sergiotarxz/nuttx
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Documentation: Remove all tail spaces from *.rst and *.html

Browse Source 
by the below command:
find . -type f -name '*.rst' -exec sed --in-place 's/[[:space:]]\+$//' {} \+

Signed-off-by: Xiang Xiao <xiaoxiang@xiaomi.com>
This commit is contained in:
Xiang Xiao 2020-10-19 00:48:44 +08:00 committed by Brennan Ashton
parent a066186127
commit 598e3eedb4
64 changed files with 836 additions and 836 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
Documentation/_templates/layout.html
View File

@ -32,10 +32,10 @@
<img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="{{ _('Logo') }}"/>
{% endif %}
</a>
<!-- this version selector is quite ugly, should be probably replaced by something
more modern -->
<div class="version-selector">
<select>
{% for nuttx_version in nuttx_versions %}
@ -43,7 +43,7 @@
{% endfor %}
</select>
</div>
{% include "searchbox.html" %}
{% endblock %}

4
Documentation/applications/index.rst
View File

@ -1,10 +1,10 @@
.. todo::
Applications included in ``apps`` repo should be documented here. This should also include information
on how to create a given application.
on how to create a given application.
Applications
============
NuttX ships a large number of applications covering a wide spectrum of functionality. These can be found in the `apps <https://github.com/apache/incubator-nuttx-apps>`_ repository. At the moment, these are documented in their individual README files so you can find more information at the repository.
NuttX ships a large number of applications covering a wide spectrum of functionality. These can be found in the `apps <https://github.com/apache/incubator-nuttx-apps>`_ repository. At the moment, these are documented in their individual README files so you can find more information at the repository.

4
Documentation/boards/index.rst
View File

@ -1,9 +1,9 @@
.. todo::
.. todo::
Include a full list of supported boards, organized by architecture / family / vendor.
Each board should have its own entry, a photo, brief hardware specifications, features
supported (currently working in NuttX), how to flash, special toolchains required, etc.
This will involve migrating most of the content existing currently in board README files
to RST documents here.
to RST documents here.
Supported Boards
================

46
Documentation/components/binfmt.rst
View File

@ -87,7 +87,7 @@ pointer to a write-able instance of :c:struct:`binfmt_s`.
structure is shown below:
.. code-block:: c
struct symtab_s;
struct binary_s
{
@ -137,9 +137,9 @@ pointer to a write-able instance of :c:struct:`binfmt_s`.
Where the types ``binfmt_ctor_t`` and ``binfmt_dtor_t`` define the type
of one C++ constructor or destructor:
.. code-block:: c
typedef FAR void (*binfmt_ctor_t)(void);
typedef FAR void (*binfmt_dtor_t)(void);
@ -152,20 +152,20 @@ Binary format management
.. c:function:: int register_binfmt(FAR struct binfmt_s *binfmt)
Register a loader for a binary format.
:return: This is a NuttX internal function so it follows the convention
that 0 (OK) is returned on success and a negated errno is returned on
failure.
.. c:function:: int unregister_binfmt(FAR struct binfmt_s *binfmt)
Register a loader for a binary format.
Register a loader for a binary format.
:return:
This is a NuttX internal function so it follows the convention
that 0 (OK) is returned on success and a negated errno is returned on
failure.
Basic module management
~~~~~~~~~~~~~~~~~~~~~~~
@ -193,12 +193,12 @@ Basic module management
(via :c:func:`exec_module`) and has not exited, calling this will be fatal.
However, this function must be called after the module exist. How this is
done is up to your logic. Perhaps you register it to be called by :c:func:`on_exit`?
done is up to your logic. Perhaps you register it to be called by :c:func:`on_exit`?
:return:
This is a NuttX internal function so it follows the convention that 0 (``OK``)
is returned on success and a negated ``errno`` is returned on failure.
.. c:function:: int exec_module(FAR const struct binary_s *bin);
Execute a module that has been loaded into memory by :c:func:`load_module`.
@ -209,10 +209,10 @@ Basic module management
.. tip::
The function :c:func:`exec` is a convenience function that wraps
:c:func:`load_module` and :c:func:`exec_module` into one call.
:c:func:`load_module` and :c:func:`exec_module` into one call.
``PATH`` traversal logic
~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~
.. c:function:: ENVPATH_HANDLE envpath_init(void);
@ -232,17 +232,17 @@ Basic module management
that may subsequently be used in calls to :c:func:`envpath_next` and
:c:func:`envpath_release`. On error, a ``NULL`` handle value will be returned.
The most likely cause of an error would be that there is no value
associated with the ``PATH`` variable.
associated with the ``PATH`` variable.
.. c:function:: FAR char *envpath_next(ENVPATH_HANDLE handle, FAR const char *relpath)
Traverse all possible values in the PATH variable in attempt to find the
full path to an executable file when only a relative path is provided.
full path to an executable file when only a relative path is provided.
:param handle: The handle value returned by :c:func:`envpath_init`.
:param relpath: The relative path to the file to be found.
:return:
:return:
On success, a non-``NULL`` pointer to a null-terminated string is provided.
This is the full path to a file that exists in the file system.
This function will verify that the file exists (but will not verify that it is marked executable).
@ -262,7 +262,7 @@ Release all resources set aside by envpath_init when the
handle value was created. The handle value is invalid on
return from this function. Attempts to all :c:func:`envpath_next`
or :c:func:`envpath_release` with such a stale handle will result
in undefined (i.e., not good) behavior.
in undefined (i.e., not good) behavior.
:param handle: The handle value returned by :c:func:`envpath_init`.
@ -297,7 +297,7 @@ Symbol Table Data Structures
Describes one entry in the symbol table.
.. code-block:: c
struct symtab_s
{
FAR const char *sym_name; /* A pointer to the symbol name string */
@ -326,16 +326,16 @@ Symbol Table Function Interfaces
to ``nsyms``.
:return:
A reference to the symbol table entry if an entry with the matching name is found; NULL is returned if the entry is not found.
A reference to the symbol table entry if an entry with the matching name is found; NULL is returned if the entry is not found.
.. c:function:: FAR const struct symtab_s *symtab_findorderedbyname(FAR const struct symtab_s *symtab, FAR const char *name, int nsyms);
Find the symbol in the symbol table with the matching name.
This version assumes that table ordered with respect to symbol name.
This version assumes that table ordered with respect to symbol name.
:return:
A reference to the symbol table entry if an entry with
the matching name is found; NULL is returned if the entry is not found.
the matching name is found; NULL is returned if the entry is not found.
.. c:function:: FAR const struct symtab_s *symtab_findbyvalue(FAR const struct symtab_s *symtab, FAR void *value, int nsyms);
@ -343,12 +343,12 @@ Symbol Table Function Interfaces
Find the symbol in the symbol table whose value closest
(but not greater than), the provided value. This version assumes
that table is not ordered with respect to symbol name and, hence,
access time will be linear with respect to ``nsyms``.
access time will be linear with respect to ``nsyms``.
:return:
A reference to the symbol table entry if an entry with the matching
name is found; ``NULL`` is returned if the entry is not found.
Configuration Variables
=======================

2
Documentation/components/drivers/character/index.rst
View File

@ -50,7 +50,7 @@ Character device drivers have these properties:
.. toctree::
:caption: Supported Drivers
serial.rst
touchscreen.rst
analog.rst

52
Documentation/components/drivers/character/timer.rst
View File

@ -16,7 +16,7 @@ locations:
reside in ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>*
directory for the specific processor *<architecture>* and for
the specific *<chip>* timer peripheral devices.
There are two ways to enable Timer Support along with the Timer Example. The first is faster and simpler. Just run the following command to use a ready config file with timer support and example included. You need to check if there's a timer config file for your specific chip. You may check it at the specific board's path: ``/boards/<arch>/<chip>/<variant>/config``.
.. code-block:: console
@ -49,30 +49,30 @@ Enabling the Timer Support and Example in ``menuconfing``
- [x] Timer example
Below the option, it is possible to manually configure some parameters as the standard timer device path, the timeout, the sample rate in which the counter will be read, the number of samples to be executed, and other parameters.
Below the option, it is possible to manually configure some parameters as the standard timer device path, the timeout, the sample rate in which the counter will be read, the number of samples to be executed, and other parameters.
Timer Example
--------------
The previously selected example will basically consult the timer status, set a timer alarm interval, set a timer signal handler function to be notified at the alarm, which only increments a variable, and then it will start the timer. The application will periodically consult the timer status at the sample rate previously configured through the ``menuconfig`` to follow the time left until the timer expires. After the samples have been read, the application stops de timer.
The `example code <https://github.com/apache/incubator-nuttx-apps/blob/master/examples/timer/timer_main.c#ref-example>`_ may be explored, its path is at ``/examples/timer/timer_main.c`` in the apps' repository.
The `example code <https://github.com/apache/incubator-nuttx-apps/blob/master/examples/timer/timer_main.c#ref-example>`_ may be explored, its path is at ``/examples/timer/timer_main.c`` in the apps' repository.
In NuttX, the timer driver is a character driver and when a chip supports multiple timers, each one is accessible through its respective file in ``/dev`` directory. Each timer is registered using a unique numeric identifier (i.e. ``/dev/timer0``, ``/dev/timer1``, ...).
In NuttX, the timer driver is a character driver and when a chip supports multiple timers, each one is accessible through its respective file in ``/dev`` directory. Each timer is registered using a unique numeric identifier (i.e. ``/dev/timer0``, ``/dev/timer1``, ...).
Use the following command to run the example:
.. code-block:: console
`nsh> timer`
This command will use the timer 0. To use the others, specify it through a parameter (where x is the timer number):
.. code-block:: console
`nsh> timer -d /dev/timerx`
Application Level Interface
`nsh> timer -d /dev/timerx`
Application Level Interface
----------------------------
The first necessary thing to be done in order to use the timer driver in an application is to include the header file for the NuttX timer driver. It contains the Application Level Interface to the timer driver. To do so, include:
@ -87,7 +87,7 @@ At an application level, the timer functionalities may be accessed through ``ioc
.. c:macro:: TCIOC_START
.. c:macro:: TCIOC_STOP
.. c:macro:: TCIOC_GETSTATUS
.. c:macro:: TCIOC_SETTIMEOUT
.. c:macro:: TCIOC_SETTIMEOUT
.. c:macro:: TCIOC_NOTIFICATION
.. c:macro:: TCIOC_MAXTIMEOUT
@ -166,9 +166,9 @@ The ``TCIOC_START`` command calls the ``start`` operation, which is described be
The start operation configures the timer, enables the interrupt if ``TCIOC_NOTIFICATION`` has already been called and finally starts the timer.
:return: A Linux System Error Code for failing or 0 for success.
:return: A Linux System Error Code for failing or 0 for success.
This command may be used like so:
This command may be used like so:
.. code-block:: c
@ -192,9 +192,9 @@ The ``TCIOC_STOP`` command calls the ``stop`` operation, which is described belo
The stop operation stops the timer and disables the interrupt.
:return: A Linux System Error Code for failing or 0 for success.
:return: A Linux System Error Code for failing or 0 for success.
This command may be used like so:
This command may be used like so:
.. code-block:: c
@ -218,11 +218,11 @@ The ``TCIOC_GETSTATUS`` command calls the ``getstatus`` operation, which is desc
The getstatus operation gathers the timer's current information.
:param status: A writable pointer to a struct ``timer_status_s``. This struct contains 3 fields: ``flags`` (``uint32_t``), ``timeout`` (``uint32_t``) and ``timeleft`` (``uint32_t``). Bit 0 from `flags` indicates the timer's status, 1 indicates that the timer is running, zero it is stopped. Bit 1 from `flags` indicates if there's a callback registered. The `timeout` indicates the time interval that was configured to trigger an alarm, it is in microseconds. The `timeleft` interval indicates how many microseconds it's missing to trigger the alarm. The following snippet demonstrates how to use it and how to access these fields.
:param status: A writable pointer to a struct ``timer_status_s``. This struct contains 3 fields: ``flags`` (``uint32_t``), ``timeout`` (``uint32_t``) and ``timeleft`` (``uint32_t``). Bit 0 from `flags` indicates the timer's status, 1 indicates that the timer is running, zero it is stopped. Bit 1 from `flags` indicates if there's a callback registered. The `timeout` indicates the time interval that was configured to trigger an alarm, it is in microseconds. The `timeleft` interval indicates how many microseconds it's missing to trigger the alarm. The following snippet demonstrates how to use it and how to access these fields.
:return: A Linux System Error Code for failing or 0 for success.
:return: A Linux System Error Code for failing or 0 for success.
This command may be used like so:
This command may be used like so:
.. code-block:: c
@ -250,11 +250,11 @@ The ``TCIOC_SETTIMEOUT`` command calls the ``settimeout`` operation, which is de
The getstatus operation sets a timeout interval to trigger the alarm and then trigger an interrupt. It defines the timer interval in which the handler will be called.
:param timeout: An argument of type ``uint32_t`` with the timeout value in microseconds.
:param timeout: An argument of type ``uint32_t`` with the timeout value in microseconds.
:return: A Linux System Error Code for failing or 0 for success.
:return: A Linux System Error Code for failing or 0 for success.
This command may be used like so:
This command may be used like so:
.. code-block:: c
@ -273,11 +273,11 @@ This command may be used like so:
.. c:macro:: TCIOC_NOTIFICATION
The ``TCIOC_NOTIFICATION`` is used to configure the timer callback to notify the application via a signal when the timer expires. This command calls the ``setcallback`` operation. Which will not be described here, since the application does not set a callback directly. Instead, the user should configure a signal handler to catch notifications, and then, configure a timer notifier to notify and to signal the previously configured signal handler. For a better performance, a separate pthread may be configured to wait on sigwaitinfo() for timer events.
The ``TCIOC_NOTIFICATION`` is used to configure the timer callback to notify the application via a signal when the timer expires. This command calls the ``setcallback`` operation. Which will not be described here, since the application does not set a callback directly. Instead, the user should configure a signal handler to catch notifications, and then, configure a timer notifier to notify and to signal the previously configured signal handler. For a better performance, a separate pthread may be configured to wait on sigwaitinfo() for timer events.
In any case, this command expects a read-only pointer to a struct `timer_notify_s`. This struct contains 2 fields: ``pid`` (``pid_t``), that indicates the ID of the task/thread to receive the signal and ``event`` (``struct sigevent``), which describes the way a task will be notified.
This command may be used like so:
This command may be used like so:
.. code-block:: c
@ -303,12 +303,12 @@ The ``TCIOC_MAXTIMEOUT`` command calls the ``maxtimeout`` operation, which is de
.. c:function:: int maxtimeout(uint32_t *status)
The maxtimeout operation gets the maximum timeout value that can be configured.
The maxtimeout operation gets the maximum timeout value that can be configured.
:param maxtimeout: A writable pointer to a variable of ``uint32_t`` type in which the value will be stored.
:return: A Linux System Error Code for failing or 0 for success.
:return: A Linux System Error Code for failing or 0 for success.
This command may be used like so:
This command may be used like so:
.. code-block:: c
@ -330,4 +330,4 @@ This command may be used like so:
Those snippets were taken from the Example which provides a great resource to demonstrate how to use those ``ioctl`` commands.

6
Documentation/components/drivers/index.rst
View File

@ -1,7 +1,7 @@
==============
Device Drivers
==============
NuttX supports a variety of device drivers, which can be broadly
divided in three classes:
@ -10,8 +10,8 @@ divided in three classes:
character/index.rst
block/index.rst
special/index.rst
special/index.rst
.. note::
Device driver support depends on the *in-memory*, *pseudo*
file system that is enabled by default.

2
Documentation/components/drivers/special/index.rst
View File

@ -21,7 +21,7 @@ following section.
.. toctree::
:caption: Supported Drivers
spi.rst
i2c.rst
ethernet.rst

4
Documentation/components/index.rst
View File

@ -1,8 +1,8 @@
OS Components
=============
NuttX is very feature-rich RTOS and is thus composed of various different subsystems. The following sections explain how each of these main RTOS components work and can be used. For detailed documentation on the specific API used in this case, you can head to the :doc:`reference <../reference/index>`.
NuttX is very feature-rich RTOS and is thus composed of various different subsystems. The following sections explain how each of these main RTOS components work and can be used. For detailed documentation on the specific API used in this case, you can head to the :doc:`reference <../reference/index>`.
.. toctree::
:maxdepth: 2
:caption: Contents:

14
Documentation/components/nsh/builtin.rst
View File

@ -135,17 +135,17 @@ registers the ``hello_main()`` application in the ``builtin``'s
that in ``apps/examples/hello/Makefile`` is abstracted below:
#. First, the ``Makefile`` includes ``apps/Make.defs``::
include $(APPDIR)/Make.defs
This defines a macro called ``REGISTER`` that adds data to the
*builtin* header files::
define REGISTER
@echo "Register: $1"
@echo "{ \"$1\", $2, $3, $4 }," >> "$(APPDIR)/builtin/builtin_list.h"
@echo "EXTERN int $4(int argc, char *argv[]);" >> "$(APPDIR)/builtin/builtin_proto.h"
endef
endef
When this macro runs, you will see the output in the build
"``Register: hello``", that is a sure sign that the registration was
@ -154,21 +154,21 @@ that in ``apps/examples/hello/Makefile`` is abstracted below:
#. The make file then defines the application name (``hello``), the task
priority (default), and the stack size that will be allocated in the
task runs (2K)::
APPNAME = hello
PRIORITY = SCHED_PRIORITY_DEFAULT
STACKSIZE = 2048
#. And finally, the ``Makefile`` invokes the ``REGISTER`` macro to added
the ``hello_main()`` builtin application. Then, when the system build
completes, the ``hello`` command can be executed from the NSH command
line. When the ``hello`` command is executed, it will start the task
with entry point ``hello_main()`` with the default priority and with
a stack size of 2K::
context:
$(call REGISTER,$(APPNAME),$(PRIORITY),$(STACKSIZE),$(APPNAME)_main)
**Other Uses of Built-In Application.** The primary purpose of builtin
applications is to support command line execution of applications from

28
Documentation/components/nsh/commands.rst
View File

@ -406,7 +406,7 @@ examples:
#. Using ``export`` to promote an NSH variable to an environment
variable::
nsh> env
PATH=/bin
@ -417,7 +417,7 @@ examples:
nsh> export foo
nsh> env
PATH=/bin
foo=bar
foo=bar
A group-wide environment variable is created with the same
value as the local NSH variable; the local NSH variable is
@ -428,12 +428,12 @@ examples:
environment variable of the same name and same value.
#. Using ``export`` to set an environment variable::
nsh> export dog poop
nsh> env
PATH=/bin
foo=bar
dog=poop
dog=poop
The ``export`` command is not supported by NSH unless both
``CONFIG_NSH_VARS=y`` and ``CONFIG_DISABLE_ENVIRON``\ is not set.
@ -452,7 +452,7 @@ example::
total used free largest
Mem: 4194288 1591552 2602736 2601584
nsh>
**Where:**
======= ======================================
@ -477,7 +477,7 @@ whose IP address is identified by ``<ip-address>``.
=================== ============================================
``-f <local-path>`` The file will be saved relative to the current working directory unless <local-path> is provided.
``-n`` Selects text ("netascii") transfer mode (default).
``-b`` Selects binary ("octet") transfer mode
``-b`` Selects binary ("octet") transfer mode
=================== ============================================
Show Usage Command Usage (help)
@ -509,7 +509,7 @@ character device
================= ==================================
``skip=<bytes>`` Will skip <bytes> number of bytes from the beginning.
``count=<bytes>`` Will stop after dumping <bytes> number of bytes.
``count=<bytes>`` Will stop after dumping <bytes> number of bytes.
================= ==================================
The ``skip`` and ``count`` options are only available if
@ -529,9 +529,9 @@ supported:
#. With one or no arguments, ``ifconfig`` will shows the current
configuration of the network and, perhaps, the status of
Ethernet device::
ifconfig
ifconfig [nic_name]
ifconfig [nic_name]
As an example::
@ -545,7 +545,7 @@ supported:
#. If both the network interface name and an IP address are
supplied as arguments, then ``ifconfig`` will set the address
of the Ethernet device::
ifconfig nic_name ip_address
#. Other forms *to be provided*
@ -553,7 +553,7 @@ supported:
.. note:: This commands depends upon having the *procfs* file system
configured into the system. The *procfs* file system must also
have been mounted with a command like::
nsh> mount -t procfs /proc
Take a network down (ifdown)
@ -820,7 +820,7 @@ accesses (mh), or 32-bit access (mw). In each case,
``<hex-address>=<hex-value>`` Read the value, then write <hex-value> to the location.
``<hex-byte-count>`` Perform the mb, mh, or mw operation on a total of
<hex-byte-count> bytes, increment the <hex-address>
appropriately after each access.
appropriately after each access.
============================= ==============================================
**Example**::
@ -1225,7 +1225,7 @@ names in the *pseudo* file system.
TESTFILE.TXT
nsh>
Remove a Directory (rmdir)
Remove a Directory (rmdir)
**************************
**Command Syntax**::
@ -1541,7 +1541,7 @@ output is the same as -s.
``-v`` Print the kernel version
``-m`` Print the machine hardware name
``-i`` Print the machine platform name
``-p`` Print "unknown"
``-p`` Print "unknown"
========== ========================================
Unset an Environment Variable (unset)

444
Documentation/components/nsh/config.rst
View File

@ -29,10 +29,10 @@ Command Depends on Configuration Can Be Disabl
``addroute`` ``CONFIG_NET`` && ``CONFIG_NET_ROUTE`` ``CONFIG_NSH_DISABLE_ADDROUTE``
``arp`` ``CONFIG_NET`` && ``CONFIG_NET_ARP`` ``CONFIG_NSH_DISABLE_ARP``
``base64dec`` ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_BASE64DEC``
``CONFIG_CODECS_BASE64``
``CONFIG_CODECS_BASE64``
``base64enc`` ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_BASE64ENC``
``CONFIG_CODECS_BASE64``
``basename`` . ``CONFIG_NSH_DISABLE_BASENAME``
``basename`` . ``CONFIG_NSH_DISABLE_BASENAME``
``break`` ! ``CONFIG_NSH_DISABLESCRIPT`` && .
! ``CONFIG_NSH_DISABLE_LOOPS``  
``cat`` ``CONFIG_NSH_DISABLE_CAT`` .
@ -59,9 +59,9 @@ Command Depends on Configuration Can Be Disabl
``help`` [#3]_ ``CONFIG_NSH_DISABLE_HELP`` .
``hexdump`` ``CONFIG_NSH_DISABLE_HEXDUMP`` .
``ifconfig`` ``CONFIG_NET`` && ``CONFIG_FS_PROCFS`` && ``CONFIG_NSH_DISABLE_IFCONFIG``
! ``CONFIG_FS_PROCFS_EXCLUDE_NET``
! ``CONFIG_FS_PROCFS_EXCLUDE_NET``
``ifdown`` ``CONFIG_NET`` && ``CONFIG_FS_PROCFS`` && ``CONFIG_NSH_DISABLE_IFUPDOWN``
! ``CONFIG_FS_PROCFS_EXCLUDE_NET``
! ``CONFIG_FS_PROCFS_EXCLUDE_NET``
``ifup`` ``CONFIG_NET`` && ``CONFIG_FS_PROCFS`` &&
! ``CONFIG_FS_PROCFS_EXCLUDE_NET`` ``CONFIG_NSH_DISABLE_IFUPDOWN``
``insmod`` ``CONFIG_MODULE`` ``CONFIG_NSH_DISABLE_MODCMDS``
@ -70,37 +70,37 @@ Command Depends on Configuration Can Be Disabl
``CONFIG_SCHED_IRQMONITOR``
``kill`` ``CONFIG_NSH_DISABLE_KILL`` .
``losetup`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_LOSETUP``
``CONFIG_DEV_LOOP``
``CONFIG_DEV_LOOP``
``ln`` ``CONFIG_PSEUDOFS_SOFTLINKS`` ``CONFIG_NSH_DISABLE_LN``
``ls`` ``CONFIG_NSH_DISABLE_LS`` .
``lsmod`` ``CONFIG_MODULE`` && ``CONFIG_FS_PROCFS`` ``CONFIG_NSH_DISABLE_MODCMDS``
&& |br|
! ``CONFIG_FS_PROCFS_EXCLUDE_MODULE``
! ``CONFIG_FS_PROCFS_EXCLUDE_MODULE``
``md5`` ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_MD5``
``CONFIG_CODECS_HASH_MD5``
``CONFIG_CODECS_HASH_MD5``
``mb,mh,mw`` . ``CONFIG_NSH_DISABLE_MB``, |br|
``CONFIG_NSH_DISABLE_MH``, |br|
``CONFIG_NSH_DISABLE_MW``
``mkdir`` (! ``CONFIG_DISABLE_MOUNTPOINT`` \|\| ``CONFIG_NSH_DISABLE_MKDIR``
! ``CONFIG_DISABLE_PSEUDOFS_OPERATIONS``)
! ``CONFIG_DISABLE_PSEUDOFS_OPERATIONS``)
``mkfatfs`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_MKFATFS``
``CONFIG_FSUTILS_MKFATFS``
``mkfifo`` ``CONFIG_PIPES`` && ``CONFIG_NSH_DISABLE_MKFIFO``
``CONFIG_DEV_FIFO_SIZE`` > 0
``CONFIG_DEV_FIFO_SIZE`` > 0
``mkrd`` ! ``CONFIG_DISABLE_MOUNTPOINT`` ``CONFIG_NSH_DISABLE_MKRD``
``mount`` ! ``CONFIG_DISABLE_MOUNTPOINT`` ``CONFIG_NSH_DISABLE_MOUNT``
``mv`` ! ``CONFIG_DISABLE_MOUNTPOINT`` \|\| ``CONFIG_NSH_DISABLE_MV``
! ``CONFIG_DISABLE_PSEUDOFS_OPERATIONS``
! ``CONFIG_DISABLE_PSEUDOFS_OPERATIONS``
``nfsmount`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_NFSMOUNT``
``CONFIG_NET`` && ``CONFIG_NFS``
``CONFIG_NET`` && ``CONFIG_NFS``
``nslookup`` ``CONFIG_LIBC_NETDB`` && ``CONFIG_NSH_DISABLE_NSLOOKUP``
``CONFIG_NETDB_DNSCLIENT``
``CONFIG_NETDB_DNSCLIENT``
``passwd`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_PASSWD``
``CONFIG_NSH_LOGIN_PASSWD``
``CONFIG_NSH_LOGIN_PASSWD``
``pmconfig`` ``CONFIG_PM`` ``CONFIG_NSH_DISABLE_PMCONFIG``
``poweroff`` ``CONFIG_BOARDCTL_POWEROFF`` ``CONFIG_NSH_DISABLE_POWEROFF``
``ps`` ``CONFIG_FS_PROCFS`` && ``CONFIG_NSH_DISABLE_PS``
! ``CONFIG_FS_PROCFS_EXCLUDE_PROC``
! ``CONFIG_FS_PROCFS_EXCLUDE_PROC``
``put`` ``CONFIG_NET`` && ``CONFIG_NET_UDP`` && ``CONFIG_NSH_DISABLE_PUT``
``MTU >= 558`` [#1]_, [#2]_
``pwd`` ! ``CONFIG_DISABLE_ENVIRON`` ``CONFIG_NSH_DISABLE_PWD``
@ -120,22 +120,22 @@ Command Depends on Configuration Can Be Disabl
``CONFIG_NET_IPv6``)
``rptun`` ``CONFIG_RPTUN`` ``CONFIG_NSH_DISABLE_RPTUN``
``set`` ``CONFIG_NSH_VARS`` \|\| ``CONFIG_NSH_DISABLE_SET``
! ``CONFIG_DISABLE_ENVIRON``
! ``CONFIG_DISABLE_ENVIRON``
``shutdown`` ``CONFIG_BOARDCTL_POWEROFF`` \|\| ``CONFIG_NSH_DISABLE_SHUTDOWN``
``CONFIG_BOARD_RESET``
``sleep`` . ``CONFIG_NSH_DISABLE_SLEEP``
``source`` ``CONFIG_FILE_STREAM`` && ``CONFIG_NSH_DISABLE_SOURCE``
! ``CONFIG_NSH_DISABLESCRIPT``
``telnetd`` ``CONFIG_NSH_TELNET`` ``CONFIG_NSH_DISABLE_TELNETD``
! ``CONFIG_NSH_DISABLESCRIPT``
``telnetd`` ``CONFIG_NSH_TELNET`` ``CONFIG_NSH_DISABLE_TELNETD``
``test`` ! ``CONFIG_NSH_DISABLESCRIPT`` ``CONFIG_NSH_DISABLE_TEST``
``time`` . ``CONFIG_NSH_DISABLE_TIME``
``truncate`` ! ``CONFIG_DISABLE_MOUNTPOINT`` ``CONFIG_NSH_DISABLE_TRUNCATE``
``umount`` ! ``CONFIG_DISABLE_MOUNTPOINT`` ``CONFIG_NSH_DISABLE_UMOUNT``
``uname`` . ``CONFIG_NSH_DISABLE_UNAME``
``unset`` ``CONFIG_NSH_VARS`` \|\| ``CONFIG_NSH_DISABLE_UNSET``
! ``CONFIG_DISABLE_ENVIRON``
! ``CONFIG_DISABLE_ENVIRON``
``urldecode`` ! ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_URLDECODE``
``CONFIG_CODECS_URLCODE``
``CONFIG_CODECS_URLCODE``
``urlencode`` ! ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_URLENCODE``
``CONFIG_CODECS_URLCODE``
``useradd`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_USERADD``
@ -172,226 +172,226 @@ The behavior of NSH can be modified with the following settings in the
``boards/<arch>/<chip>/<board>/defconfig`` file:
=================================== ==================================
Configuration Description
Configuration Description
=================================== ==================================
``CONFIG_NSH_READLINE`` Selects the minimal implementation of ``readline()``.
This minimal implementation provides on backspace for command
line editing. It expects some minimal VT100 command support from the terminal.
``CONFIG_NSH_CLE`` Selects the more extensive, EMACS-like command line editor.
Select this option only if (1) you don't mind a modest increase
in the FLASH footprint, and (2) you work with a terminal that
supports extensive VT100 editing commands. Selecting this option
will add probably 1.5-2KB to the FLASH footprint.
``CONFIG_NSH_BUILTIN_APPS`` Support external registered, "builtin" applications that can
be executed from the NSH command line (see apps/README.txt for
more information). This required ``CONFIG_BUILTIN`` to enable
NuttX support for "builtin" applications.
``CONFIG_NSH_FILEIOSIZE`` Size of a static I/O buffer used for file access (ignored if there
is no file system). Default is 1024.
``CONFIG_NSH_STRERROR`` ``strerror(errno)`` makes more readable output but
``strerror()`` is very large and will not be used unless this
setting is *y*. This setting depends upon the ``strerror()``
having been enabled with ``CONFIG_LIBC_STRERROR``.
``CONFIG_NSH_LINELEN`` The maximum length of one command line and of one output line.
Default: 80
``CONFIG_NSH_DISABLE_SEMICOLON`` By default, you can enter multiple NSH commands on a line
with each command separated by a semicolon. You can disable this
feature to save a little memory on FLASH challenged platforms.
``CONFIG_NSH_READLINE`` Selects the minimal implementation of ``readline()``.
This minimal implementation provides on backspace for command
line editing. It expects some minimal VT100 command support from the terminal.
``CONFIG_NSH_CLE`` Selects the more extensive, EMACS-like command line editor.
Select this option only if (1) you don't mind a modest increase
in the FLASH footprint, and (2) you work with a terminal that
supports extensive VT100 editing commands. Selecting this option
will add probably 1.5-2KB to the FLASH footprint.
``CONFIG_NSH_BUILTIN_APPS`` Support external registered, "builtin" applications that can
be executed from the NSH command line (see apps/README.txt for
more information). This required ``CONFIG_BUILTIN`` to enable
NuttX support for "builtin" applications.
``CONFIG_NSH_FILEIOSIZE`` Size of a static I/O buffer used for file access (ignored if there
is no file system). Default is 1024.
``CONFIG_NSH_STRERROR`` ``strerror(errno)`` makes more readable output but
``strerror()`` is very large and will not be used unless this
setting is *y*. This setting depends upon the ``strerror()``
having been enabled with ``CONFIG_LIBC_STRERROR``.
``CONFIG_NSH_LINELEN`` The maximum length of one command line and of one output line.
Default: 80
``CONFIG_NSH_DISABLE_SEMICOLON`` By default, you can enter multiple NSH commands on a line
with each command separated by a semicolon. You can disable this
feature to save a little memory on FLASH challenged platforms.
Default: n
``CONFIG_NSH_CMDPARMS`` If selected, then the output from commands, from file applications,
and from NSH built-in commands can be used as arguments to other
commands. The entity to be executed is identified by
``CONFIG_NSH_CMDPARMS`` If selected, then the output from commands, from file applications,
and from NSH built-in commands can be used as arguments to other
commands. The entity to be executed is identified by
enclosing the command line in back quotes. For example::
set FOO `myprogram $BAR`
will execute the program named ``myprogram`` passing it the
value of the environment variable ``BAR``. The value of the
environment variable ``FOO`` is then set output of ``myprogram``
on ``stdout``. Because this feature commits significant
resources, it is disabled by default. The ``CONFIG_NSH_CMDPARMS`` interim
output will be retained in a temporary file. Full path to a
directory where temporary files can be created is taken from
``CONFIG_LIBC_TMPDIR`` and it defaults to ``/tmp`` if
``CONFIG_LIBC_TMPDIR`` is not set.
``CONFIG_NSH_MAXARGUMENTS`` The maximum number of NSH command arguments. Default: 6
``CONFIG_NSH_ARGCAT`` Support concatenation of strings with environment variables or
set FOO `myprogram $BAR`
will execute the program named ``myprogram`` passing it the
value of the environment variable ``BAR``. The value of the
environment variable ``FOO`` is then set output of ``myprogram``
on ``stdout``. Because this feature commits significant
resources, it is disabled by default. The ``CONFIG_NSH_CMDPARMS`` interim
output will be retained in a temporary file. Full path to a
directory where temporary files can be created is taken from
``CONFIG_LIBC_TMPDIR`` and it defaults to ``/tmp`` if
``CONFIG_LIBC_TMPDIR`` is not set.
``CONFIG_NSH_MAXARGUMENTS`` The maximum number of NSH command arguments. Default: 6
``CONFIG_NSH_ARGCAT`` Support concatenation of strings with environment variables or
command output. For example::
set FOO XYZ
set BAR 123
set FOOBAR ABC_${FOO}_${BAR}
would set the environment variable ``FOO`` to ``XYZ``,
``BAR`` to ``123`` and ``FOOBAR`` to ``ABC_XYZ_123``. If
``CONFIG_NSH_ARGCAT`` is not selected, then a slightly small
FLASH footprint results but then also only simple environment
variables like ``$FOO`` can be used on the command line.
``CONFIG_NSH_VARS`` By default, there are no internal NSH variables. NSH will use OS
environment variables for all variable storage. If this option,
NSH will also support local NSH variables. These variables are,
for the most part, transparent and work just like the OS
environment variables. The difference is that when you
create new tasks, all of environment variables are
inherited by the created tasks. NSH local variables are not.
If this option is enabled (and ``CONFIG_DISABLE_ENVIRON`` is not),
then a new command called 'export' is enabled. The export
command works very must like the set command except that is
operates on environment variables. When CONFIG_NSH_VARS
would set the environment variable ``FOO`` to ``XYZ``,
``BAR`` to ``123`` and ``FOOBAR`` to ``ABC_XYZ_123``. If
``CONFIG_NSH_ARGCAT`` is not selected, then a slightly small
FLASH footprint results but then also only simple environment
variables like ``$FOO`` can be used on the command line.
``CONFIG_NSH_VARS`` By default, there are no internal NSH variables. NSH will use OS
environment variables for all variable storage. If this option,
NSH will also support local NSH variables. These variables are,
for the most part, transparent and work just like the OS
environment variables. The difference is that when you
create new tasks, all of environment variables are
inherited by the created tasks. NSH local variables are not.
If this option is enabled (and ``CONFIG_DISABLE_ENVIRON`` is not),
then a new command called 'export' is enabled. The export
command works very must like the set command except that is
operates on environment variables. When CONFIG_NSH_VARS
is enabled, there are changes in the behavior of certain commands.
See following :ref:`table <nsh_vars_table>`.
``CONFIG_NSH_QUOTE`` Enables back-slash quoting of certain characters within the
command. This option is useful for the case where an NSH script
is used to dynamically generate a new NSH script. In that case,
commands must be treated as simple text strings without
interpretation of any special characters. Special characters
such as ``$``, :literal:`\``, ``"``, and others must be
retained intact as part of the test string. This option is
currently only available is ``CONFIG_NSH_ARGCAT`` is also
selected.
``CONFIG_NSH_NESTDEPTH`` The maximum number of nested ``if-then[-else]-fi`` <#conditional>`__
sequences that are permissible. Default: 3
``CONFIG_NSH_DISABLESCRIPT`` This can be set to *y* to suppress support for scripting.
This setting disables the ```sh`` <#cmdsh>`__,
```test`` <#cmdtest>`__, and ```[`` <#cmtest>`__ commands and
the ```if-then[-else]-fi`` <#conditional>`__
construct. This would only be set on systems where a minimal
footprint is a necessity and scripting is not.
``CONFIG_NSH_DISABLE_ITEF`` If scripting is enabled, then then this option can be selected
to suppress support for ``if-then-else-fi`` sequences in
scripts. This would only be set on systems where some minimal
``CONFIG_NSH_QUOTE`` Enables back-slash quoting of certain characters within the
command. This option is useful for the case where an NSH script
is used to dynamically generate a new NSH script. In that case,
commands must be treated as simple text strings without
interpretation of any special characters. Special characters
such as ``$``, :literal:`\``, ``"``, and others must be
retained intact as part of the test string. This option is
currently only available is ``CONFIG_NSH_ARGCAT`` is also
selected.
``CONFIG_NSH_NESTDEPTH`` The maximum number of nested ``if-then[-else]-fi`` <#conditional>`__
sequences that are permissible. Default: 3
``CONFIG_NSH_DISABLESCRIPT`` This can be set to *y* to suppress support for scripting.
This setting disables the ```sh`` <#cmdsh>`__,
```test`` <#cmdtest>`__, and ```[`` <#cmtest>`__ commands and
the ```if-then[-else]-fi`` <#conditional>`__
construct. This would only be set on systems where a minimal
footprint is a necessity and scripting is not.
``CONFIG_NSH_DISABLE_ITEF`` If scripting is enabled, then then this option can be selected
to suppress support for ``if-then-else-fi`` sequences in
scripts. This would only be set on systems where some minimal
scripting is required but ``if-then-else-fi`` is not.
``CONFIG_NSH_DISABLE_LOOPS`` If scripting is enabled, then then this option can be selected
suppress support ``for while-do-done`` and
``until-do-done`` sequences in scripts. This would only be set
on systems where some minimal scripting is required but looping
is not.
``CONFIG_NSH_DISABLEBG`` This can be set to *y* to suppress support for background
commands. This setting disables the ```nice`` <#cmdoverview>`__
command prefix and the ```&`` <#cmdoverview>`__ command
suffix. This would only be set on systems where a minimal footprint
is a necessity and background command execution is not.
``CONFIG_NSH_MMCSDMINOR`` If the architecture supports an MMC/SD slot and if the NSH
architecture specific logic is present, this option will provide
the MMC/SD minor number, i.e., the MMC/SD block driver will be
registered as ``/dev/mmcsd``\ *N* where *N* is the minor number.
Default is zero.
``CONFIG_NSH_ROMFSETC`` Mount a ROMFS file system at ``/etc`` and provide a startup
script at ``/etc/init.d/rcS``.
The default startup script will mount a FAT FS RAMDISK at
``/tmp`` but the logic is `easily extensible <#startupscript>`__.
``CONFIG_NSH_CONSOLE`` If ``CONFIG_NSH_CONSOLE`` is set to *y*, then a serial console
front-end is selected.
Normally, the serial console device is a UART and RS-232
interface. However, if ``CONFIG_USBDEV`` is defined,
then a USB serial device may, instead, be used if the one of
the following are defined:
- ``CONFIG_PL2303`` and ``CONFIG_PL2303_CONSOLE``.
Sets up the Prolifics PL2303 emulation as a console device
at ``/dev/console``.
- ``CONFIG_CDCACM`` and ``CONFIG_CDCACM_CONSOLE``.
Sets up the CDC/ACM serial device as a console device at
``/dev/console``.
- ``CONFIG_NSH_USBCONSOLE``. If defined, then an arbitrary USB
device may be used to as the NSH console. In this case,
``CONFIG_NSH_USBCONDEV`` must be defined to indicate which
USB device to use as the console. The advantage of
using a device other that ``/dev/console`` is that
normal debug output can then use ``/dev/console`` while NSH
uses ``CONFIG_NSH_USBCONDEV``.
``CONFIG_NSH_USBCONDEV``. If ``CONFIG_NSH_USBCONSOLE`` is
set to 'y', then ``CONFIG_NSH_USBCONDEV`` must also be set to select the USB
device used to support the NSH console. This should be set to
the quoted name of a readable/write-able USB driver
such as: ``CONFIG_NSH_USBCONDEV="/dev/ttyACM0"``.
If there are more than one USB slots, then a USB device minor
number may also need to be provided:
- ``CONFIG_NSH_UBSDEV_MINOR``: The minor device number of the USB device. Default: 0
If USB tracing is enabled (``CONFIG_USBDEV_TRACE``), then
NSH will initialize USB tracing as requested by the following.
Default: Only USB errors are traced.
- ``CONFIG_NSH_USBDEV_TRACEINIT``: Show initialization events
- ``CONFIG_NSH_USBDEV_TRACECLASS``: Show class driver events
- ``CONFIG_NSH_USBDEV_TRACETRANSFERS``: Show data transfer events
- ``CONFIG_NSH_USBDEV_TRACECONTROLLER``: Show controller events
- ``CONFIG_NSH_USBDEV_TRACEINTERRUPTS``: Show interrupt-related events.
``CONFIG_NSH_DISABLE_LOOPS`` If scripting is enabled, then then this option can be selected
suppress support ``for while-do-done`` and
``until-do-done`` sequences in scripts. This would only be set
on systems where some minimal scripting is required but looping
is not.
``CONFIG_NSH_DISABLEBG`` This can be set to *y* to suppress support for background
commands. This setting disables the ```nice`` <#cmdoverview>`__
command prefix and the ```&`` <#cmdoverview>`__ command
suffix. This would only be set on systems where a minimal footprint
is a necessity and background command execution is not.
``CONFIG_NSH_MMCSDMINOR`` If the architecture supports an MMC/SD slot and if the NSH
architecture specific logic is present, this option will provide
the MMC/SD minor number, i.e., the MMC/SD block driver will be
registered as ``/dev/mmcsd``\ *N* where *N* is the minor number.
Default is zero.
``CONFIG_NSH_ROMFSETC`` Mount a ROMFS file system at ``/etc`` and provide a startup
script at ``/etc/init.d/rcS``.
The default startup script will mount a FAT FS RAMDISK at
``/tmp`` but the logic is `easily extensible <#startupscript>`__.
``CONFIG_NSH_CONSOLE`` If ``CONFIG_NSH_CONSOLE`` is set to *y*, then a serial console
front-end is selected.
Normally, the serial console device is a UART and RS-232
interface. However, if ``CONFIG_USBDEV`` is defined,
then a USB serial device may, instead, be used if the one of
the following are defined:
- ``CONFIG_PL2303`` and ``CONFIG_PL2303_CONSOLE``.
Sets up the Prolifics PL2303 emulation as a console device
at ``/dev/console``.
- ``CONFIG_CDCACM`` and ``CONFIG_CDCACM_CONSOLE``.
Sets up the CDC/ACM serial device as a console device at
``/dev/console``.
- ``CONFIG_NSH_USBCONSOLE``. If defined, then an arbitrary USB
device may be used to as the NSH console. In this case,
``CONFIG_NSH_USBCONDEV`` must be defined to indicate which
USB device to use as the console. The advantage of
using a device other that ``/dev/console`` is that
normal debug output can then use ``/dev/console`` while NSH
uses ``CONFIG_NSH_USBCONDEV``.
``CONFIG_NSH_USBCONDEV``. If ``CONFIG_NSH_USBCONSOLE`` is
set to 'y', then ``CONFIG_NSH_USBCONDEV`` must also be set to select the USB
device used to support the NSH console. This should be set to
the quoted name of a readable/write-able USB driver
such as: ``CONFIG_NSH_USBCONDEV="/dev/ttyACM0"``.
If there are more than one USB slots, then a USB device minor
number may also need to be provided:
- ``CONFIG_NSH_UBSDEV_MINOR``: The minor device number of the USB device. Default: 0
If USB tracing is enabled (``CONFIG_USBDEV_TRACE``), then
NSH will initialize USB tracing as requested by the following.
Default: Only USB errors are traced.
- ``CONFIG_NSH_USBDEV_TRACEINIT``: Show initialization events
- ``CONFIG_NSH_USBDEV_TRACECLASS``: Show class driver events
- ``CONFIG_NSH_USBDEV_TRACETRANSFERS``: Show data transfer events
- ``CONFIG_NSH_USBDEV_TRACECONTROLLER``: Show controller events
- ``CONFIG_NSH_USBDEV_TRACEINTERRUPTS``: Show interrupt-related events.
``CONFIG_NSH_ALTCONDEV`` and If ``CONFIG_NSH_CONSOLE`` is set ``CONFIG_NSH_CONDEV``
to *y*, then ``CONFIG_NSH_ALTCONDEV`` may also
be selected to enable use of an alternate character device to
support the NSH console. If ``CONFIG_NSH_ALTCONDEV`` is
selected, then ``CONFIG_NSH_CONDEV`` holds the
quoted name of a readable/write-able character
driver such as: ``CONFIG_NSH_CONDEV="/dev/ttyS1"``.
This is useful, for example, to separate the NSH command line
from the system console when the system console is used to provide
debug output. Default: ``stdin`` and ``stdout`` (probably
"``/dev/console``")
- **NOTE 1:** When any other device other than
``/dev/console`` is used for a user interface, (1) linefeeds
(``\n``) will not be expanded to carriage return / linefeeds
(``\r\n``). You will need to configure your terminal
program to account for this.
And (2) input is not automatically echoed so you
will have to turn local echo on.
- **NOTE 2:** This option forces the console of all sessions to
use NSH_CONDEV. Hence, this option only makes sense for a
system that supports only a single session. This option
is, in particular, incompatible with Telnet
sessions because each Telnet session must use a different
console device.
``CONFIG_NSH_TELNET`` If ``CONFIG_NSH_TELNET`` is set to *y*, then a TELNET server
front-end is selected. When this option is provided, you may log
into NuttX remotely using telnet in order to access NSH.
``CONFIG_NSH_ARCHINIT`` Set ``CONFIG_NSH_ARCHINIT`` if your board provides architecture
specific initialization via the board-specific function
``board_app_initialize()``. This function will be called early in
NSH initialization to allow board logic to do such things as
configure MMC/SD slots.
to *y*, then ``CONFIG_NSH_ALTCONDEV`` may also
be selected to enable use of an alternate character device to
support the NSH console. If ``CONFIG_NSH_ALTCONDEV`` is
selected, then ``CONFIG_NSH_CONDEV`` holds the
quoted name of a readable/write-able character
driver such as: ``CONFIG_NSH_CONDEV="/dev/ttyS1"``.
This is useful, for example, to separate the NSH command line
from the system console when the system console is used to provide
debug output. Default: ``stdin`` and ``stdout`` (probably
"``/dev/console``")
- **NOTE 1:** When any other device other than
``/dev/console`` is used for a user interface, (1) linefeeds
(``\n``) will not be expanded to carriage return / linefeeds
(``\r\n``). You will need to configure your terminal
program to account for this.
And (2) input is not automatically echoed so you
will have to turn local echo on.
- **NOTE 2:** This option forces the console of all sessions to
use NSH_CONDEV. Hence, this option only makes sense for a
system that supports only a single session. This option
is, in particular, incompatible with Telnet
sessions because each Telnet session must use a different
console device.
``CONFIG_NSH_TELNET`` If ``CONFIG_NSH_TELNET`` is set to *y*, then a TELNET server
front-end is selected. When this option is provided, you may log
into NuttX remotely using telnet in order to access NSH.
``CONFIG_NSH_ARCHINIT`` Set ``CONFIG_NSH_ARCHINIT`` if your board provides architecture
specific initialization via the board-specific function
``board_app_initialize()``. This function will be called early in
NSH initialization to allow board logic to do such things as
configure MMC/SD slots.
=================================== ==================================
.. _nsh_vars_table:
================== =================================== =============================================
CMD w/o ``CONFIG_NSH_VARS`` w/``CONFIG_NSH_VARS``
CMD w/o ``CONFIG_NSH_VARS`` w/``CONFIG_NSH_VARS``
================== =================================== =============================================
``set <a> <b>`` Set environment variable <a> to <b> Set NSH variable <a> to <b> (Unless the NSH variable has been *promoted* via
``set <a> <b>`` Set environment variable <a> to <b> Set NSH variable <a> to <b> (Unless the NSH variable has been *promoted* via
``export``, in which case the env ironment variable of the same name is set to <b>).
``set`` Causes an error. Lists all NSH variables.
``unset <a>`` Unsets environment variable <a> Unsets both environment variable *and* NSH variable with and name <a>
``export <a> <b>`` Causes an error, Unsets NSH variable <a>. Sets environment variable <a> to <b>.
``export <a>`` Causes an error. Sets environment variable <a> to the value of NSH variable <a> (or "" if the
NSH variable has not been set). Unsets NSH local variable <a>.
``env`` Lists all environment variables Lists all environment variables (*only*)
``set`` Causes an error. Lists all NSH variables.
``unset <a>`` Unsets environment variable <a> Unsets both environment variable *and* NSH variable with and name <a>
``export <a> <b>`` Causes an error, Unsets NSH variable <a>. Sets environment variable <a> to <b>.
``export <a>`` Causes an error. Sets environment variable <a> to the value of NSH variable <a> (or "" if the
NSH variable has not been set). Unsets NSH local variable <a>.
``env`` Lists all environment variables Lists all environment variables (*only*)
================== =================================== =============================================

6
Documentation/components/nsh/customizing.rst
View File

@ -58,7 +58,7 @@ The NSH initialization function, ``nsh_initialize()``, be found in
The ROMFS image is, itself, just built into the firmware. By default,
this ``rcS`` start-up script contains the following logic::
# Create a RAMDISK and mount it at XXXRDMOUNTPOINTXXX
mkrd -m XXXMKRDMINORXXX -s XXMKRDSECTORSIZEXXX XXMKRDBLOCKSXXX
@ -80,12 +80,12 @@ The NSH initialization function, ``nsh_initialize()``, be found in
Default: ``/etc``
By default, the substituted values would yield an ``rcS`` file like::
# Create a RAMDISK and mount it at /tmp
mkrd -m 1 -s 512 1024
mkfatfs /dev/ram1
mount -t vfat /dev/ram1 /tmp
mount -t vfat /dev/ram1 /tmp
This script will, then:

4
Documentation/components/nsh/index.rst
View File

@ -5,11 +5,11 @@ NuttShell (NSH)
The NuttShell is a very complete shell system to be used in NuttX, similar to bash and other similar options. It supports a rich set of included commands, scripting and the ability to run your own applications as "builtin" (part of the same NuttX binary). NSH is implemented as an application where most of the functionality is part of the library called `nshlib`.
As such, NSH is completely optional and can be disabled so that NuttX directly starts a given task instead of the main ``nsh`` application.
.. toctree::
:maxdepth: 2
:caption: Contents
nsh.rst
commands.rst
config.rst

16
Documentation/components/nsh/installation.rst
View File

@ -61,39 +61,39 @@ behave as follows at NSH start-up time:
- NSH will create a read-only RAM disk (a ROM disk), containing a tiny
ROMFS file system containing the following::
`--init.d/
`-- rcS
Where ``rcS`` is the NSH start-up script.
- NSH will then mount the ROMFS file system at ``/etc``, resulting in::
|--dev/
| `-- ram0
`--etc/
`--init.d/
`-- rcS
`-- rcS
- By default, the contents of ``rcS`` script are::
# Create a RAMDISK and mount it at /tmp
mkrd -m 1 -s 512 1024
mkfatfs /dev/ram1
mount -t vfat /dev/ram1 /tmp
- NSH will execute the script at ``/etc/init.d/rcS`` at start-up
(before the first NSH prompt). After execution of the script, the
root FS will look like::
|--dev/
| |-- ram0
| `-- ram1
|--etc/
| `--init.d/
| `-- rcS
`--tmp/
`--tmp/
**Example Configurations**. Here are some configurations that have
``CONFIG_NSH_ROMFSETC=y`` in the NuttX configuration file. They might

56
Documentation/components/nsh/login.rst
View File

@ -46,13 +46,13 @@ credentials at login time:
#. The simplest implementation simply uses fixed login credentials and
is selected with::
CONFIG_NSH_LOGIN_FIXED=y
CONFIG_NSH_LOGIN_FIXED=y
The fixed login credentials are selected via::
CONFIG_NSH_LOGIN_USERNAME=admin
CONFIG_NSH_LOGIN_PASSWORD="Administrator"
CONFIG_NSH_LOGIN_PASSWORD="Administrator"
This is not very flexible since there can be only one user and the
password is fixed in the FLASH image. This option is also not very
@ -61,22 +61,22 @@ credentials at login time:
#. NSH can also be configured to defer the entire user credential
verification to platform-specific logic with this setting::
CONFIG_NSH_LOGIN_PLATFORM=y
CONFIG_NSH_LOGIN_PLATFORM=y
In this case, NSH will call a platform-specific function to perform
the verification of user credentials. The platform-specific logic
must provide a function with the following prototype:
.. code-block:: c
int platform_user_verify(FAR const char *username, FAR const char *password);
which is prototyped an described in ``apps/include/nsh.h`` and which
may be included like:
.. code-block:: c
#include <apps/nsh.h>
An appropriate place to implement this function might be in the
@ -85,7 +85,7 @@ credentials at login time:
#. A final option is to use a password file contained encrypted password
information. This final option is selected with the following and
described in more detail in the following paragraph::
CONFIG_NSH_LOGIN_PASSWD=y
Password Files
@ -126,17 +126,17 @@ The password file logic requires a few additional settings:
#. The size of dynamically allocated and freed buffer that is used for
file access::
CONFIG_FSUTILS_PASSWD_IOBUFFER_SIZE=512
#. And the 128-bit encryption key. The password file currently uses the
Tiny Encryption Algorithm (TEA), but could be extended to use
something more powerful.
CONFIG_FSUTILS_PASSWD_KEY1=0x12345678
CONFIG_FSUTILS_PASSWD_KEY2=0x9abcdef0
CONFIG_FSUTILS_PASSWD_KEY3=0x12345678
CONFIG_FSUTILS_PASSWD_KEY4=0x9abcdef0
CONFIG_FSUTILS_PASSWD_KEY4=0x9abcdef0
Password can only be decrypted with access to this key. Note that this
key could potentially be fished out of your FLASH image, but without any
@ -178,27 +178,27 @@ ROMFS file system, passwords, and login prompts. First, I make these
changes to that configuration.
#. Disable logins:
.. code-block:: diff
- CONFIG_NSH_CONSOLE_LOGIN=y
+ # CONFIG_NSH_CONSOLE_LOGIN is not set
# CONFIG_NSH_TELNET_LOGIN is not set
# CONFIG_NSH_TELNET_LOGIN is not set
#. Move the password file to a write-able file system:
.. code-block:: diff
- CONFIG_FSUTILS_PASSWD_PATH="/etc/passwd"
+ CONFIG_FSUTILS_PASSWD_PATH="/tmp/passwd"
#. Make the password file modifiable
.. code-block:: diff
- CONFIG_FSUTILS_PASSWD_READONLY=y
# CONFIG_FSUTILS_PASSWD_READONLY is not set
Now rebuild the simulation. No login should be required to enter the
shell and you should find the ```useradd`` <#cmduseradd>`__,
```userdel`` <#cmduserdel>`__, and ```passwd`` <#cmdpasswd>`__ commands
@ -228,21 +228,21 @@ Then create/re-create the ``nsh_romfsimg.h`` file as described below.
#. The content on the ``nsh_romfsimg.h`` header file is generated from a
template directory structure. Create the directory structure::
mkdir etc
mkdir etc/init.d
mkdir etc/init.d
And copy your existing startup script into ``etc/init.c`` as ``rcS``.
#. Save your new password file in the ``etc/`` directory as ``passwd``.
#. Create the new ROMFS image::
genromfs -f romfs_img -d etc -V MyVolName
genromfs -f romfs_img -d etc -V MyVolName
#. Convert the ROMFS image to a C header file::
xxd -i romfs_img >nsh_romfsimg.h
xxd -i romfs_img >nsh_romfsimg.h
#. Edit ``nsh_romfsimg.h``: Mark both data definitions as ``const`` so
that the data will be stored in FLASH.

38
Documentation/components/nsh/nsh.rst
View File

@ -93,19 +93,19 @@ commands forms:
Simple command ``<cmd>``
Command with re-directed output ``<cmd> > <file> <cmd> >> <file>``
Background command ``<cmd> &``
Re-directed background command ``<cmd> > <file> & <cmd> >> <file> &``
Re-directed background command ``<cmd> > <file> & <cmd> >> <file> &``
=============================== ======================================
Where:
* ``<cmd>`` is any one of the simple commands listed later.
* ``<file>`` is the full or relative path to any writable object in the file system name space (file or character driver). Such objects will be referred to simply as files throughout this document.
* ``<file>`` is the full or relative path to any writable object in the file system name space (file or character driver). Such objects will be referred to simply as files throughout this document.
``nice`` **'d Background Commands**. NSH executes at the
mid-priority (128). Backgrounded commands can be made to execute
at higher or lower priorities using ``nice``::
[nice [-d <niceness>>]] <cmd> [> <file>|>> <file>] [&]
[nice [-d <niceness>>]] <cmd> [> <file>|>> <file>] [&]
Where ``<niceness>`` is any value between -20 and 19 where lower
(more negative values) correspond to higher priorities. The
@ -123,9 +123,9 @@ significant resources, they are disabled by default.
commands can be used as arguments to other commands. The entity
to be executed is identified by enclosing the command line in
back quotes. For example,
.. code-block:: bash
set FOO myprogram $BAR
Will execute the program named ``myprogram`` passing it the
@ -135,9 +135,9 @@ significant resources, they are disabled by default.
- ``CONFIG_NSH_ARGCAT``: Support concatenation of strings
with environment variables or command output. For example:
.. code-block:: bash
set FOO XYZ
set BAR 123
set FOOBAR ABC_${FOO}_${BAR}
@ -191,20 +191,20 @@ the ```sh`` <#cmdsh>`__ command).
- ``while-do-done``: Execute ``[sequence of <cmd>]`` as long
as ``<cmd>`` has an exit status of zero. The syntax is as
follows:
.. code-block:: bash
while <cmd>
do
[sequence of <cmd>]
done
done
- ``until-do-done``: Execute ``[sequence of <cmd>]`` as long
as ``<cmd>`` has a non-zero exit status. The syntax is as
follows:
.. code-block::
until <cmd>
do
[sequence of <cmd>]
@ -228,7 +228,7 @@ Built-In Variables
====== ====================================================
``$?`` The result of the last simple command execution. |br|
On backgrounded commands, this variable holds only |br|
the result of spawning the background command.
the result of spawning the background command.
====== ====================================================
Current Working Directory
@ -274,23 +274,23 @@ NSH to behave as follows at NSH startup time:
- NSH will create a read-only RAM disk (a ROM disk), containing a
tiny ROMFS file system containing the following::
`--init.d/
`-- rcS
Where rcS is the NSH start-up script.
- NSH will then mount the ROMFS file system at ``/etc``,
resulting in::
|--dev/
| `-- ram0
`--etc/
`--init.d/
`-- rcS
`-- rcS
- By default, the contents of rcS script are::
# Create a RAMDISK and mount it at XXXRDMOUNTPOINTXXX
mkrd -m 1 -s 512 1024
@ -300,14 +300,14 @@ NSH to behave as follows at NSH startup time:
- NSH will execute the script at ``/etc/init.d/rcS`` at start-up
(before the first NSH prompt). After execution of the script,
the root FS will look like::
|--dev/
| |-- ram0
| `-- ram1
|--etc/
| `--init.d/
| `-- rcS
`--tmp/
`--tmp/
**Modifying the ROMFS Image**. The contents of the ``/etc``
directory are retained in the file ``apps/nshlib/nsh_romfsimg.h``

22
Documentation/components/nxflat.rst
View File

@ -77,7 +77,7 @@ Limitations
of file system but will require copying of all NXFLAT executables to RAM.
- **GCC/ARM/Cortex-M3/4 Only**:
At present, the NXFLAT toolchain is only available for ARM and Cortex-M3/4 (thumb2) targets.
At present, the NXFLAT toolchain is only available for ARM and Cortex-M3/4 (thumb2) targets.
- **Read-Only Data in RAM**:
With older GCC compilers (at least up to 4.3.3), read-only data must
@ -96,10 +96,10 @@ Limitations
- **Globally Scoped Function Function Pointers**:
If a function pointer is taken to a statically defined function,
then (at least for ARM) GCC will generate a relocation that NXFLAT
cannot handle. The workaround is make all such functions global in
cannot handle. The workaround is make all such functions global in
scope. A fix would involve a change to the GCC compiler as described
in Appendix B.
in Appendix B.
- **Special Handling of Callbacks**:
Callbacks through function pointers must be avoided or, when
then cannot be avoided, handled very specially. The reason
@ -109,7 +109,7 @@ Limitations
will be unable to correctly access data memory. Special logic
is in place to handle some NuttX callbacks: Signal callbacks
and watchdog timer callbacks. But other callbacks (like those
used with qsort() must be avoided in an NXFLAT module.
used with qsort() must be avoided in an NXFLAT module.
Supported Processors
--------------------
@ -217,7 +217,7 @@ files. In particular, the CSV files:
interface, and
#. ``nuttx/libc/libc.csv`` that describes the NuttX C library interface.
#. ``nuttx/libc/math.cvs`` that descirbes any math library.
::
USAGE: ./mksymtab <cvs-file> <symtab-file>
@ -254,21 +254,21 @@ example).
* Target 2:
.. code-block:: makefile
hello-thunk.S: hello.r1
mknxflat -o $@ $^
* Target 3:
.. code-block:: makefile
hello.r2: hello-thunk.S
hello.r2: hello-thunk.S
abc-nuttx-elf-ld -r -d -warn-common -T binfmt/libnxflat/gnu-nxflat-gotoff.ld -no-check-sections -o $@ hello.o hello-thunk.o
* Target 4:
.. code-block:: makefile
hello: hello.r2
ldnxflat -e main -s 2048 -o $@ $^

178
Documentation/components/nxgraphics/appendix.rst
View File

@ -14,22 +14,22 @@ the RTOS. User callable functions must be part of a library that can be
linked against user applications. This user callable interfaces are
provided in sub-directories under ``nuttx/libnx``.
``libnx/nx``
``libnx/nx``
Common callable interfaces that are, logically, part of both nxmu and
nxsu.
``graphics/nxglib`` and ``libnx/nxglib``
``graphics/nxglib`` and ``libnx/nxglib``
The NuttX tiny graphics library. The directory contains generic
utilities support operations on primitive graphics objects and logic
to rasterize directly into a framebuffer or through an LCD driver
interface. It has no concept of windows (other than the one,
framebuffer or LCD window).
``graphics/nxbe``
``graphics/nxbe``
This is the *back-end* of a tiny windowing system. It can be used
with either of two front-ends to complete a windowing system (see
``nxmu`` and ``nxsu`` below). It contains most of the important
window management logic: clipping, window controls, window drawing,
etc.
``graphics/nxmu`` and ``libnx/nxmu``
``graphics/nxmu`` and ``libnx/nxmu``
This is the NX multi user *front end*. When combined with the generic
*back-end* (``nxbe``), it implements a multi-threaded, multi-user
windowing system. The files in this directory present the window APIs
@ -37,18 +37,18 @@ provided in sub-directories under ``nuttx/libnx``.
includes a graphics server that executes on its own thread; multiple
graphics clients then communicate with the server via a POSIX message
queue to serialize window operations from many threads.
``libnx/nxfonts``
``libnx/nxfonts``
This is where the NXFONTS implementation resides. This is a
relatively low-level set of charset set/glyph management APIs. See
``include/nuttx/nx/nxfonts.h``.
``libnx/nxtk``
``libnx/nxtk``
This is where the NXTOOLKIT implementation resides. This toolkit is
built on top of NX and works with the multi-user NX front-end. See
``include/nuttx/nx/nxtk.h``.
``apps/graphics/NxWidgets``
``apps/graphics/NxWidgets``
The `NxWidgets <NxWidgets.html>`__ code is provided as a separate
package provided in the ``apps/`` repository.
``graphics/nxterm``
``graphics/nxterm``
The NxTerm driver is built on top of NX and works with the multi-user
NX front-end. See ``include/nuttx/nx/nxterm.h``.
@ -58,9 +58,9 @@ NX Configuration Options
General Configuration Settings
------------------------------
``CONFIG_NX``
``CONFIG_NX``
Enables overall support for graphics library and NX
``CONFIG_NX_RAMBACKED``
``CONFIG_NX_RAMBACKED``
Enables RAM backed window support. If this option is selected, then
windows may be optionally created with a RAM framebuffer backing up
the window content. Rending into the window will result in rending
@ -87,21 +87,21 @@ General Configuration Settings
NXGL Configuration Settings
---------------------------
``CONFIG_NX_NPLANES``:
``CONFIG_NX_NPLANES``:
Some YUV color formats requires support for multiple planes, one for
each color component. Unless you have such special hardware, this
value should be undefined or set to 1.
``CONFIG_NX_DISABLE_1BPP``, ``CONFIG_NX_DISABLE_2BPP``, ``CONFIG_NX_DISABLE_4BPP``, ``CONFIG_NX_DISABLE_8BPP`` ``CONFIG_NX_DISABLE_16BPP``, ``CONFIG_NX_DISABLE_24BPP``, and ``CONFIG_NX_DISABLE_32BPP``:
``CONFIG_NX_DISABLE_1BPP``, ``CONFIG_NX_DISABLE_2BPP``, ``CONFIG_NX_DISABLE_4BPP``, ``CONFIG_NX_DISABLE_8BPP`` ``CONFIG_NX_DISABLE_16BPP``, ``CONFIG_NX_DISABLE_24BPP``, and ``CONFIG_NX_DISABLE_32BPP``:
NX supports a variety of pixel depths. You can save some memory by
disabling support for unused color depths.
``CONFIG_NX_PACKEDMSFIRST``:
``CONFIG_NX_PACKEDMSFIRST``:
If a pixel depth of less than 8-bits is used, then NX needs to know
if the pixels pack from the MS to LS or from LS to MS
``CONFIG_NX_LCDDRIVER``:
``CONFIG_NX_LCDDRIVER``:
By default, NX builds to use a framebuffer driver (see
``include/nuttx/video/fb.h``). If this option is defined, NX will
build to use an LCD driver (see ``include/nuttx/lcd/lcd.h``).
``CONFIG_NX_ANTIALIASING``:
``CONFIG_NX_ANTIALIASING``:
Enable support for anti-aliasing when rendering lines as various
orientations. This option is only available for use with frame buffer
drivers and only with 16-, 24-, or 32-bit RGB color formats.
@ -109,11 +109,11 @@ NXGL Configuration Settings
Configuration Settings
----------------------
``CONFIG_NX_XYINPUT``:
``CONFIG_NX_XYINPUT``:
Build in support for an X/Y input such as a mouse or a touscreen.
``CONFIG_NX_KBD``:
``CONFIG_NX_KBD``:
Build in support of keypad/keyboard input.
``CONFIG_NX_WRITEONLY``:
``CONFIG_NX_WRITEONLY``:
Define if the underlying graphics device does not support read
operations. Automatically defined if ``CONFIG_NX_LCDDRIVER`` and
``CONFIG_LCD_NOGETRUN`` are defined.
@ -121,11 +121,11 @@ Configuration Settings
NX Server Configuration Settings
--------------------------------
``CONFIG_NX_BLOCKING``
``CONFIG_NX_BLOCKING``
Open the client message queues in blocking mode. In this case,
``nx_eventhandler()`` will not return until a message is received and
processed.
``CONFIG_NX_MXSERVERMSGS`` and ``CONFIG_NX_MXCLIENTMSGS``
``CONFIG_NX_MXSERVERMSGS`` and ``CONFIG_NX_MXCLIENTMSGS``
Specifies the maximum number of messages that can fit in the message
queues. No additional resources are allocated, but this can be set to
prevent flooding of the client or server with too many messages
@ -135,17 +135,17 @@ NX Server Configuration Settings
NXTK Configuration Settings
---------------------------
``CONFIG_NXTK_BORDERWIDTH``:
``CONFIG_NXTK_BORDERWIDTH``:
Specifies the width of the border (in pixels) used with framed
windows. The default is 4.
``CONFIG_NXTK_BORDERCOLOR1``, ``CONFIG_NXTK_BORDERCOLOR2``, and ``CONFIG_NXTK_BORDERCOLOR3``:
``CONFIG_NXTK_BORDERCOLOR1``, ``CONFIG_NXTK_BORDERCOLOR2``, and ``CONFIG_NXTK_BORDERCOLOR3``:
Specify the colors of the border used with framed windows.
``CONFIG_NXTK_BORDERCOLOR2``
``CONFIG_NXTK_BORDERCOLOR2``
The shadow side color and so is normally darker.
``CONFIG_NXTK_BORDERCOLOR3``
``CONFIG_NXTK_BORDERCOLOR3``
The shiny side color and so is normally brighter. The default is
medium, dark, and light grey, respectively
``CONFIG_NXTK_AUTORAISE``:
``CONFIG_NXTK_AUTORAISE``:
If set, a window will be raised to the top if the mouse position is
over a visible portion of the window. Default: A mouse button must be
clicked over a visible portion of the window.
@ -153,58 +153,58 @@ NXTK Configuration Settings
NXFONTS Configuration Settings
------------------------------
``CONFIG_NXFONTS_CHARBITS``:
``CONFIG_NXFONTS_CHARBITS``:
The number of bits in the character set. Current options are only 7
and 8. The default is 7.
``CONFIG_NXFONT_SANS17X22``:
``CONFIG_NXFONT_SANS17X22``:
This option enables support for a tiny, 17x22 san serif font (font
``ID FONTID_SANS17X22`` == 14).
``CONFIG_NXFONT_SANS20X26``:
``CONFIG_NXFONT_SANS20X26``:
This option enables support for a tiny, 20x26 san serif font (font
``ID FONTID_SANS20X26`` == 15).
``CONFIG_NXFONT_SANS23X27``:
``CONFIG_NXFONT_SANS23X27``:
This option enables support for a tiny, 23x27 san serif font (font
``ID FONTID_SANS23X27`` == 1).
``CONFIG_NXFONT_SANS22X29``:
``CONFIG_NXFONT_SANS22X29``:
This option enables support for a small, 22x29 san serif font (font
``ID FONTID_SANS22X29`` == 2).
``CONFIG_NXFONT_SANS28X37``:
``CONFIG_NXFONT_SANS28X37``:
This option enables support for a medium, 28x37 san serif font (font
``ID FONTID_SANS28X37`` == 3).
``CONFIG_NXFONT_SANS39X48``:
``CONFIG_NXFONT_SANS39X48``:
This option enables support for a large, 39x48 san serif font (font
``ID FONTID_SANS39X48`` == 4).
``CONFIG_NXFONT_SANS17X23B``:
``CONFIG_NXFONT_SANS17X23B``:
This option enables support for a tiny, 17x23 san serif bold font
(font ``ID FONTID_SANS17X23B`` == 16).
``CONFIG_NXFONT_SANS20X27B``:
``CONFIG_NXFONT_SANS20X27B``:
This option enables support for a tiny, 20x27 san serif bold font
(font ``ID FONTID_SANS20X27B`` == 17).
``CONFIG_NXFONT_SANS22X29B``:
``CONFIG_NXFONT_SANS22X29B``:
This option enables support for a small, 22x29 san serif bold font
(font ID ``FONTID_SANS22X29B`` == 5).
``CONFIG_NXFONT_SANS28X37B``:
``CONFIG_NXFONT_SANS28X37B``:
This option enables support for a medium, 28x37 san serif bold font
(font ID ``FONTID_SANS28X37B`` == 6).
``CONFIG_NXFONT_SANS40X49B``:
``CONFIG_NXFONT_SANS40X49B``:
This option enables support for a large, 40x49 san serif bold font
(font ID ``FONTID_SANS40X49B`` == 7).
``CONFIG_NXFONT_SERIF22X29``:
``CONFIG_NXFONT_SERIF22X29``:
This option enables support for a small, 22x29 font (with serifs)
(font ID ``FONTID_SERIF22X29`` == 8).
``CONFIG_NXFONT_SERIF29X37``:
``CONFIG_NXFONT_SERIF29X37``:
This option enables support for a medium, 29x37 font (with serifs)
(font ID ``FONTID_SERIF29X37`` == 9).
``CONFIG_NXFONT_SERIF38X48``:
``CONFIG_NXFONT_SERIF38X48``:
This option enables support for a large, 38x48 font (with serifs)
(font ID ``FONTID_SERIF38X48`` == 10).
``CONFIG_NXFONT_SERIF22X28B``:
``CONFIG_NXFONT_SERIF22X28B``:
This option enables support for a small, 27x38 bold font (with
serifs) (font ID ``FONTID_SERIF22X28B`` == 11).
``CONFIG_NXFONT_SERIF27X38B``:
``CONFIG_NXFONT_SERIF27X38B``:
This option enables support for a medium, 27x38 bold font (with
serifs) (font ID ``FONTID_SERIF27X38B`` == 12).
``CONFIG_NXFONT_SERIF38X49B``:
``CONFIG_NXFONT_SERIF38X49B``:
This option enables support for a large, 38x49 bold font (with
serifs) (font ID ``FONTID_SERIF38X49B`` == 13).
@ -213,24 +213,24 @@ NxTerm Configuration Settings
General NxTerm settings.
``CONFIG_NXTERM``:
``CONFIG_NXTERM``:
Enables building of the NxTerm driver.
NxTerm output text/graphics options:
``CONFIG_NXTERM_BPP``:
``CONFIG_NXTERM_BPP``:
Currently, NxTerm supports only a single pixel depth. This
configuration setting must be provided to support that single pixel
depth. Default: The smallest enabled pixel depth. (see
``CONFIG_NX_DISABLE_*BPP``)
``CONFIG_NXTERM_CURSORCHAR``:
``CONFIG_NXTERM_CURSORCHAR``:
The bitmap code to use as the cursor. Default '_'
``CONFIG_NXTERM_MXCHARS``:
``CONFIG_NXTERM_MXCHARS``:
NxTerm needs to remember every character written to the console so
that it can redraw the window. This setting determines the size of
some internal memory allocations used to hold the character data.
Default: 128.
``CONFIG_NXTERM_CACHESIZE``:
``CONFIG_NXTERM_CACHESIZE``:
NxTerm supports caching of rendered fonts. This font caching is
required for two reasons: (1) First, it improves text performance,
but more importantly (2) it preserves the font memory. Since the NX
@ -251,26 +251,26 @@ NxTerm output text/graphics options:
server task. ``CONFIG_NXTERM_CACHESIZE`` should be larger than
``CONFIG_MQ_MAXMSGSIZE`` in any event.
``CONFIG_NXTERM_LINESEPARATION``:
``CONFIG_NXTERM_LINESEPARATION``:
This the space (in rows) between each row of test. Default: 0
``CONFIG_NXTERM_NOWRAP``:
``CONFIG_NXTERM_NOWRAP``:
By default, lines will wrap when the test reaches the right hand side
of the window. This setting can be defining to change this behavior
so that the text is simply truncated until a new line is encountered.
NxTerm input options:
``CONFIG_NXTERM_NXKBDIN``:
``CONFIG_NXTERM_NXKBDIN``:
Take input from the NX keyboard input callback. By default, keyboard
input is taken from stdin (``/dev/console``). If this option is set,
then the interface\ ``nxterm_kdbin()`` is enabled. That interface may
be driven by window callback functions so that keyboard input *only*
goes to the top window.
``CONFIG_NXTERM_KBDBUFSIZE``:
``CONFIG_NXTERM_KBDBUFSIZE``:
If ``CONFIG_NXTERM_NXKBDIN`` is enabled, then this value may be used
to define the size of the per-window keyboard input buffer. Default:
16
``CONFIG_NXTERM_NPOLLWAITERS``:
``CONFIG_NXTERM_NPOLLWAITERS``:
The number of threads that can be waiting for read data available.
Default: 4
@ -323,25 +323,25 @@ yournew font in a similar fashion:
4. ``include/nuttx/nx/nxfonts.h``. Add you new font as a possible
system default font:
.. code-block:: c
#if defined(CONFIG_NXFONT_SANS23X27)
# define NXFONT_DEFAULT FONTID_SANS23X27
#elif defined(CONFIG_NXFONT_MYFONT)
# define NXFONT_DEFAULT FONTID_MYFONT
#endif
Then define the actual font ID. Make sure that the font ID value is
unique:
.. code-block:: c
#if defined(CONFIG_NXFONT_SANS23X27)
# define NXFONT_DEFAULT FONTID_SANS23X27
#elif defined(CONFIG_NXFONT_MYFONT)
# define NXFONT_DEFAULT FONTID_MYFONT
#endif
#endif
New Add the font to the NX build system. There are several files that
you have to modify to do this. Look how the build system uses the font
@ -352,29 +352,29 @@ CONFIG_NXFONT_SANS23X27 for examaples:
with the *bdf-converter* program. Notice ``NXFONTS_FONTID=2``; this
must be set to the same font ID value that you defined in the
``include/nuttx/nx/nxfonts.h`` file.
.. code-block:: makefile
genfontsources:
ifeq ($(CONFIG_NXFONT_SANS23X27),y)
@$(MAKE) -C nxfonts -f Makefile.sources NXFONTS_FONTID=1 EXTRAFLAGS=$(EXTRAFLAGS)
endif
ifeq ($(CONFIG_NXFONT_MYFONT),y)
@$(MAKE) -C nxfonts -f Makefile.sources NXFONTS_FONTID=2 EXTRAFLAGS=$(EXTRAFLAGS)
endif
endif
6. ``nuttx/graphics/nxfonts/Make.defs``. Set the make variable
``NXFSET_CSRCS``. ``NXFSET_CSRCS`` determines the name of the font C
file to build when ``NXFONTS_FONTID=2``:
.. code-block:: makefile
ifeq ($(CONFIG_NXFONT_SANS23X27),y)
NXFSET_CSRCS += nxfonts_bitmaps_sans23x27.c
endif
ifeq ($(CONFIG_NXFONT_MYFONT),y)
NXFSET_CSRCS += nxfonts_bitmaps_myfont.c
endif
endif
7. ``nuttx/graphics/nxfonts/Makefile.sources``. This is the Makefile
used in step 5 that will actually generate the font C file. So, given
@ -382,9 +382,9 @@ CONFIG_NXFONT_SANS23X27 for examaples:
auto-generated variable and function names and (again) the name of
the autogenerated file to create (this must be the same name that was
used in ``nuttx/graphics/nxfonts/Make.defs``):
.. code-block:: makefile
ifeq ($(NXFONTS_FONTID),1)
NXFONTS_PREFIX := g_sans23x27_
GEN_CSRC = nxfonts_bitmaps_sans23x27.c
@ -393,21 +393,21 @@ CONFIG_NXFONT_SANS23X27 for examaples:
NXFONTS_PREFIX := g_myfont_
GEN_CSRC = nxfonts_bitmaps_myfont.c
endif
8. ``graphics/nxfonts/nxfonts_bitmaps.c``. This is the file that
contains the generic font structures. It is used as a "template&qout;
file by ``nuttx/graphics/nxfonts/Makefile.sources``\ to create your
customized font data set at build time.
.. code-block:: c
#if NXFONTS_FONTID == 1
# include "nxfonts_sans23x27.h"
#elif NXFONTS_FONTID == 2
# include "nxfonts_myfont.h"
#else
# error "No font ID specified"
#endif
#endif
Where ``nxfonts_myfont.h`` is the NuttX font file that we generated
in step 2 using the *bdf-converter* tool.
@ -419,9 +419,9 @@ CONFIG_NXFONT_SANS23X27 for examaples:
Note that the lookup is based on the font ID that was defined in step
4. The new font information needs to be added to data structures used
by that function:
.. code-block:: c
#ifdef CONFIG_NXFONT_SANS23X27
extern const struct nx_fontpackage_s g_sans23x27_package;
#endif
@ -439,7 +439,7 @@ CONFIG_NXFONT_SANS23X27 for examaples:
#endif
NULL
};
NX Test Coverage
================
@ -460,10 +460,10 @@ configurations for building the simulation:
feedback. In this configuration, a very simple, simulated framebuffer
driver is used that is based upon a simple region of memory posing as
video memory. That default configuration can be built as follows::
tools/configure.sh sim:nx
make
./nuttx
./nuttx
#. The preferred configuration is at
``boards/sim/sim/sim/configs/nx11/defconfig``. This configuration
@ -471,10 +471,10 @@ configurations for building the simulation:
window as a framebuffer. This is a superior test configuration
because the X window appears at your desktop and you can see the NX
output. This preferred configuration can be built as follows::
tools/configure sim:nx11
make
./nuttx
./nuttx
*Update:* The sim target has suffered some bit-rot over the years and
so the following caveats need to be added:
@ -537,7 +537,7 @@ Function Special Setup/Notes Verified
There is a "fudge factor" that seems
to eliminate the problem, but there
could still be issues in some
configurations.
configurations.
``nxgl_circlepts`` Verified by apps/examples/nxlines. YES
``nxgl_circletraps`` Verified by apps/examples/nxlines. YES
================================ ==================================== ========
@ -569,25 +569,25 @@ Function Special Setup/Notes
``nx_openwindow()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES
``<NuttX-Directory>/.config file``
``nx_closewindow()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` YES
in the ``<NuttX-Directory>/.config`` file
in the ``<NuttX-Directory>/.config`` file
``nx_requestbkgd()`` Verified by ``apps/examples/nxtext`` and YES
``apps/examples/nxhello``.
``apps/examples/nxhello``.
``nx_releasebkgd()`` Verified by ``apps/examples/nxtext`` and YES
``apps/examples/nxhello``.
``apps/examples/nxhello``.
``nx_getposition()`` . NO
``nx_setposition()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES
``<NuttX-Directory>/.config`` file
``<NuttX-Directory>/.config`` file
``nx_setsize()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES
``<NuttX-Directory>/.config`` file
``<NuttX-Directory>/.config`` file
``nx_raise()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES
``<NuttX-Directory>/.config`` file
``<NuttX-Directory>/.config`` file
``nx_lower()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES
``<NuttX-Directory>/.config`` file
``<NuttX-Directory>/.config`` file
``nx_modal()`` . NO
``nx_setvisibility()`` Exercized using Twm4Nx YES, Informally
``nx_ishidden()`` Exercized using Twm4Nx YES, Informally
``nx_fill()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES
``<NuttX-Directory>/.config`` file
``<NuttX-Directory>/.config`` file
``nx_getrectangle()`` . YES
``nx_filltrapezoid()`` Verified by ``apps/examples/nxlines``. YES
``nx_drawline()`` by ``apps/examples/nxlines``. YES
@ -595,9 +595,9 @@ Function Special Setup/Notes
``nx_fillcircle()`` Verified by ``apps/examples/nxlines``. YES
``nx_setbgcolor()`` . YES
``nx_move()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES
``<NuttX-Directory>/.config`` file
``<NuttX-Directory>/.config`` file
``nx_bitmap()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES
``<NuttX-Directory>/.config`` file.
``<NuttX-Directory>/.config`` file.
``nx_kbdin()`` . YES
``nx_mousein()`` . YES
========================= =============================================================== ========
@ -640,7 +640,7 @@ Function Special Setup/Notes Verified
NXFONTS API Test Coverage
-------------------------
======================== ============================= ========
Function Special Setup/Notes Verified
======================== ============================= ========

14
Documentation/components/nxgraphics/index.rst
View File

@ -9,7 +9,7 @@ organization, and OS configuration options.
.. figure:: NuttXScreenShot.jpg
:align: center
**Figure 1**. This screnshot shows the final frame for the NuttX example
at ``apps/examples/nx`` running on the simulated, Linux x86 platform with
simulated framebuffer output to an X window. This picture shows to framed window
@ -152,18 +152,18 @@ and ``stderr`` and, hence, can provide the output side of NuttX console.
NX Header Files
===============
``include/nuttx/nx/nxglib.h``
``include/nuttx/nx/nxglib.h``
Describes the NXGLIB C interfaces
``include/nuttx/nx/nx.h``
``include/nuttx/nx/nx.h``
Describes the NX C interfaces
``include/nutt/nxtk.h``
``include/nutt/nxtk.h``
Describe the NXTOOLKIT C interfaces
``include/nutt/nxfont.h``
``include/nutt/nxfont.h``
Describe sthe NXFONT C interfaces
.. toctree::
:Caption: User APIs
nxgl.rst
nx.rst
nxtk.rst
@ -171,4 +171,4 @@ NX Header Files
nxcursor.rst
sample.rst
appendix.rst

56
Documentation/components/nxgraphics/nx.rst
View File

@ -38,7 +38,7 @@ These callbacks will be invoked as part of the processing performed by
.. c:struct:: nx_callback_s
.. code-block:: c
struct nx_callback_s
{
void (*redraw)(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect,
@ -70,9 +70,9 @@ start this daemon. There are two ways that this can be done:
``CONFIG_BOARD_LATE_INITIALIZE`` is defined in the configuration. Or,
the board startup logic can execute under control of the application
by calling :c:func:`boardctl` as:
.. code-block:: c
boardctl(BOARDIOC_INIT, arg)
The board initialization logic will run in either case and the simple
@ -98,7 +98,7 @@ start this daemon. There are two ways that this can be done:
waiting to accept connections from NX clients.
A negated ``errno`` value is returned on failure. The ``errno`` value
indicates the nature of the failure.
NX Server Callbacks
===================
@ -107,12 +107,12 @@ NX Server Callbacks
NX requests that the client re-draw the portion of the
window within with rectangle.
:param hwnd:
:param hwnd:
The handle created by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd`
:param rect:
The rectangle that needs to be re-drawn (in window relative
coordinates)
:param more:
:param more:
true: More re-draw requests will follow
:param arg:
User provided argument (see :c:func:`nx_openwindow`)
@ -125,7 +125,7 @@ NX Server Callbacks
The size or position of the window has changed (or the
window was just created with zero size.
:param hwnd:
:param hwnd:
The handle created by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd`
:param size:
The size of the window
@ -155,11 +155,11 @@ NX Server Callbacks
New keyboard/keypad data is available for the window.
:param hwnd:
:param hwnd:
The handle created by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd`
:param nch:
:param nch:
The number of characters that are available in ch[]
:param ch:
:param ch:
The array of characters
:param arg:
User provided argument (see :c:func:`nx_openwindow`)
@ -168,7 +168,7 @@ NX Server Callbacks
This callback is used to communicate server events to the window listener.
- ``NXEVENT_BLOCKED``: Window messages are blocked.
- ``NXEVENT_BLOCKED``: Window messages are blocked.
This callback is the response from :c:func:`nx_block`,
:c:func:`nxtk_block`. Those blocking interfaces are used
to assure that no further messages are directed to the window.
@ -180,7 +180,7 @@ NX Server Callbacks
callbacks are processed. Then the window may be safely closed.
Closing the window prior with pending callbacks can lead to bad
behavior when the callback is executed.
- ``NXEVENT_SYNCHED``: Synchronization handshake
- ``NXEVENT_SYNCHED``: Synchronization handshake
This completes the handshake started by
:c:func:`nx_synch`, or :c:func:`nxtk_synch`.
Those interfaces send a synchronization messages to the NX server
@ -190,23 +190,23 @@ NX Server Callbacks
synchronization is sometimes necessary to assure that the client and
server are working together properly.
:param hwnd:
:param hwnd:
TWindow handle of window receiving the event
:param event:
:param event:
The server event
:param arg1:
:param arg1:
User provided argument (see :c:func:`nx_openwindow`,
:c:func:`nx_requestbkgd`, or :c:func:`nxtk_opentoolbar`)
:param arg2:
:param arg2:
TUser provided argument (see :c:func:`nx_block`, :c:func:`nxtk_block`,
:c:func:`nx_synch`, or :c:func:`nxtk_synch`)
.. c:macro:: nx_run(fb)
.. code-block:: c
#define nx_run(fb) nx_runinstance(NX_DEFAULT_SERVER_MQNAME, dev)
.. c:function:: int nx_runinstance(FAR const char *mqname, FAR struct fb_vtable_s *fb)
This is the server entry point. It does not return; the
@ -227,9 +227,9 @@ NX Server Callbacks
.. c:macro:: nx_connect(cb)
.. code-block:: c
#define nx_connect(cb) nx_connectinstance(NX_DEFAULT_SERVER_MQNAME)
.. c:function:: NXHANDLE nx_connectinstance(FAR const char *svrmqname);
Open a connection from a client to the NX server. One
@ -250,8 +250,8 @@ NX Server Callbacks
:param svrmqname: The name for the server incoming message queue
:return: Success: A non-NULL handle used with subsequent NX accesses
Failure: NULL is returned and errno is set appropriately.
Failure: NULL is returned and errno is set appropriately.
.. c:function:: void nx_disconnect(NXHANDLE handle)
Disconnect a client from the NX server and/or free
@ -321,7 +321,7 @@ NX Server Callbacks
prior with pending callbacks can lead to bad behavior when the callback
is executed.
:param wnd: The window to be blocked
:param wnd: The window to be blocked
:param arg: An argument that will accompany the block messages (This is ``arg2`` in
the event callback).
@ -341,7 +341,7 @@ NX Server Callbacks
server are fully synchronized in time.
Usage by the window client might be something like this:
.. code-block:: c
extern bool g_synched;
@ -376,7 +376,7 @@ NX Server Callbacks
.. c:function:: NXWINDOW nx_openwindow(NXHANDLE handle, uint8_t flags, \
FAR const struct nx_callback_s *cb, \
FAR void *arg);
Create a new window.
:param handle: The handle returned by ```nx_connect()`` <#nxconnectinstance>`__.
@ -388,7 +388,7 @@ NX Server Callbacks
:param arg: User provided value that will be returned with NX callbacks.
:return: Success: A non-NULL handle used with subsequent NX accesses
Failure: NULL is returned and errno is set appropriately.
Failure: NULL is returned and errno is set appropriately.
.. c:function:: int nx_closewindow(NXWINDOW hwnd)
@ -543,7 +543,7 @@ NX Server Callbacks
.. c:function:: int nx_fill(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect, \
nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
Fill the specified rectangle in the window with the
specified color.
@ -608,7 +608,7 @@ NX Server Callbacks
:param color: The color to use to fill the line
:param caps: Draw a circular cap on the ends of the line to support better line
joins. One of::
/* Line caps */
#define NX_LINECAP_NONE 0x00, /* No line caps */

2
Documentation/components/nxgraphics/nxcursor.rst
View File

@ -20,7 +20,7 @@ NX Cursor Support (``NXCURSOR``)
The image is provided a a 2-bits-per-pixel image. The two bit incoding
is as following:
- 00: The transparent background.
- 01: Color1: The main color of the cursor.
- 10: Color2: The color of any border.

8
Documentation/components/nxgraphics/nxfonts.rst
View File

@ -34,7 +34,7 @@ NXFONTS types
};
.. c:struct:: nx_fontset_s
.. c:struct:: nx_fontset_s
This structure describes one contiguous grouping of glyphs that can be
described by an array starting with encoding ``first`` and extending
@ -84,7 +84,7 @@ NXFONTS types
Return font bitmap information for the selected
character encoding.
:param ch: The char code for the requested bitmap.
:param ch: The char code for the requested bitmap.
:param handle: A font handle previously returned by :c:func:`nxf_getfonthandle`.
:return: An instance of :c:struct:`nx_fontbitmap_s` describing the glyph.
@ -92,7 +92,7 @@ NXFONTS types
uint16_t width, uint16_t stride, \
FAR const struct nx_fontbitmap_s *bm, \
nxgl_mxpixel_t color);
.. c:function:: int nxf_convert_4bpp(FAR uint8_t *dest, uint16_t height, \
uint16_t width, uint16_t stride, \
FAR const struct nx_fontbitmap_s *bm, \
@ -113,7 +113,7 @@ NXFONTS types
uint16_t width, uint16_t stride, \
FAR const struct nx_fontbitmap_s *bm, \
nxgl_mxpixel_t color);
Convert the 1BPP font to a new pixel depth.
:param dest: The destination buffer provided by the caller.

54
Documentation/components/nxgraphics/nxgl.rst
View File

@ -21,17 +21,17 @@ NXGL Types
if 24, and 32 resolution support is disabled, or ``uint32_t``.
.. c:type:: nxgl_coord_t
A given coordinate is limited to the screen height an
width. If either of those values exceed 32,767 pixels, then the
following will have to need to change:
.. c:struct:: nxgl_point_s
Describes a point on the display:
.. code-block:: c
struct nxgl_point_s
{
nxgl_coord_t x; /* X position, range: 0 to screen width - 1 */
@ -39,28 +39,28 @@ NXGL Types
};
.. c:struct:: nxgl_size_s
Describes the size of a rectangular region.
.. code-block:: c
struct nxgl_size_s
{
nxgl_coord_t w; /* Width in pixels */
nxgl_coord_t h; /* Height in rows */
};
};
.. c:struct:: nxgl_rect_s
Describes a positioned rectangle on the display.
.. code-block:: c
struct nxgl_rect_s
{
struct nxgl_point_s pt1; /* Upper, left-hand corner */
struct nxgl_point_s pt2; /* Lower, right-hand corner */
};
};
.. c:struct:: nxgl_run_s
@ -68,30 +68,30 @@ NXGL Types
that the start/end positions have fractional precision. This is
necessary for good joining of trapezoids when a more complex shape is
decomposed into trapezoids.
.. code-block:: c
struct nxgl_run_s
{
b16_t x1; /* Left X position, range: 0 to x2 */
b16_t x2; /* Right X position, range: x1 to screen width - 1 */
nxgl_coord_t y; /* Top Y position, range: 0 to screen height - 1 */
};
.. c:struct:: nxgl_trapezoid_s
Describes a horizontal trapezoid on the
display in terms the run at the top of the trapezoid and the run at the
bottom.
.. code-block:: c
struct nxgl_trapezoid_s
{
struct nxgl_run_s top; /* Top run */
struct nxgl_run_s bot; /* bottom run */
};
.. c:function:: void nxgl_rgb2yuv(uint8_t r, uint8_t g, uint8_t b, uint8_t *y, uint8_t *u, uint8_t *v)
Convert 8-bit RGB triplet to 8-bit YUV triplet.
@ -144,24 +144,24 @@ NXGL Types
.. c:function:: void nxgl_nonintersecting(FAR struct nxgl_rect_s result[4], \
FAR const struct nxgl_rect_s *rect1, \
FAR const struct nxgl_rect_s *rect2);
Return the regions of rectangle ``rect1`` that do not
intersect with ``rect2``. This will four rectangles, some of which may
be degenerate (and can be picked off with :c:func:`nxgl_nullrect`).
.. c:function:: bool nxgl_rectoverlap(FAR struct nxgl_rect_s *rect1, \
FAR struct nxgl_rect_s *rect2);
Return true if the two rectangles overlap.
.. c:function:: bool nxgl_rectinside(FAR const struct nxgl_rect_s *rect, \
FAR const struct nxgl_point_s *pt);
Return true if the point ``pt`` lies within ``rect``.
.. c:function:: void nxgl_rectsize(FAR struct nxgl_size_s *size, \
FAR const struct nxgl_rect_s *rect);
Return the size of the specified rectangle.
.. c:function:: bool nxgl_nullrect(FAR const struct nxgl_rect_s *rect);
@ -171,33 +171,33 @@ NXGL Types
.. c:function:: void nxgl_runoffset(FAR struct nxgl_run_s *dest, \
FAR const struct nxgl_run_s *src, \
nxgl_coord_t dx, nxgl_coord_t dy);
Offset the run position by the specified ``dx``, ``dy``
values.
.. c:function:: void nxgl_runcopy(FAR struct nxgl_run_s *dest, \
FAR const struct nxgl_run_s *src);
This is essentially ``memcpy()``\ for runs. We don't do
structure assignments because some compilers are not good at that.
.. c:function:: void nxgl_trapoffset(FAR struct nxgl_trapezoid_s *dest, \
FAR const struct nxgl_trapezoid_s *src, \
nxgl_coord_t dx, nxgl_coord_t dy);
Offset the trapezoid position by the specified ``dx``,
``dy`` values.
.. c:function:: void nxgl_trapcopy(FAR struct nxgl_trapezoid_s *dest, \
FAR const struct nxgl_trapezoid_s *src);
This is essentially ``memcpy()``\ for trapezoids. We
don't do structure assignments because some compilers are not good at
that.
.. c:function:: void nxgl_colorcopy(nxgl_mxpixel_t dest[CONFIG_NX_NPLANES], \
const nxgl_mxpixel_t src[CONFIG_NX_NPLANES]);
This is essentially ``memcpy()``\ for colors. This does
very little for us other than hide all of the conditional compilation
for planar colors in one place.
@ -230,7 +230,7 @@ NXGL Types
- 0: Line successfully broken up into three trapezoids. Values in traps[0], traps[1], and traps[2] are valid.
- 1: Line successfully represented by one trapezoid. Value in traps[1] is valid.
- 2: Line successfully represented by one rectangle. Value in rect is valid
- <0: On errors, a negated errno value is returned.
- <0: On errors, a negated errno value is returned.
.. c:function:: void nxgl_circlepts(FAR const struct nxgl_point_s *center, nxgl_coord_t radius, \
FAR struct nxgl_point_s *circle);

34
Documentation/components/nxgraphics/nxtk.rst
View File

@ -26,10 +26,10 @@ these sub-windows to be managed more-or-less independently:
coordinate system for each sub-window begins at the top left
corner of the subwindow. This means that toolbar logic need not
be concerned about client window geometry (and vice versa) and,
for example, common toolbar logic can be used with different windows.
for example, common toolbar logic can be used with different windows.
.. c:type:: FAR void *NXTKWINDOW
This is the handle that can be used to access the window data region.
.. c:function:: int nxtk_block(NXWINDOW hwnd, FAR void *arg)
@ -71,9 +71,9 @@ these sub-windows to be managed more-or-less independently:
server are fully synchronized in time.
Usage by the window client might be something like this:
.. code-block:: c
extern bool g_synched;
extern sem_t g_synch_sem;
@ -91,7 +91,7 @@ these sub-windows to be managed more-or-less independently:
{
-- Handle the error --
}
}
}
When the window listener thread receives the ``NXEVENT_SYNCHED`` event,
it would set ``g_synched`` to ``true`` and post ``g_synch_sem``, waking
@ -128,7 +128,7 @@ these sub-windows to be managed more-or-less independently:
User provided argument (see ```nx_openwindow()`` <#nxopenwindow>`__)
:return: Success: A non-NULL handle used with subsequent NXTK window accesses
Failure: NULL is returned and errno is set appropriately.
Failure: NULL is returned and errno is set appropriately.
.. c:function:: int nxtk_closewindow(NXTKWINDOW hfwnd);
@ -204,7 +204,7 @@ these sub-windows to be managed more-or-less independently:
Lower the window containing the specified client
sub-window to the bottom of the display.
:param hfwnd:
:param hfwnd:
A handle previously returned by
```nxtk_openwindow()`` <#nxtkopenwindow>`__ specifying the window to
be lowered.
@ -251,7 +251,7 @@ these sub-windows to be managed more-or-less independently:
is reported by ``nxtk_ishidden()``. ``nxtk_synch()`` may be used if
temporal synchronization is required.
:param hfwnd:
:param hfwnd:
The handle returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__
that identifies the window to be queried.
@ -351,7 +351,7 @@ these sub-windows to be managed more-or-less independently:
Draw a circular outline using the specified line
thickness and color.
:param hfwnd:
:param hfwnd:
A handle previously returned by
```nxtk_openwindow()`` <#nxtkopenwindow>`__.
:param center:
@ -371,7 +371,7 @@ these sub-windows to be managed more-or-less independently:
Fill a circular region using the specified color.
:param hfwnd:
:param hfwnd:
A handle previously returned by
```nxtk_openwindow()`` <#nxtkopenwindow>`__.
:param center:
@ -548,16 +548,16 @@ these sub-windows to be managed more-or-less independently:
:param caps:
Draw a circular cap on the ends of the line to support better line
joins. One of:
.. code-block:: c
/* Line caps */
#define NX_LINECAP_NONE 0x00, /* No line caps */
#define NX_LINECAP_PT1 0x01 /* Line cap on pt1 on of the vector only */
#define NX_LINECAP_PT2 0x02 /* Line cap on pt2 on of the vector only */
#define NX_LINECAP_BOTH 0x03 /* Line cap on both ends of the vector only */
:return: ``OK`` on success; ``ERROR`` on failure with
``errno`` set appropriately
@ -569,7 +569,7 @@ these sub-windows to be managed more-or-less independently:
Draw a circular outline using the specified line
thickness and color.
:param hfwnd:
:param hfwnd:
A handle previously returned by
```nxtk_openwindow()`` <#nxtkopenwindow>`__.
:param center:
@ -608,7 +608,7 @@ these sub-windows to be managed more-or-less independently:
Move a rectangular region within the toolbar sub-window
of a framed window.
:param hfwnd:
:param hfwnd:
A handle identifying sub-window containing the toolbar within which
the move is to be done. This handle must have previously been
returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
@ -633,10 +633,10 @@ these sub-windows to be managed more-or-less independently:
:param hfwnd:
A handle previously returned by
```nxtk_openwindow()`` <#nxtkopenwindow>`__.
:param dest:
:param dest:
Describes the rectangular region on in the toolbar sub-window will
receive the bit map.
:param src:
:param src:
The start of the source image.
:param origin:
The origin of the upper, left-most corner of the full bitmap. Both

26
Documentation/components/power.rst
View File

@ -30,26 +30,26 @@ consumption states have various names and are sometimes used in
conflicting ways. In the NuttX PM logic, we will use the following
terminology:
``NORMAL``
``NORMAL``
The normal, full power operating mode.
``IDLE``
``IDLE``
This is still basically normal operational mode, the system is,
however, ``IDLE`` and some simple simple steps to reduce power
consumption provided that they do not interfere with normal
Operation. Simply dimming the a backlight might be an example
some that that would be done when the system is idle.
``STANDBY``
``STANDBY``
Standby is a lower power consumption mode that may involve more
extensive power management steps such has disabling clocking or
setting the processor into reduced power consumption modes. In
this state, the system should still be able to resume normal
activity almost immediately.
``SLEEP``
``SLEEP``
The lowest power consumption mode. The most drastic power
reduction measures possible should be taken in this state. It
may require some time to get back to normal operation from
``SLEEP`` (some MCUs may even require going through reset).
.. c:enum:: pm_state_e
These various states are represented with type :c:enum:`pm_state_e`
@ -117,7 +117,7 @@ All PM interfaces are declared in the file ``include/nuttx/power/pm.h``.
and prevent entering reduced power states.
:param domain: Identifies the domain of the new PM activity
:param priority:
:param priority:
Activity priority, range 0-9. Larger values correspond to
higher priorities. Higher priority activity can prevent the
system from entering reduced power states for a longer period
@ -199,16 +199,16 @@ Callbacks
state change mode by returning a non-zero value from the callback
function.
:param cb:
:param cb:
Returned to the driver. The driver version of the callback
structure may include additional, driver-specific state data at
the end of the structure.
:param domain:
:param domain:
Identifies the activity domain of the state change
:param pmstate:
:param pmstate:
Identifies the new PM state
:return:
:return:
Zero (``OK``) means the event was successfully
processed and that the driver is prepared for the PM state change.
Non-zero means that the driver is not prepared to perform the
@ -225,13 +225,13 @@ Callbacks
callback is called after all drivers have had the opportunity to
prepare for the new power state.
:param cb:
:param cb:
Returned to the driver. The driver version of the callback
structure may include additional, driver-specific state data at
the end of the structure.
:param domain:
:param domain:
Identifies the activity domain of the state change
:param pmstate:
:param pmstate:
Identifies the new PM state
The driver already agreed to transition

2
Documentation/components/socketcan.rst
View File

@ -17,7 +17,7 @@ SocketCAN Device Drivers
dlc to CAN FD len sizes named
.. code-block:: c
extern const uint8_t can_dlc_to_len[16];
extern const uint8_t len_to_can_dlc[65];

10
Documentation/components/syslog.rst
View File

@ -62,11 +62,11 @@ extent, its companion ``vsyslog()``:
controlling the SYSLOG output only form that process. There
will be a separate mask accessible only in the kernel code to
control kernel SYSLOG output.
The above are all standard interfaces as defined at
`OpenGroup.org <http://pubs.opengroup.org/onlinepubs/009695399/functions/closelog.html>`__.
Those interfaces are available for use by application software.
The remaining interfaces discussed in this section are non-standard, OS-internal interfaces.
The remaining interfaces discussed in this section are non-standard, OS-internal interfaces.
Debug Interfaces
----------------
@ -166,7 +166,7 @@ The channel interface is instantiated by calling
:return:
Zero (OK)is returned on success. A negated errno value is
returned on any failure.
returned on any failure.
SYSLOG Channel Initialization
-----------------------------
@ -423,14 +423,14 @@ SYSLOG file channel:
NOTE interrupt level SYSLOG output will be lost in this case
unless the interrupt buffer is used.
:param devpath:
:param devpath:
The full path to the file to be used for SYSLOG
output. This may be an existing file or not. If the file
exists, ``syslog_file_channel()`` will append new SYSLOG data
to the end of the file. If it does not, then
``syslog_file_channel()`` will create the file.
:return:
:return:
Zero (``OK``) is returned on success; a
negated ``errno`` value is returned on any failure.

56
Documentation/contributing/documentation.rst
View File

@ -12,32 +12,32 @@ Using Sphinx, the RST files are rendered into HTML files that can be read in you
Building
========
To render the Documentation locally, you should clone the NuttX main repository, and
To render the Documentation locally, you should clone the NuttX main repository, and
go into ``Documentation`` directory. Then,
1. Install Sphinx and other dependencies using pipenv.
You may also find it helpful on platforms such as Windows and MacOS to use *pyenv*
to manage your python installation. You can read about installing that on the
project `site <https://github.com/pyenv/pyenv#installation>`_.
.. code-block:: console
$ pip3 install pipenv
$ pipenv install
$ # activate the virtual environent
$ pipenv shell
2. Build documentation:
.. code-block:: console
$ make html
The resulting HTMLs will end up under ``_build/html``. You can open your browser at the root with:
.. code-block:: console
$ xdg-open _build/html/index.html
$ xdg-open _build/html/index.html
Contributing
============
@ -85,35 +85,35 @@ Sections should look like this:
Subsection
==========
Subsubsection
-------------
Code
----
Code should be documented using the `C domain <https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-c-domain>`_.
Code should be documented using the `C domain <https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-c-domain>`_.
This means for example that a function should be documented as:
.. code-block:: RST
.. c:function:: bool myfunction(int arg1, int arg2)
Here the function should be described
:param arg1: Description of arg1
:param arg2: Description of arg2
:return: Description of return value
To document a piece of code, use a ``code-block`` `directive <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block>`_, specifying the highlight language. If the block is not of code but some verbatim piece of text,
it is acceptable to use RST standard `::`. This is specially useful and compact when used in the following mode:
.. code-block:: RST
The text file should have the following content::
Line1
Line1
Line2
Line3
@ -124,15 +124,15 @@ To generate internal links, Sphinx's `roles <https://www.sphinx-doc.org/en/maste
be used. So, use ``:ref:`` instead of standard RST syntax like ```link <target>`_`` for internal links.
Moreover, sphinx is configured to use `autosectionlabel <https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html#confval-autosectionlabel_prefix_document>`_ extension. This means that sections will automatically get a label that can be linked with the
`:ref:`. For example:
`:ref:`. For example:
.. code-block:: RST
This is a Section
=================
:ref:`This is a Section` is a link to this very same section.
If the target is in a different file, you can refer it with: ``:ref:`link text </pathtorst:Section Name>```.
Notes and TODOS
@ -176,10 +176,10 @@ Generally, you should follow this format:
.. code-block:: RST
.. directive::
child content
non-child content which appears after previous directive
Note the line between directive and content and the indentation.
child content
non-child content which appears after previous directive
Note the line between directive and content and the indentation.

2
Documentation/contributing/index.rst
View File

@ -1,7 +1,7 @@
Contributing
============
In the following sections you will find important information on how to contribute to NuttX codebase (from small bugfixes to large new features)
In the following sections you will find important information on how to contribute to NuttX codebase (from small bugfixes to large new features)
and documentation (the one you are reading now):
.. toctree::

24
Documentation/contributing/workflow.rst
View File

@ -11,32 +11,32 @@ You should be aware of the following:
- All contributions must adhere to the :doc:`Coding Standard <coding_style>`. You can check your files using ``nxstyle``
or complete patchsets using ``checkpatch`` script (both found in ``tools`` subdirectory of NuttX repository). This check will also run
automatically during CI to ensure conformance.
Note that not all existing files in the repository are already adapted to conform to the standard as this is an ongoing effort. Thus,
if you're submitting a patch to an existing file you may have to make the file conform to the standard, even if you are not reponsible
for those standard violations.
for those standard violations.
It is also appreciated that you separate any styling fixes in a separate commit from the functional changes so that these are more
easily readable during review.
- Before starting work on any given non trivial contribution, do subscribe to the mailing list and ask about your idea to avoid
wasted effort by going the wrong-route.
- If you are submitting an original contribution (you wrote the code yourself from scratch) it will have to be submitted under
the terms of the Apache 2.0 License using the corresponding :ref:`header <contributing/coding_style:Appendix>`.
Note that if you are working as an employee in a company, usually copyright belongs to the company and thus this means the company
will have to authorize this and submit the appropriate license agreements.
- If you are submitting third-party code:
- Code from actively developed projects is not accepted to be included in NuttX (i.e.: creating a fork). It is expected that
- Code from actively developed projects is not accepted to be included in NuttX (i.e.: creating a fork). It is expected that
changes required in third-party code for NuttX support are to be implemented in these projects. As an intermediate solution,
it is acceptable to include a patch to be applied to this third-party code, which will be pulled during built.
- If this is from an inactive project, it may be considered for inclusion in NuttX, provided that licensing terms allow to do so
and it is deemed of sufficient value to be included, considering that this code will have to be maintained in NuttX afterwards.
Note that it is undesireable to included non Apache 2.0 Licensed code inside the repository, even if the license itself allows it
(for example BSD License).

2
Documentation/guides/tasktraceuser.rst
View File

@ -31,7 +31,7 @@ The following configurations must be enabled.
- ``CONFIG_SYSTEM_SYSTEM`` : Enables "``system``" command (required by :ref:`trace_cmd`)
The following configurations are configurable parameters for trace.
The following configurations are configurable parameters for trace.
- ``CONFIG_SCHED_INSTRUMENTATION_FILTER_DEFAULT_MODE``

26
Documentation/guides/usbtrace.rst
View File

@ -120,16 +120,16 @@ N. USB EVENT ID 8-bit EVENT DATA MEANING
NOTES:
1. See include/nuttx/usb/usbdev_trace.h
2. See arch/arm/src/lpc17xx_40xx/lpc17_40_usbdev.c
2. See arch/arm/src/lpc17xx_40xx/lpc17_40_usbdev.c
In the above example you can see that:
- **1**. The serial class USB setup method was called for the USB
serial class. This is the corresponds to the following logic in
``drivers/usbdev/pl2303.c``:
.. code-block:: c
static int pl2303_setup(FAR struct uart_dev_s *dev)
{
...
@ -139,7 +139,7 @@ In the above example you can see that:
- **2**. An error occurred while processing the setup command because
no configuration has yet been selected by the host. This corresponds
to the following logic in ``drivers/usbdev/pl2303.c``:
.. code-block:: c
static int pl2303_setup(FAR struct uart_dev_s *dev)
@ -175,19 +175,19 @@ Device Drivers -> USB Device Driver Support .
. (or increase the rate at which the trace buffer is emptied).
``CONFIG_USBDEV_TRACE_STRINGS=y`` Optionally, convert trace ID numbers to strings.
. This feature may not be supported by all drivers.
=========================================== ===================================================
=========================================== ===================================================
=========================================== ===================================================
=========================================== ===================================================
Application Configuration -> NSH LIbrary .
``CONFIG_NSH_USBDEV_TRACE=n`` Make sure that any built-in tracing from NSH is disabled.
``CONFIG_NSH_ARCHINIT=y`` Enable this option only if your board-specific logic
. has logic to automatically start the USB monitor.
. Otherwise the USB monitor can be started or stopped
. with the usbmon_start and usbmon_stop commands from the NSH console.
=========================================== ===================================================
=========================================== ===================================================
=============================================== ============================================
Application Configuration -> System NSH Add-Ons .
``CONFIG_USBMONITOR=y`` Enable the USB monitor daemon
@ -201,13 +201,13 @@ Application Configuration -> System NSH Add-Ons .
. If you lose buffered USB trace data, then dropping
. this value will help by increasing the rate at which
. the USB trace buffer is emptied.
``CONFIG_USBMONITOR_TRACEINIT=y`` Selects which USB event(s) that you want to be traced.
``CONFIG_USBMONITOR_TRACEINIT=y`` Selects which USB event(s) that you want to be traced.
``CONFIG_USBMONITOR_TRACECLASS=y`` .
``CONFIG_USBMONITOR_TRACETRANSFERS=y`` .
``CONFIG_USBMONITOR_TRACECONTROLLER=y`` .
``CONFIG_USBMONITOR_TRACEINTERRUPTS=y`` .
=============================================== ============================================
NOTE: If USB debug output is also enabled, both outputs will appear on
the serial console. However, the debug output will be asynchronous with

8
Documentation/index.rst
View File

@ -1,12 +1,12 @@
.. note::
The present documentation is a recent addition to NuttX and was migrated from previous
The present documentation is a recent addition to NuttX and was migrated from previous
documentation content. For this reason, it is possible you may find broken links or
formatting errors. You can help contribute fixes or improvements to this documentation
by following these :doc:`instructions <contributing/documentation>`.
.. tip::
You can find the old documentation `here <https://cwiki.apache.org/confluence/display/NUTTX/Documentation>`_.
You can find the old documentation `here <https://cwiki.apache.org/confluence/display/NUTTX/Documentation>`_.
===================
NuttX Documentation
===================
@ -31,5 +31,5 @@ Last Updated: |today|
releases/index.rst
contributing/index.rst
glossary.rst
.. include:: substitutions.rst

70
Documentation/make.bat
View File

@ -1,35 +1,35 @@
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=.
set BUILDDIR=_build
if "%1" == "" goto help
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
:end
popd
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=.
set BUILDDIR=_build
if "%1" == "" goto help
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
:end
popd

14
Documentation/quickstart/compiling.rst
View File

@ -19,7 +19,7 @@ a pre-existing configuration. To list all supported configurations you can do:
$ cd nuttx
$ ./tools/configure.sh -L | less
The output is in the format ``<board name>:<board configuration>``. You will see that
generally all boards support the ``nsh`` configuration which is a good sarting point
since it enables booting into the interactive command line
@ -32,7 +32,7 @@ to ``configure.sh`` and indicate your host platform, such as:
$ cd nuttx
$ ./tools/configure.sh -l stm32f4discovery:nsh
The ``-l`` tells use that we're on Linux (macOS and Windows builds are
possible). Use the ``-h`` argument to see all available options.
@ -50,7 +50,7 @@ Don't worry about the complexity– you don't have to use most of the options.
$ cd nuttx/
$ make menuconfig
.. todo::
Explain some useful options.
@ -63,18 +63,18 @@ We can now build NuttX. To do so, you can simply run:
$ cd nuttx/
$ make make
The build will complete by generating the binary outputs
inside `nuttx` directory. Typically this includes the `nuttx`
ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
file that can be flashed to the board.
file that can be flashed to the board.
To clean the build, you can do:
.. code-block:: console
$ make clean
.. warning::
At the moment it is recommended that after modifying the
configuration you first clean before building again. This

2
Documentation/quickstart/index.rst
View File

@ -14,7 +14,7 @@ to build NuttX.
.. toctree::
:maxdepth: 1
quickstart.rst
install.rst
compiling.rst

36
Documentation/quickstart/install.rst
View File

@ -14,7 +14,7 @@ Prerequisites
.. tabs::
.. tab:: Linux
#. Install system packages
.. code-block:: console
@ -63,7 +63,7 @@ Prerequisites
gcc-g++ gperf libncurses-devel
flex gdb libmpfr-devel
git unzip zlib-devel
To complete the installation of prerequisites, you need to install `kconfig-frontends`
as instructed in the :doc:`quickstart` guide.
@ -74,7 +74,7 @@ To build Apache NuttX you need the appropriate toolchain
according to your target platform. Some Operating Systems
such as Linux distribute toolchains for various architectures.
This is usually an easy choice however you should be aware
that in some cases the version offered by your OS may have
that in some cases the version offered by your OS may have
problems and it may better to use a widely used build from
another source.
@ -84,15 +84,15 @@ ARM architecture:
.. tabs::
.. code-tab:: console Ubuntu (deb)
$ apt install gcc-arm-none-eabi binutils-arm-none-eabi
.. tab:: From arm.com
First, create a directory to hold the toolchain:
.. code-block:: console
$ usermod -a -G users $USER
$ # get a login shell that knows we're in this group:
$ su - $USER
@ -100,25 +100,25 @@ ARM architecture:
$ sudo chgrp -R users /opt/gcc
$ sudo chmod -R u+rw /opt/gcc
$ cd /opt/gcc
Download and extract toolchain:
.. code-block:: console
$ HOST_PLATFORM=x86_64-linux # use "mac" for macOS.
$ # For windows there is a zip instead (gcc-arm-none-eabi-9-2019-q4-major-win32.zip)
$ wget https://developer.arm.com/-/media/Files/downloads/gnu-rm/9-2019q4/gcc-arm-none-eabi-9-2019-q4-major-${HOST_PLATFORM}.tar.bz2
$ tar xf gcc-arm-none-eabi-9-2019-q4-major-${HOST_PLATFORM}.tar.bz2
Add the toolchain to your `PATH`:
.. code-block:: console
$ echo "export PATH=/opt/gcc/gcc-arm-none-eabi-9-2019-q4-major/bin:$PATH" >> ~/.bashrc
You can edit your shell's rc files if you don't use bash.
.. tip::
.. tip::
There are hints on how to get the latest tool chains for most supported
architectures in the Apache NuttX CI helper
`script <https://github.com/apache/incubator-nuttx-testing/blob/master/cibuild.sh>`_
@ -130,7 +130,7 @@ Get Source Code
Now that all required tools are installed, you need to download NuttX source-code.
.. tabs::
.. tab:: Development (Git)
Apache NuttX is `actively developed on GitHub <https://github.com/apache/incubator-nuttx/>`_.
@ -153,7 +153,7 @@ Now that all required tools are installed, you need to download NuttX source-cod
# optionally, zipball is also available (for Windows users).
.. tab:: Stable Release
Apache NuttX releases are published on the project `Downloads <https://nuttx.apache.org/download/>`_
page and distributed by the Apache mirrors. Be sure to download both the `nuttx` and `apps` tarballs.

6
Documentation/quickstart/quickstart.rst
View File

@ -53,7 +53,7 @@ computer, you're using an ARM microcontroller on your embedded board, and you're
NuttX is configured using ``kconfig`` system via an interactive menu system (``menuconfig``). It also includes the ``kconfig-tweak`` utility that can be used to quickly change debug settings without going into the menu system.
.. tabs::
.. code-tab:: console Ubuntu 20.04 LTS and later
$ apt install kconfig-frontends
@ -91,7 +91,7 @@ computer, you're using an ARM microcontroller on your embedded board, and you're
$ ./tools/configure.sh -l <board-name>:<config-dir>
# for instance:
$ ./tools/configure.sh -l sama5d27-xult:nsh
#. Customize Your Configuration (Optional)
This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
@ -104,7 +104,7 @@ computer, you're using an ARM microcontroller on your embedded board, and you're
$ make menuconfig
Use your arrows to navigate the menu and :kbd:`Enter` key to enable/disable options. To exit and save your configuration, go back to the main menu, choose ``<Exit>`` and select "yes" when asked if you want to save.
#. Compile Apache NuttX
.. code-block:: bash

22
Documentation/quickstart/running.rst
View File

@ -21,14 +21,14 @@ Flashing
There are various tools you can use to flash the NuttX binary to your Nucleo
board. One common option is to use `openocd` which supports a large number
of programmers and target microcontrollers.
of programmers and target microcontrollers.
To install the stable version of openocd you can do:
.. code-block:: console
$ apt install openocd
.. todo:: add instructions for other platforms
You should note that openocd project has not made stable releases for long
@ -42,7 +42,7 @@ latest Git version. To install it you should:
$ ./bootstrap
$ ./configure --prefix install/
$ make install
The resulting installation will be under ``openocd/install``. You can add
``openocd/install/bin`` to your ``PATH``.
@ -53,7 +53,7 @@ Now, to flash the binary to your board, connect the USB cable and do:
$ cd nuttx/
$ openocd -f interface/st-link-v2.cfg -f target/stm32f1x.cfg -c 'init' \
-c 'program nuttx/nuttx.bin verify reset' -c 'shutdown'
Access NuttShell
================
@ -64,13 +64,13 @@ of your choice where you will see the ``nsh>`` prompt:
.. tabs::
.. code-tab:: console picocom (CLI)
$ picocom -b 115200 /dev/ttyUSB0
.. code-tab:: console gtkterm (GUI)
$ gtkterm -s 115200 -p /dev/ttyUSB0
Debugging
=========
@ -80,20 +80,20 @@ Using ``openocd`` you can also debug NuttX. To do so, first run:
.. code-block:: console
$ openocd -f interface/st-link-v2.cfg -f target/stm32f1x.cfg
which will start a GDB server. Then, start ``gdb`` as:
.. code-block:: console
$ cd nuttx/
$ gdb-multiarch nuttx/nuttx
Inside ``gdb`` console, connect to the ``openocd`` server with:
.. code-block::
(gdb) target extended-remote :3333
You can debug using standard ``gdb`` commands.
Advanced Debugging with JTAG

48
Documentation/reference/os/addrenv.rst
View File

@ -1,6 +1,6 @@
====================
Address Environments
====================
====================
CPUs that support memory management units (MMUs) may provide
*address environments* within which tasks and their child threads
@ -93,7 +93,7 @@ The CPU-specific logic must provide two categories in interfaces:
This function is called when a new task is created in order to
instantiate an address environment for the new task group.
up_addrenv_create() is essentially the allocator of the physical memory for the new task.
up_addrenv_create() is essentially the allocator of the physical memory for the new task.
:param textsize: The size (in bytes) of the ``.text`` address
environment needed by the task. This region may be read/execute
@ -125,19 +125,19 @@ The CPU-specific logic must provide two categories in interfaces:
Return the virtual .text address associated with the newly create
address environment. This function is used by the binary loaders
in order get an address that can be used to initialize the new task.
in order get an address that can be used to initialize the new task.
:param addrenv: The representation of the task address environment
previously returned by ``up_addrenv_create()``.
:param vtext: The location to return the virtual address.
:return: Zero (OK) on success; a negated errno value on failure.
:return: Zero (OK) on success; a negated errno value on failure.
.. c:function:: int up_addrenv_vdata(FAR group_addrenv_t *addrenv, size_t textsize, FAR void **vdata)
Return the virtual .text address associated with the newly create
address environment. This function is used by the binary loaders
in order get an address that can be used to initialize the new task.
in order get an address that can be used to initialize the new task.
:param addrenv: The representation of the task address environment
previously returned by ``up_addrenv_create()``.
@ -147,28 +147,28 @@ The CPU-specific logic must provide two categories in interfaces:
offset into the common region.
:param vdata: The location to return the virtual address.
:return: Zero (OK) on success; a negated errno value on failure.
:return: Zero (OK) on success; a negated errno value on failure.
.. c:function:: ssize_t up_addrenv_heapsize(FAR const group_addrenv_t *addrenv)
Return the initial heap allocation size. That is the amount of
memory allocated by up_addrenv_create() when the heap memory
region was first created. This may or may not differ from the
heapsize parameter that was passed to up_addrenv_create().
heapsize parameter that was passed to up_addrenv_create().
:param addrenv: The representation of the task address environment
previously returned by ``up_addrenv_create()``.
:return: The initial heap size allocated is returned on success;
a negated errno value on failure.
a negated errno value on failure.
.. c:function:: int up_addrenv_select(group_addrenv_t *addrenv, save_addrenv_t *oldenv)
After an address environment has been established for a task
After an address environment has been established for a task
(via up_addrenv_create()), this function may be called to instantiate
that address environment in the virtual address space. This might be
necessary, for example, to load the code for the task from a file or
to access address environment private data.
to access address environment private data.
:param addrenv: The representation of the task address environment
previously returned by ``up_addrenv_create()``.
@ -180,13 +180,13 @@ The CPU-specific logic must provide two categories in interfaces:
platform-specific representation that may or may not be
different from ``group_addrenv_t``.
:return: Zero (OK) on success; a negated errno value on failure.
:return: Zero (OK) on success; a negated errno value on failure.
.. c:function:: int up_addrenv_restore(save_addrenv_t oldenv)
After an address environment has been temporarily instantiated
by up_addrenv_select, this function may be called to restore
the original address environment.
the original address environment.
:param oldenv: The platform-specific representation of the address
environment previously returned by ``up_addrenv_select()``.
@ -197,13 +197,13 @@ The CPU-specific logic must provide two categories in interfaces:
Duplicate an address environment. This does not copy the underlying
memory, only the representation that can be used to instantiate
that memory as an address environment.
that memory as an address environment.
:param src: The address environment to be copied.
:param dest: The location to receive the copied address
environment.
:return: Zero (OK) on success; a negated errno value on failure.
:return: Zero (OK) on success; a negated errno value on failure.
.. c:function:: int up_addrenv_attach(FAR struct task_group_s *group, FAR struct tcb_s *tcb)
@ -220,7 +220,7 @@ The CPU-specific logic must provide two categories in interfaces:
:param ctcb: The TCB of the thread needing the address
environment.
:return: Zero (OK) on success; a negated errno value on failure.
:return: Zero (OK) on success; a negated errno value on failure.
.. c:function:: int up_addrenv_detach(FAR struct task_group_s *group, FAR struct task_group_s *tcb)
@ -228,17 +228,17 @@ The CPU-specific logic must provide two categories in interfaces:
to release its reference to an address environment. The address
environment, however, should persist until up_addrenv_destroy()
is called when the task group is itself destroyed. Any resources
unique to this thread may be destroyed now.
unique to this thread may be destroyed now.
:param group: The group to which the thread belonged.
:param tcb: The TCB of the task or thread whose the address
environment will be released.
:return: Zero (OK) on success; a negated errno value on failure.
:return: Zero (OK) on success; a negated errno value on failure.
.. c:function:: int up_addrenv_ustackalloc(FAR struct tcb_s *tcb, size_t stacksize)
This function is called when a new thread is created in order
This function is called when a new thread is created in order
to instantiate an address environment for the new thread's stack.
up_addrenv_ustackalloc() is essentially the allocator of the
physical memory for the new task's stack.
@ -249,13 +249,13 @@ The CPU-specific logic must provide two categories in interfaces:
environment needed by the task. This region may be read/write
only.
:return: Zero (OK) on success; a negated errno value on failure.
:return: Zero (OK) on success; a negated errno value on failure.
.. c:function:: int up_addrenv_ustackfree(FAR struct tcb_s *tcb)
This function is called when any thread exits. This function then
destroys the defunct address environment for the thread's stack,
releasing the underlying physical memory.
releasing the underlying physical memory.
:param tcb: The TCB of the thread that no longer requires the
stack address environment.
@ -269,7 +269,7 @@ The CPU-specific logic must provide two categories in interfaces:
:param tcb: The TCB of the thread with the stack address environment of interest.
:param vstack: The location to return the stack virtual base address.
:return: Zero (OK) on success; a negated errno value on failure.
:return: Zero (OK) on success; a negated errno value on failure.
.. c:function:: int up_addrenv_ustackselect(FAR const struct tcb_s *tcb)
@ -289,7 +289,7 @@ The CPU-specific logic must provide two categories in interfaces:
This function is called when a new thread is created to allocate the
new thread's kernel stack. This function may be called for certain
terminating threads which have no kernel stack. It must be
tolerant of that case.
tolerant of that case.
:param tcb: The TCB of the thread that requires the kernel stack.
@ -297,9 +297,9 @@ The CPU-specific logic must provide two categories in interfaces:
.. c:function:: int up_addrenv_kstackfree(FAR struct tcb_s *tcb);
This function is called when any thread exits. This function frees the kernel stack.
This function is called when any thread exits. This function frees the kernel stack.
:param tcb: The TCB of the thread that no longer requires the
kernel stack.
:return: Zero (OK) on success; a negated errno value on failure.
:return: Zero (OK) on success; a negated errno value on failure.

2
Documentation/reference/os/boardctl.rst
View File

@ -36,5 +36,5 @@
of the argument is determined by the specific command.
:return: On success zero (OK) is returned; -1 (ERROR) is
returned on failure with the errno variable set to indicate the nature of the failure.
returned on failure with the errno variable set to indicate the nature of the failure.

12
Documentation/reference/os/iob.rst
View File

@ -29,10 +29,10 @@ networking subsystem. This objectives of this feature are:
Configuration Options
=====================
``CONFIG_MM_IOB``
``CONFIG_MM_IOB``
Enables generic I/O buffer support. This setting will build the
common I/O buffer (IOB) support library.
``CONFIG_IOB_NBUFFERS``
``CONFIG_IOB_NBUFFERS``
Number of pre-allocated I/O buffers. Each packet is represented
by a series of small I/O buffers in a chain. This setting
determines the number of preallocated I/O buffers available for
@ -41,12 +41,12 @@ Configuration Options
is enabled (neither ``CONFIG_NET_TCP_WRITE_BUFFERS`` nor
``CONFIG_NET_TCP``), 24 if only TCP/UDP is enabled, and 36 if
both TCP/UDP and write buffering are enabled.
``CONFIG_IOB_BUFSIZE``
``CONFIG_IOB_BUFSIZE``
Payload size of one I/O buffer. Each packet is represented by a
series of small I/O buffers in a chain. This setting determines
the data payload each preallocated I/O buffer. The default
value is 196 bytes.
``CONFIG_IOB_NCHAINS``
``CONFIG_IOB_NCHAINS``
Number of pre-allocated I/O buffer chain heads. These tiny
nodes are used as *containers* to support queueing of I/O
buffer chains. This will limit the number of I/O transactions
@ -59,7 +59,7 @@ Configuration Options
zero if nether TCP nor UDP is enabled (i.e., neither
``CONFIG_NET_TCP`` && !\ ``CONFIG_NET_UDP`` or eight if either
is enabled.
``CONFIG_IOB_THROTTLE``
``CONFIG_IOB_THROTTLE``
I/O buffer throttle value. TCP write buffering and read-ahead
buffer use the same pool of free I/O buffers. In order to
prevent uncontrolled incoming TCP packets from hogging all of
@ -68,7 +68,7 @@ Configuration Options
denied to the read-ahead logic before TCP writes are halted.
The default 0 if neither TCP write buffering nor TCP read-ahead
buffering is enabled. Otherwise, the default is 8.
``CONFIG_IOB_DEBUG``
``CONFIG_IOB_DEBUG``
Force I/O buffer debug. This option will force debug output
from I/O buffer logic. This is not normally something that
would want to do but is convenient if you are debugging the I/O

4
Documentation/reference/os/led.rst
View File

@ -108,13 +108,13 @@ The ``include/nuttx/board.h`` includes the following declarations:
interfaces (such as ``stm32_led_initialize()``).
.. c:function:: void board_autoled_on(int led)
Called to instantiate the LED
presentation of the event. The ``led`` argument is one of the
definitions provided in ``<board-name>/include/board.h``.
.. c:function:: void board_autoled_off(int led)
Called to terminate the LED
presentation of the event. The ``led`` argument is one of the
definitions provided in ``<board-name>/include/board.h``. Note

10
Documentation/reference/os/note.rst
View File

@ -33,21 +33,21 @@ Notectl Device (``/dev/notectl``)
unsigned int flag; /* Filter mode flag */
#ifdef CONFIG_SMP
unsigned int cpuset; /* The set of monitored CPUs */
#endif
#endif
};
- ``flag`` : Filter mode flag. The bitwise OR of the following defines are available.
.. c:macro:: NOTE_FILTER_MODE_FLAG_ENABLE
Enable instrumentation
.. c:macro:: NOTE_FILTER_MODE_FLAG_SYSCALL
Enable syscall instrumentation
.. c:macro:: NOTE_FILTER_MODE_FLAG_IRQ
Enable IRQ instrumentaiton
- ``cpuset`` : (SMP only) Monitor only CPUs in the bitset. Bit 0=CPU0, Bit1=CPU1, etc.
@ -199,7 +199,7 @@ Noteram Device (``/dev/note``)
The overwrite mode takes one of the following values.
.. c:macro:: NOTERAM_MODE_OVERWRITE_DISABLE
Overwrite mode is disabled. When the buffer is full, accepting the data will be stopped.
.. c:macro:: NOTERAM_MODE_OVERWRITE_ENABLE

4
Documentation/reference/os/nuttx.rst
View File

@ -30,7 +30,7 @@ OS List Management APIs
the tick-less OS expires.
**Assumptions**: Base code implementation assumes that this
function is called from interrupt handling logic with interrupts disabled.
function is called from interrupt handling logic with interrupts disabled.
.. c:function:: void nxsched_alarm_expiration(void);
@ -40,7 +40,7 @@ OS List Management APIs
the tick-less OS expires.
**Assumptions**: Base code implementation assumes that this
function is called from interrupt handling logic with interrupts disabled.
function is called from interrupt handling logic with interrupts disabled.
.. c:function:: void irq_dispatch(int irq, FAR void *context)

8
Documentation/reference/os/shm.rst
View File

@ -14,7 +14,7 @@ below:
.. c:function:: int up_shmat(FAR uintptr_t *pages, unsigned int npages, uintptr_t vaddr)
Attach, i.e, map, on shared memory region to a user virtual address.
Attach, i.e, map, on shared memory region to a user virtual address.
:param pages: A pointer to the first element in a array of
physical address, each corresponding to one page of memory.
@ -23,16 +23,16 @@ below:
:param vaddr: The virtual address corresponding to the beginning
of the (contiguous) virtual address region.
:return: Zero (OK) is returned on success; a negated errno value is returned on failure.
:return: Zero (OK) is returned on success; a negated errno value is returned on failure.
.. c:function:: int up_shmdt(uintptr_t vaddr, unsigned int npages)
Detach, i.e, unmap, on shared memory region from a user virtual address.
Detach, i.e, unmap, on shared memory region from a user virtual address.
:param vaddr: The virtual address corresponding to the beginning
of the (contiguous) virtual address region.
:param npages: T The number of pages to be unmapped.
:return: Zero (OK) is returned on success; a negated errno value is returned on failure.
:return: Zero (OK) is returned on success; a negated errno value is returned on failure.

14
Documentation/reference/os/smp.rst
View File

@ -26,7 +26,7 @@ Page <https://cwiki.apache.org/confluence/display/NUTTX/SMP>`__.
.. c:function:: spinlock_t up_testset(volatile FAR spinlock_t *lock)
Perform and atomic test and set operation on the provided spinlock.
Perform and atomic test and set operation on the provided spinlock.
:param lock: The address of spinlock object.
@ -35,16 +35,16 @@ Page <https://cwiki.apache.org/confluence/display/NUTTX/SMP>`__.
either SP_LOCKED if the spinlock was previously locked
(meaning that the test-and-set operation failed to obtain the lock)
or SP_UNLOCKED if the spinlock was previously unlocked
(meaning that we successfully obtained the lock)
(meaning that we successfully obtained the lock)
.. c:function:: int up_cpu_index(void)
Return an index in the range of 0 through (CONFIG_SMP_NCPUS-1)
that corresponds to the currently executing CPU.
that corresponds to the currently executing CPU.
:return: An integer index in the range of 0 through
(CONFIG_SMP_NCPUS-1) that corresponds to the
currently executing CPU.
currently executing CPU.
.. c:function:: int up_cpu_start(int cpu)
@ -66,7 +66,7 @@ Page <https://cwiki.apache.org/confluence/display/NUTTX/SMP>`__.
numeric value in the range of from one to
``(CONFIG_SMP_NCPUS-1)``). (CPU 0 is already active).
:return: Zero (OK) is returned on success; a negated errno value on failure.
:return: Zero (OK) is returned on success; a negated errno value on failure.
.. c:function:: int up_cpu_pause(int cpu)
@ -84,7 +84,7 @@ Page <https://cwiki.apache.org/confluence/display/NUTTX/SMP>`__.
.. c:function:: int up_cpu_resume(int cpu)
Restart the cpu after it was paused via up_cpu_pause(),
Restart the cpu after it was paused via up_cpu_pause(),
restoring the state of the task at the head of the
``g_assignedtasks[cpu]`` list, and resume normal tasking.
@ -95,5 +95,5 @@ Page <https://cwiki.apache.org/confluence/display/NUTTX/SMP>`__.
:param cpu: The index of the CPU being resumed. This will not be
the index of the currently executing CPU.
:return: Zero (OK) is returned on success; a negated errno value on failure.
:return: Zero (OK) is returned on success; a negated errno value on failure.

60
Documentation/reference/os/time_clock.rst
View File

@ -56,9 +56,9 @@ run. Consider this example implementation:
#. Initially an accumulator is zero an the match value is
programmed to 328:
.. code-block:: c
accumulator = 0;
match = 328;
@ -66,9 +66,9 @@ run. Consider this example implementation:
that, in this reflects, 100\* the error in interval that just
passed. So on the first timer interrupt, the accumulator would
be updated like:
.. code-block:: c
if (match == 328)
{
accumulator += 32; // 100*(328 - 327.68)
@ -76,13 +76,13 @@ run. Consider this example implementation:
else
{
accumulator -= 68; // (100*(327 - 327.68)
}
}
#. And on that same timer interrupt a new match value would be
programmed:
.. code-block:: c
if (accumulator < 0)
{
match = 328;
@ -91,7 +91,7 @@ run. Consider this example implementation:
{
match = 327;
}
In this way, the timer interval is controlled from
interrupt-to-interrupt to produce an average frequency of exactly
100Hz.
@ -101,10 +101,10 @@ Hardware
To enable hardware module use the following configuration options:
``CONFIG_RTC``
``CONFIG_RTC``
Enables general support for a hardware RTC. Specific
architectures may require other specific settings.
``CONFIG_RTC_EXTERNAL``
``CONFIG_RTC_EXTERNAL``
Most MCUs include RTC hardware built into the chip. Other RTCs,
*external* MCUs, may be provided as separate chips typically
interfacing with the MCU via a serial interface such as SPI or
@ -113,7 +113,7 @@ To enable hardware module use the following configuration options:
booted and can support the required serial communications.
``CONFIG_RTC_EXTERNAL`` will configure the operating system so
that it defers initialization of its time facilities.
``CONFIG_RTC_DATETIME``
``CONFIG_RTC_DATETIME``
There are two general types of RTC: (1) A simple battery backed
counter that keeps the time when power is down, and (2) A full
date / time RTC the provides the date and time information,
@ -121,7 +121,7 @@ To enable hardware module use the following configuration options:
specifies this second kind of RTC. In this case, the RTC is
used to "seed"" the normal NuttX timer and the NuttX system
timer provides for higher resolution time.
``CONFIG_RTC_HIRES``
``CONFIG_RTC_HIRES``
If ``CONFIG_RTC_DATETIME`` not selected, then the simple,
battery backed counter is used. There are two different
implementations of such simple counters based on the time
@ -132,11 +132,11 @@ To enable hardware module use the following configuration options:
If ``CONFIG_RTC_HIRES`` is enabled in the NuttX configuration,
then the RTC provides higher resolution time and completely
replaces the system timer for purpose of date and time.
``CONFIG_RTC_FREQUENCY``
``CONFIG_RTC_FREQUENCY``
If ``CONFIG_RTC_HIRES`` is defined, then the frequency of the
high resolution RTC must be provided. If ``CONFIG_RTC_HIRES``
is not defined, ``CONFIG_RTC_FREQUENCY`` is assumed to be one.
``CONFIG_RTC_ALARM``
``CONFIG_RTC_ALARM``
Enable if the RTC hardware supports setting of an alarm. A
callback function will be executed when the alarm goes off
@ -377,9 +377,9 @@ timer implementation:
On return, the current up-time should be available from up_timer_gettime()
and the interval timer is ready for use (but not actively timing).
The naming will depend on the architecture so for STM32 ``archname`` will
be ``stm32``.
be ``stm32``.
:return: Zero (OK) on success; a negated errno value on failure.
:return: Zero (OK) on success; a negated errno value on failure.
**Assumptions**: Called early in the initialization sequence before
any special concurrency protections are required.
@ -395,12 +395,12 @@ timer implementation:
:param ts: Provides the location in which to return the up-time..
:return: Zero (OK) on success; a negated errno value on failure.
:return: Zero (OK) on success; a negated errno value on failure.
**Assumptions**: Called from the normal tasking context. The
implementation must provide whatever mutual exclusion is necessary
for correct operation. This can include disabling interrupts in
order to assure atomic register operations.
order to assure atomic register operations.
.. c:function:: int up_alarm_cancel(FAR struct timespec *ts)
@ -415,11 +415,11 @@ timer implementation:
time should be returned if the timer is not active. ``ts`` may
be ``NULL`` in which case the time is not returned
:return: Zero (OK) on success; a negated errno value on failure.
:return: Zero (OK) on success; a negated errno value on failure.
**Assumptions**: May be called from interrupt level handling or
from the normal tasking level. interrupts may need to be disabled
internally to assure non-reentrancy.
internally to assure non-reentrancy.
.. c:function:: int up_alarm_start(FAR const struct timespec *ts)
@ -431,11 +431,11 @@ timer implementation:
occur. When the alarm occurs the timer logic will call
``nxsched_timer_expiration()``.
:return: Zero (OK) on success; a negated errno value on failure.
:return: Zero (OK) on success; a negated errno value on failure.
**Assumptions**: May be called from interrupt level handling or
from the normal tasking level. Interrupts may need to be
disabled internally to assure non-reentrancy.
disabled internally to assure non-reentrancy.
.. c:function:: int up_timer_cancel(FAR struct timespec *ts)
@ -451,11 +451,11 @@ remaining time of zero should be returned.
:param ts: Location to return the remaining time. Zero should be
returned if the timer is not active.
:return: Zero (OK) on success; a negated errno value on failure.
:return: Zero (OK) on success; a negated errno value on failure.
**Assumptions**: May be called from interrupt level handling or
from the normal tasking level. interrupts may need to be
disabled internally to assure non-reentrancy.
from the normal tasking level. interrupts may need to be
disabled internally to assure non-reentrancy.
.. c:function:: int up_timer_start(FAR const struct timespec *ts)
@ -466,11 +466,11 @@ called at the completion of the timeout (unless
:param ts: Provides the time interval until
``nxsched_timer_expiration()`` is called.
:return: Zero (OK) on success; a negated errno value on failure.
:return: Zero (OK) on success; a negated errno value on failure.
**Assumptions**: May be called from interrupt level handling
or from the normal tasking level. Interrupts may need to be
disabled internally to assure non-reentrancy.
disabled internally to assure non-reentrancy.
Watchdog Timer Interfaces
=========================
@ -562,18 +562,18 @@ with NuttX tasks.
watchdog time expires. Zero means either that wdog is not valid or
that the wdog has already expired.
.. c:type:: void (*wdentry_t)(wdparm_t arg)
.. c:type:: void (*wdentry_t)(wdparm_t arg)
**Watchdog Timer Callback**: when a watchdog expires,
the callback function with this type is
called.
The argument is passed as scalar ``wdparm_t`` values. For
systems where the ``sizeof(pointer) < sizeof(uint32_t)``, the
following union defines the alignment of the pointer within the
``uint32_t``. For example, the SDCC MCS51 general pointer is
24-bits, but ``uint32_t`` is 32-bits (of course).
We always have ``sizeof(pointer) <= sizeof(uintptr_t)`` by
definition.

12
Documentation/reference/os/wqueue.rst
View File

@ -237,7 +237,7 @@ Work Queue Interfaces
until the worker is invoked. Zero means to perform the work
immediately.
:return: Zero is returned on success; a negated errno is returned on failure.
:return: Zero is returned on success; a negated errno is returned on failure.
.. c:function:: int work_cancel(int qid, FAR struct work_s *work)
@ -263,15 +263,15 @@ Work Queue Interfaces
:param qid: The work queue ID.
:return: Zero is returned on success; a negated errno is returned on failure.
:return: Zero is returned on success; a negated errno is returned on failure.
.. c:function:: bool work_available(FAR struct work_s *work)
Check if the work structure is available.
Check if the work structure is available.
:param work: The work queue structure to check.
:return: ``true`` if available; ``false`` if busy (i.e., there is still pending work).
:return: ``true`` if available; ``false`` if busy (i.e., there is still pending work).
.. c:function:: int work_usrstart(void)
@ -285,7 +285,7 @@ Work Queue Interfaces
:return: The task ID of the worker thread is returned on success.
A negated ``errno`` value is returned on failure.
.. c:function:: void lpwork_boostpriority(uint8_t reqprio)
Called by the work queue client to assure that

16
Documentation/reference/user/01_task_control.rst
View File

@ -90,12 +90,12 @@ Non-standard task control interfaces inspired by ``posix_spawn``:
- :c:func:`task_spawnattr_getstacksize`
- :c:func:`task_spawnattr_setstacksize`
- :c:func:`posix_spawn_file_actions_init`
Functions
---------
.. c:function:: int task_create(char *name, int priority, int stack_size, main_t entry, char * const argv[])
This function creates and activates a new task with a
specified priority and returns its system-assigned ID.
@ -127,16 +127,16 @@ Functions
:param argv: A pointer to an array of input parameters. The array should
be terminated with a NULL argv[] value. If no parameters are
required, argv may be NULL.
:return: the non-zero task ID of the new task or ERROR if memory is
insufficient or the task cannot be created
(```errno`` <#ErrnoAccess>`__ is not set).
**Defined in:** ``sched.h``
**POSIX Compatibility:** This is a NON-POSIX interface. VxWorks provides
the following similar interface:
.. code-block:: c
int taskSpawn(char *name, int priority, int options, int stackSize, FUNCPTR entryPt,
@ -240,7 +240,7 @@ Functions
- Restart of the currently running task is not supported by NuttX.
- The VxWorks description says that the ID, priority, etc. take the
value that they had when the task was *terminated*.
.. c:function:: int task_setcancelstate(int state, int *oldstate)
This function atomically sets
@ -305,7 +305,7 @@ Functions
the functionality of ``pthread_testcancel()`` to tasks and supports use
of ``task_delete()``.
.. c:function:: void exit(int code)
.. c:function:: void exit(int code)
.. c:function:: void _exit(int code)
.. #include <sched.h>
@ -793,7 +793,7 @@ Functions
FAR const posix_spawn_file_actions_t *file_actions, \
FAR const posix_spawnattr_t *attr, \
FAR char * const argv[], FAR char * const envp[])
The ``task_spawn()`` function will create a new, child
task, where the entry point to the task is an address in memory.

6
Documentation/reference/user/02_task_scheduling.rst
View File

@ -55,13 +55,13 @@ Functions
name. Differences from the full POSIX implementation include:
- The range of priority values for the POSIX call is 0 to 255.
.. note:: Setting a task's priority to the same value has the similar effect
to ``sched_yield()``: The task will be moved to after all other tasks
with the same priority.
with the same priority.
.. c:function:: int sched_getparam(pid_t pid, FAR struct sched_param *param)
This function gets the scheduling priority of the task
specified by pid.

18
Documentation/reference/user/03_task_control.rst
View File

@ -26,11 +26,11 @@ Task Control Interfaces
within the task group. Members of a task group share certain
resources such as environment variables, file descriptors, ``FILE``
streams, sockets, pthread keys and open message queues.
- :c:func:`atexit`
- :c:func:`on_exit`
.. note::
.. note::
Behavior of features related to task group's depend of
NuttX configuration settings. See the discussion of "Parent and
Child Tasks," below. See also the\ `NuttX
@ -132,9 +132,9 @@ Functions
**POSIX Compatibility:** This is a NON-POSIX interface. VxWorks provides
the comparable interface:
.. code-block:: c
STATUS taskLock(void);
.. c:function:: int sched_unlock(void)
@ -147,10 +147,10 @@ Functions
task will execute.
:return: OK or ERROR.
**POSIX Compatibility:** This is a NON-POSIX interface. VxWorks provides
the comparable interface:
.. code-block:: c
STATUS taskUnlock(void);
@ -168,7 +168,7 @@ Functions
.. c:function:: ipid_t waitpid(pid_t pid, int *stat_loc, int options)
.. note::
.. note::
The following discussion is a general description of the
``waitpid()`` interface. However, as of this writing, the
implementation of ``waitpid()`` is incomplete (but usable). If
@ -363,7 +363,7 @@ Functions
the structure pointed to by ``info`` will be filled in by the system
with the status of the process. The ``si_signo`` member will always be
equal to ``SIGCHLD``.
:return: If ``waitid()`` returns due to the change of state
of one of its children, 0 is returned. Otherwise, -1 is returned and
``errno`` is set to indicate the error.

2
Documentation/reference/user/05_counting_semaphore.rst
View File

@ -308,7 +308,7 @@ page <https://cwiki.apache.org/confluence/display/NUTTX/Signaling+Semaphores+and
**POSIX Compatibility:** Comparable to the POSIX interface of the same
name.
.. c:function:: int sem_timedwait(sem_t *sem, const struct timespec *abstime)
This function will lock the semaphore referenced by sem

2
Documentation/reference/user/06_clocks_timers.rst
View File

@ -128,7 +128,7 @@ Clocks and Timers
return the pointer, ``buf``, provided by the caller. Otherwise, a NULL
will be returned to indicate the error.
.. c:function:: FAR char *ctime_r(FAR const time_t *timep, FAR char *buf)
.. c:function:: FAR char *ctime_r(FAR const time_t *timep, FAR char *buf)
Converts the time provided in seconds
since the epoch to a string representation. ``ctime()`` is re-entrant.

8
Documentation/reference/user/07_signals.rst
View File

@ -19,7 +19,7 @@ time* signals by default. If the configuration option
default actions dependent upon addition configuration settings as
summarized in the following table:
======= ==================== =========================
======= ==================== =========================
Signal Action Additional Configuration
======= ==================== =========================
SIGUSR1 Abnormal Termination CONFIG_SIG_SIGUSR1_ACTION
@ -236,7 +236,7 @@ provided by NuttX:
:param signo: The signal number to act on
:return:
:return:
- Zero is returned upon successful completion, otherwise -1 (``ERROR``)
is returned with the errno set appropriately. The ``errno`` value of
``EINVAL``, for example, would indicate that ``signo`` argument is
@ -259,7 +259,7 @@ provided by NuttX:
:param signo: The signal number to operate on
:param disp: The new disposition of the signal
:return:
:return:
- Upon successful completion, ``sigset()`` will the previous
disposition of the signal. Otherwise, ``SIG_ERR`` will be returned
and ``errno`` set to indicate the error.
@ -279,7 +279,7 @@ provided by NuttX:
:param how: How the signal mask will be changed.
- ``SIG_BLOCK`` The resulting set is the union of the current set and the signal set pointed to by the ``set`` input parameter.
- ``SIG_UNBLOCK`` The resulting set is the intersection of the current set and the complement of the signal set pointed to by the ``set`` input parameter.
- ``SIG_UNBLOCK`` The resulting set is the intersection of the current set and the complement of the signal set pointed to by the ``set`` input parameter.
- ``SIG_SETMASK`` The resulting set is the signal set pointed to by the ``set`` input parameter.
:param set: Location of the new signal mask

2
Documentation/reference/user/08_pthread.rst
View File

@ -828,7 +828,7 @@ No support for the following pthread interfaces is provided by NuttX:
- ``pthread_setspecific()`` may be called from a thread-specific data
destructor function.
.. c:function:: void *pthread_getspecific(pthread_key_t key)
The ``pthread_getspecific()`` function returns the value currently bound

6
Documentation/reference/user/09_env_vars.rst
View File

@ -45,12 +45,12 @@ Functions
=========
.. c:function:: FAR char *getenv(const char *name)
Searches the environment list for a string that matches
the string pointed to by ``name``.
:param name: The name of the variable to find.
:return:
The value of the variable (read-only) or NULL on failure.
@ -64,7 +64,7 @@ Functions
:param string: ``name=value`` string describing the environment setting to
add/modify.
:return: Zero on success.
.. c:function:: int clearenv(void)

12
Documentation/reference/user/10_filesystem.rst
View File

@ -410,13 +410,13 @@ Pipes and FIFOs
.. c:function:: int pipe(int fd[2])
Creates a pair of file descriptors, pointing to a pipe inode,
and places them in the array pointed to by ``fd``.
and places them in the array pointed to by ``fd``.
:param fd: The user provided array in which to catch the pipe file
descriptors. ``fd[0]`` is for reading, ``fd[1]`` is for writing.
:return: 0 is returned on success; otherwise, -1 is returned with errno set appropriately.
:return: 0 is returned on success; otherwise, -1 is returned with errno set appropriately.
.. c:function:: int mkfifo(FAR const char *pathname, mode_t mode);
mkfifo() makes a FIFO device driver file with name pathname. Unlike Linux,
@ -426,7 +426,7 @@ Pipes and FIFOs
Once the FIFO has been created by mkfifo(), any thread can open it for reading
or writing, in the same way as an ordinary file. However, it must have been
opened from both reading and writing before input or output can be performed.
This FIFO implementation will block all attempts to open a FIFO read-only
This FIFO implementation will block all attempts to open a FIFO read-only
until at least one thread has opened the FIFO for writing.
If all threads that write to the FIFO have closed, subsequent calls to
@ -436,7 +436,7 @@ Pipes and FIFOs
create (if not already created).
:param mode: Ignored for now
:return: 0 is returned on success; otherwise, -1 is returned with errno set appropriately.
:return: 0 is returned on success; otherwise, -1 is returned with errno set appropriately.
``mmap()`` and eXecute In Place (XIP)
-------------------------------------
@ -524,7 +524,7 @@ are two conditions where ``mmap()`` can be supported:
.. c:function:: FAR void *mmap(FAR void *start, size_t length, int prot, int flags, int fd, off_t offset);
Provides minimal mmap() as needed to support eXecute In Place (XIP) operation (as described above).
Provides minimal mmap() as needed to support eXecute In Place (XIP) operation (as described above).
:param start: A hint at where to map the memory -- ignored. The address
of the underlying media is fixed and cannot be re-mapped without MMU

4
Documentation/reference/user/11_network.rst
View File

@ -28,7 +28,7 @@ the following paragraphs.
:param type: (see sys/socket.h)
:param protocol: (see sys/socket.h)
:return:
:return:
0 on success; -1 on error with
``errno`` set appropriately:
@ -278,7 +278,7 @@ the following paragraphs.
.. c:function:: ssize_t recv(int sockfd, void *buf, size_t len, int flags);
The ``recv()`` call is identical to
```recvfrom()`` <#recvfrom>`__ with a NULL ``from`` parameter.

6
Documentation/reference/user/12_shared_memory.rst
View File

@ -10,7 +10,7 @@ memory interfaces:
- :c:func:`shmat`
- :c:func:`shmctl`
- :c:func:`shmdt`
Functions
---------
@ -83,7 +83,7 @@ Functions
because user and group IDs are not yet supported by NuttX.
.. c:function:: void *shmat(int shmid, FAR const void *shmaddr, int shmflg)
Attaches the shared memory
segment associated with the shared memory identifier specified by
``shmid`` to the address space of the calling process. The segment is
@ -199,4 +199,4 @@ Functions
- ``EINVAL``. The value of ``shmaddr`` is not the data segment start
address of a shared memory segment.

2
Documentation/reference/user/index.rst
View File

@ -23,6 +23,6 @@ Porting Guide <NuttxPortingGuide.html#configandbuild>`__.
:maxdepth: 1
:caption: Contents
:glob:
*_*
structures.rst

6
Documentation/reference/user/structures.rst
View File

@ -38,8 +38,8 @@ Access to the ``errno`` Variable
A pointer to the thread-specific ``errno`` value is available through a
function call:
.. c:function:: int *__errno(void)
.. c:function:: int *__errno(void)
``__errno()`` returns a pointer to the thread-specific
``errno`` value. Note that the symbol ``errno`` is defined to be
``__errno()`` so that the usual access by referencing the symbol
@ -66,7 +66,7 @@ User Interface Structures
.. c:type:: int (*main_t)(int argc, char *argv[])
:c:type:`main_t` defines the type of a task entry point. :c:type:`main_t` is declared in
``sys/types.h``.
``sys/types.h``.
.. c:struct:: sched_param

2
Documentation/releases/index.rst
View File

@ -1,6 +1,6 @@
Releases
========
.. todo::
.. todo::
This should link (or include?) release notes. Maybe only show some recent ones and link
older ones