luchianmihai/walnux
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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

4
Documentation/applications/index.rst
View file

@ -1,10 +1,10 @@
.. todo:: .. todo::
Applications included in ``apps`` repo should be documented here. This should also include information 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 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. 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 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. 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 This will involve migrating most of the content existing currently in board README files
to RST documents here. to RST documents here.
Supported Boards 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: structure is shown below:
.. code-block:: c .. code-block:: c
struct symtab_s; struct symtab_s;
struct binary_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 Where the types ``binfmt_ctor_t`` and ``binfmt_dtor_t`` define the type
of one C++ constructor or destructor: of one C++ constructor or destructor:
.. code-block:: c .. code-block:: c
typedef FAR void (*binfmt_ctor_t)(void); typedef FAR void (*binfmt_ctor_t)(void);
typedef FAR void (*binfmt_dtor_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) .. c:function:: int register_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 :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 that 0 (OK) is returned on success and a negated errno is returned on
failure. failure.
.. c:function:: int unregister_binfmt(FAR struct binfmt_s *binfmt) .. 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: :return:
This is a NuttX internal function so it follows the convention 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 that 0 (OK) is returned on success and a negated errno is returned on
failure. failure.
Basic module management Basic module management
~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~
@ -193,12 +193,12 @@ Basic module management
(via :c:func:`exec_module`) and has not exited, calling this will be fatal. (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 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: :return:
This is a NuttX internal function so it follows the convention that 0 (``OK``) 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. is returned on success and a negated ``errno`` is returned on failure.
.. c:function:: int exec_module(FAR const struct binary_s *bin); .. 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`. Execute a module that has been loaded into memory by :c:func:`load_module`.
@ -209,10 +209,10 @@ Basic module management
.. tip:: .. tip::
The function :c:func:`exec` is a convenience function that wraps 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 ``PATH`` traversal logic
~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~
.. c:function:: ENVPATH_HANDLE envpath_init(void); .. 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 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. :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 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) .. 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 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 handle: The handle value returned by :c:func:`envpath_init`.
:param relpath: The relative path to the file to be found. :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. 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 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). 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 handle value was created. The handle value is invalid on
return from this function. Attempts to all :c:func:`envpath_next` return from this function. Attempts to all :c:func:`envpath_next`
or :c:func:`envpath_release` with such a stale handle will result 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`. :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. Describes one entry in the symbol table.
.. code-block:: c .. code-block:: c
struct symtab_s struct symtab_s
{ {
FAR const char *sym_name; /* A pointer to the symbol name string */ FAR const char *sym_name; /* A pointer to the symbol name string */
@ -326,16 +326,16 @@ Symbol Table Function Interfaces
to ``nsyms``. to ``nsyms``.
:return: :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); .. 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. 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: :return:
A reference to the symbol table entry if an entry with 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); .. 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 Find the symbol in the symbol table whose value closest
(but not greater than), the provided value. This version assumes (but not greater than), the provided value. This version assumes
that table is not ordered with respect to symbol name and, hence, 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: :return:
A reference to the symbol table entry if an entry with the matching 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. name is found; ``NULL`` is returned if the entry is not found.
Configuration Variables Configuration Variables
======================= =======================

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

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

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

@ -16,7 +16,7 @@ locations:
reside in ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>* reside in ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>*
directory for the specific processor *<architecture>* and for directory for the specific processor *<architecture>* and for
the specific *<chip>* timer peripheral devices. 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``. 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 .. code-block:: console
@ -49,30 +49,30 @@ Enabling the Timer Support and Example in ``menuconfing``
- [x] Timer example - [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 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 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: Use the following command to run the example:
.. code-block:: console .. code-block:: console
`nsh> timer` `nsh> timer`
This command will use the timer 0. To use the others, specify it through a parameter (where x is the timer number): 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 .. code-block:: console
`nsh> timer -d /dev/timerx` `nsh> timer -d /dev/timerx`
Application Level Interface 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: 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_START
.. c:macro:: TCIOC_STOP .. c:macro:: TCIOC_STOP
.. c:macro:: TCIOC_GETSTATUS .. c:macro:: TCIOC_GETSTATUS
.. c:macro:: TCIOC_SETTIMEOUT .. c:macro:: TCIOC_SETTIMEOUT
.. c:macro:: TCIOC_NOTIFICATION .. c:macro:: TCIOC_NOTIFICATION
.. c:macro:: TCIOC_MAXTIMEOUT .. 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. 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 .. 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. 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 .. 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. 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 .. 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. 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 .. code-block:: c
@ -273,11 +273,11 @@ This command may be used like so:
.. c:macro:: TCIOC_NOTIFICATION .. 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. 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 .. 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) .. 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. :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 .. 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. 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 Device Drivers
============== ==============
NuttX supports a variety of device drivers, which can be broadly NuttX supports a variety of device drivers, which can be broadly
divided in three classes: divided in three classes:
@ -10,8 +10,8 @@ divided in three classes:
character/index.rst character/index.rst
block/index.rst block/index.rst
special/index.rst special/index.rst
.. note:: .. note::
Device driver support depends on the *in-memory*, *pseudo* Device driver support depends on the *in-memory*, *pseudo*
file system that is enabled by default. file system that is enabled by default.

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

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

4
Documentation/components/index.rst
View file

@ -1,8 +1,8 @@
OS Components 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:: .. toctree::
:maxdepth: 2 :maxdepth: 2
:caption: Contents: :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: that in ``apps/examples/hello/Makefile`` is abstracted below:
#. First, the ``Makefile`` includes ``apps/Make.defs``:: #. First, the ``Makefile`` includes ``apps/Make.defs``::
include $(APPDIR)/Make.defs include $(APPDIR)/Make.defs
This defines a macro called ``REGISTER`` that adds data to the This defines a macro called ``REGISTER`` that adds data to the
*builtin* header files:: *builtin* header files::
define REGISTER define REGISTER
@echo "Register: $1" @echo "Register: $1"
@echo "{ \"$1\", $2, $3, $4 }," >> "$(APPDIR)/builtin/builtin_list.h" @echo "{ \"$1\", $2, $3, $4 }," >> "$(APPDIR)/builtin/builtin_list.h"
@echo "EXTERN int $4(int argc, char *argv[]);" >> "$(APPDIR)/builtin/builtin_proto.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 When this macro runs, you will see the output in the build
"``Register: hello``", that is a sure sign that the registration was "``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 #. The make file then defines the application name (``hello``), the task
priority (default), and the stack size that will be allocated in the priority (default), and the stack size that will be allocated in the
task runs (2K):: task runs (2K)::
APPNAME = hello APPNAME = hello
PRIORITY = SCHED_PRIORITY_DEFAULT PRIORITY = SCHED_PRIORITY_DEFAULT
STACKSIZE = 2048 STACKSIZE = 2048
#. And finally, the ``Makefile`` invokes the ``REGISTER`` macro to added #. And finally, the ``Makefile`` invokes the ``REGISTER`` macro to added
the ``hello_main()`` builtin application. Then, when the system build the ``hello_main()`` builtin application. Then, when the system build
completes, the ``hello`` command can be executed from the NSH command completes, the ``hello`` command can be executed from the NSH command
line. When the ``hello`` command is executed, it will start the task line. When the ``hello`` command is executed, it will start the task
with entry point ``hello_main()`` with the default priority and with with entry point ``hello_main()`` with the default priority and with
a stack size of 2K:: a stack size of 2K::
context: context:
$(call REGISTER,$(APPNAME),$(PRIORITY),$(STACKSIZE),$(APPNAME)_main) $(call REGISTER,$(APPNAME),$(PRIORITY),$(STACKSIZE),$(APPNAME)_main)
**Other Uses of Built-In Application.** The primary purpose of builtin **Other Uses of Built-In Application.** The primary purpose of builtin
applications is to support command line execution of applications from 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 #. Using ``export`` to promote an NSH variable to an environment
variable:: variable::
nsh> env nsh> env
PATH=/bin PATH=/bin
@ -417,7 +417,7 @@ examples:
nsh> export foo nsh> export foo
nsh> env nsh> env
PATH=/bin PATH=/bin
foo=bar foo=bar
A group-wide environment variable is created with the same A group-wide environment variable is created with the same
value as the local NSH variable; the local NSH variable is 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. environment variable of the same name and same value.
#. Using ``export`` to set an environment variable:: #. Using ``export`` to set an environment variable::
nsh> export dog poop nsh> export dog poop
nsh> env nsh> env
PATH=/bin PATH=/bin
foo=bar foo=bar
dog=poop dog=poop
The ``export`` command is not supported by NSH unless both The ``export`` command is not supported by NSH unless both
``CONFIG_NSH_VARS=y`` and ``CONFIG_DISABLE_ENVIRON``\ is not set. ``CONFIG_NSH_VARS=y`` and ``CONFIG_DISABLE_ENVIRON``\ is not set.
@ -452,7 +452,7 @@ example::
total used free largest total used free largest
Mem: 4194288 1591552 2602736 2601584 Mem: 4194288 1591552 2602736 2601584
nsh> nsh>
**Where:** **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. ``-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). ``-n`` Selects text ("netascii") transfer mode (default).
``-b`` Selects binary ("octet") transfer mode ``-b`` Selects binary ("octet") transfer mode
=================== ============================================ =================== ============================================
Show Usage Command Usage (help) Show Usage Command Usage (help)
@ -509,7 +509,7 @@ character device
================= ================================== ================= ==================================
``skip=<bytes>`` Will skip <bytes> number of bytes from the beginning. ``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 The ``skip`` and ``count`` options are only available if
@ -529,9 +529,9 @@ supported:
#. With one or no arguments, ``ifconfig`` will shows the current #. With one or no arguments, ``ifconfig`` will shows the current
configuration of the network and, perhaps, the status of configuration of the network and, perhaps, the status of
Ethernet device:: Ethernet device::
ifconfig ifconfig
ifconfig [nic_name] ifconfig [nic_name]
As an example:: As an example::
@ -545,7 +545,7 @@ supported:
#. If both the network interface name and an IP address are #. If both the network interface name and an IP address are
supplied as arguments, then ``ifconfig`` will set the address supplied as arguments, then ``ifconfig`` will set the address
of the Ethernet device:: of the Ethernet device::
ifconfig nic_name ip_address ifconfig nic_name ip_address
#. Other forms *to be provided* #. Other forms *to be provided*
@ -553,7 +553,7 @@ supported:
.. note:: This commands depends upon having the *procfs* file system .. note:: This commands depends upon having the *procfs* file system
configured into the system. The *procfs* file system must also configured into the system. The *procfs* file system must also
have been mounted with a command like:: have been mounted with a command like::
nsh> mount -t procfs /proc nsh> mount -t procfs /proc
Take a network down (ifdown) 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-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>`` Perform the mb, mh, or mw operation on a total of
<hex-byte-count> bytes, increment the <hex-address> <hex-byte-count> bytes, increment the <hex-address>
appropriately after each access. appropriately after each access.
============================= ============================================== ============================= ==============================================
**Example**:: **Example**::
@ -1225,7 +1225,7 @@ names in the *pseudo* file system.
TESTFILE.TXT TESTFILE.TXT
nsh> nsh>
Remove a Directory (rmdir) Remove a Directory (rmdir)
************************** **************************
**Command Syntax**:: **Command Syntax**::
@ -1541,7 +1541,7 @@ output is the same as -s.
``-v`` Print the kernel version ``-v`` Print the kernel version
``-m`` Print the machine hardware name ``-m`` Print the machine hardware name
``-i`` Print the machine platform name ``-i`` Print the machine platform name
``-p`` Print "unknown" ``-p`` Print "unknown"
========== ======================================== ========== ========================================
Unset an Environment Variable (unset) 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`` ``addroute`` ``CONFIG_NET`` && ``CONFIG_NET_ROUTE`` ``CONFIG_NSH_DISABLE_ADDROUTE``
``arp`` ``CONFIG_NET`` && ``CONFIG_NET_ARP`` ``CONFIG_NSH_DISABLE_ARP`` ``arp`` ``CONFIG_NET`` && ``CONFIG_NET_ARP`` ``CONFIG_NSH_DISABLE_ARP``
``base64dec`` ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_BASE64DEC`` ``base64dec`` ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_BASE64DEC``
``CONFIG_CODECS_BASE64`` ``CONFIG_CODECS_BASE64``
``base64enc`` ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_BASE64ENC`` ``base64enc`` ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_BASE64ENC``
``CONFIG_CODECS_BASE64`` ``CONFIG_CODECS_BASE64``
``basename`` . ``CONFIG_NSH_DISABLE_BASENAME`` ``basename`` . ``CONFIG_NSH_DISABLE_BASENAME``
``break`` ! ``CONFIG_NSH_DISABLESCRIPT`` && . ``break`` ! ``CONFIG_NSH_DISABLESCRIPT`` && .
! ``CONFIG_NSH_DISABLE_LOOPS``   ! ``CONFIG_NSH_DISABLE_LOOPS``  
``cat`` ``CONFIG_NSH_DISABLE_CAT`` . ``cat`` ``CONFIG_NSH_DISABLE_CAT`` .
@ -59,9 +59,9 @@ Command Depends on Configuration Can Be Disabl
``help`` [#3]_ ``CONFIG_NSH_DISABLE_HELP`` . ``help`` [#3]_ ``CONFIG_NSH_DISABLE_HELP`` .
``hexdump`` ``CONFIG_NSH_DISABLE_HEXDUMP`` . ``hexdump`` ``CONFIG_NSH_DISABLE_HEXDUMP`` .
``ifconfig`` ``CONFIG_NET`` && ``CONFIG_FS_PROCFS`` && ``CONFIG_NSH_DISABLE_IFCONFIG`` ``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`` ``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`` && ``ifup`` ``CONFIG_NET`` && ``CONFIG_FS_PROCFS`` &&
! ``CONFIG_FS_PROCFS_EXCLUDE_NET`` ``CONFIG_NSH_DISABLE_IFUPDOWN`` ! ``CONFIG_FS_PROCFS_EXCLUDE_NET`` ``CONFIG_NSH_DISABLE_IFUPDOWN``
``insmod`` ``CONFIG_MODULE`` ``CONFIG_NSH_DISABLE_MODCMDS`` ``insmod`` ``CONFIG_MODULE`` ``CONFIG_NSH_DISABLE_MODCMDS``
@ -70,37 +70,37 @@ Command Depends on Configuration Can Be Disabl
``CONFIG_SCHED_IRQMONITOR`` ``CONFIG_SCHED_IRQMONITOR``
``kill`` ``CONFIG_NSH_DISABLE_KILL`` . ``kill`` ``CONFIG_NSH_DISABLE_KILL`` .
``losetup`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_LOSETUP`` ``losetup`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_LOSETUP``
``CONFIG_DEV_LOOP`` ``CONFIG_DEV_LOOP``
``ln`` ``CONFIG_PSEUDOFS_SOFTLINKS`` ``CONFIG_NSH_DISABLE_LN`` ``ln`` ``CONFIG_PSEUDOFS_SOFTLINKS`` ``CONFIG_NSH_DISABLE_LN``
``ls`` ``CONFIG_NSH_DISABLE_LS`` . ``ls`` ``CONFIG_NSH_DISABLE_LS`` .
``lsmod`` ``CONFIG_MODULE`` && ``CONFIG_FS_PROCFS`` ``CONFIG_NSH_DISABLE_MODCMDS`` ``lsmod`` ``CONFIG_MODULE`` && ``CONFIG_FS_PROCFS`` ``CONFIG_NSH_DISABLE_MODCMDS``
&& |br| && |br|
! ``CONFIG_FS_PROCFS_EXCLUDE_MODULE`` ! ``CONFIG_FS_PROCFS_EXCLUDE_MODULE``
``md5`` ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_MD5`` ``md5`` ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_MD5``
``CONFIG_CODECS_HASH_MD5`` ``CONFIG_CODECS_HASH_MD5``
``mb,mh,mw`` . ``CONFIG_NSH_DISABLE_MB``, |br| ``mb,mh,mw`` . ``CONFIG_NSH_DISABLE_MB``, |br|
``CONFIG_NSH_DISABLE_MH``, |br| ``CONFIG_NSH_DISABLE_MH``, |br|
``CONFIG_NSH_DISABLE_MW`` ``CONFIG_NSH_DISABLE_MW``
``mkdir`` (! ``CONFIG_DISABLE_MOUNTPOINT`` \|\| ``CONFIG_NSH_DISABLE_MKDIR`` ``mkdir`` (! ``CONFIG_DISABLE_MOUNTPOINT`` \|\| ``CONFIG_NSH_DISABLE_MKDIR``
! ``CONFIG_DISABLE_PSEUDOFS_OPERATIONS``) ! ``CONFIG_DISABLE_PSEUDOFS_OPERATIONS``)
``mkfatfs`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_MKFATFS`` ``mkfatfs`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_MKFATFS``
``CONFIG_FSUTILS_MKFATFS`` ``CONFIG_FSUTILS_MKFATFS``
``mkfifo`` ``CONFIG_PIPES`` && ``CONFIG_NSH_DISABLE_MKFIFO`` ``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`` ``mkrd`` ! ``CONFIG_DISABLE_MOUNTPOINT`` ``CONFIG_NSH_DISABLE_MKRD``
``mount`` ! ``CONFIG_DISABLE_MOUNTPOINT`` ``CONFIG_NSH_DISABLE_MOUNT`` ``mount`` ! ``CONFIG_DISABLE_MOUNTPOINT`` ``CONFIG_NSH_DISABLE_MOUNT``
``mv`` ! ``CONFIG_DISABLE_MOUNTPOINT`` \|\| ``CONFIG_NSH_DISABLE_MV`` ``mv`` ! ``CONFIG_DISABLE_MOUNTPOINT`` \|\| ``CONFIG_NSH_DISABLE_MV``
! ``CONFIG_DISABLE_PSEUDOFS_OPERATIONS`` ! ``CONFIG_DISABLE_PSEUDOFS_OPERATIONS``
``nfsmount`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_NFSMOUNT`` ``nfsmount`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_NFSMOUNT``
``CONFIG_NET`` && ``CONFIG_NFS`` ``CONFIG_NET`` && ``CONFIG_NFS``
``nslookup`` ``CONFIG_LIBC_NETDB`` && ``CONFIG_NSH_DISABLE_NSLOOKUP`` ``nslookup`` ``CONFIG_LIBC_NETDB`` && ``CONFIG_NSH_DISABLE_NSLOOKUP``
``CONFIG_NETDB_DNSCLIENT`` ``CONFIG_NETDB_DNSCLIENT``
``passwd`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_PASSWD`` ``passwd`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_PASSWD``
``CONFIG_NSH_LOGIN_PASSWD`` ``CONFIG_NSH_LOGIN_PASSWD``
``pmconfig`` ``CONFIG_PM`` ``CONFIG_NSH_DISABLE_PMCONFIG`` ``pmconfig`` ``CONFIG_PM`` ``CONFIG_NSH_DISABLE_PMCONFIG``
``poweroff`` ``CONFIG_BOARDCTL_POWEROFF`` ``CONFIG_NSH_DISABLE_POWEROFF`` ``poweroff`` ``CONFIG_BOARDCTL_POWEROFF`` ``CONFIG_NSH_DISABLE_POWEROFF``
``ps`` ``CONFIG_FS_PROCFS`` && ``CONFIG_NSH_DISABLE_PS`` ``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`` ``put`` ``CONFIG_NET`` && ``CONFIG_NET_UDP`` && ``CONFIG_NSH_DISABLE_PUT``
``MTU >= 558`` [#1]_, [#2]_ ``MTU >= 558`` [#1]_, [#2]_
``pwd`` ! ``CONFIG_DISABLE_ENVIRON`` ``CONFIG_NSH_DISABLE_PWD`` ``pwd`` ! ``CONFIG_DISABLE_ENVIRON`` ``CONFIG_NSH_DISABLE_PWD``
@ -120,22 +120,22 @@ Command Depends on Configuration Can Be Disabl
``CONFIG_NET_IPv6``) ``CONFIG_NET_IPv6``)
``rptun`` ``CONFIG_RPTUN`` ``CONFIG_NSH_DISABLE_RPTUN`` ``rptun`` ``CONFIG_RPTUN`` ``CONFIG_NSH_DISABLE_RPTUN``
``set`` ``CONFIG_NSH_VARS`` \|\| ``CONFIG_NSH_DISABLE_SET`` ``set`` ``CONFIG_NSH_VARS`` \|\| ``CONFIG_NSH_DISABLE_SET``
! ``CONFIG_DISABLE_ENVIRON`` ! ``CONFIG_DISABLE_ENVIRON``
``shutdown`` ``CONFIG_BOARDCTL_POWEROFF`` \|\| ``CONFIG_NSH_DISABLE_SHUTDOWN`` ``shutdown`` ``CONFIG_BOARDCTL_POWEROFF`` \|\| ``CONFIG_NSH_DISABLE_SHUTDOWN``
``CONFIG_BOARD_RESET`` ``CONFIG_BOARD_RESET``
``sleep`` . ``CONFIG_NSH_DISABLE_SLEEP`` ``sleep`` . ``CONFIG_NSH_DISABLE_SLEEP``
``source`` ``CONFIG_FILE_STREAM`` && ``CONFIG_NSH_DISABLE_SOURCE`` ``source`` ``CONFIG_FILE_STREAM`` && ``CONFIG_NSH_DISABLE_SOURCE``
! ``CONFIG_NSH_DISABLESCRIPT`` ! ``CONFIG_NSH_DISABLESCRIPT``
``telnetd`` ``CONFIG_NSH_TELNET`` ``CONFIG_NSH_DISABLE_TELNETD`` ``telnetd`` ``CONFIG_NSH_TELNET`` ``CONFIG_NSH_DISABLE_TELNETD``
``test`` ! ``CONFIG_NSH_DISABLESCRIPT`` ``CONFIG_NSH_DISABLE_TEST`` ``test`` ! ``CONFIG_NSH_DISABLESCRIPT`` ``CONFIG_NSH_DISABLE_TEST``
``time`` . ``CONFIG_NSH_DISABLE_TIME`` ``time`` . ``CONFIG_NSH_DISABLE_TIME``
``truncate`` ! ``CONFIG_DISABLE_MOUNTPOINT`` ``CONFIG_NSH_DISABLE_TRUNCATE`` ``truncate`` ! ``CONFIG_DISABLE_MOUNTPOINT`` ``CONFIG_NSH_DISABLE_TRUNCATE``
``umount`` ! ``CONFIG_DISABLE_MOUNTPOINT`` ``CONFIG_NSH_DISABLE_UMOUNT`` ``umount`` ! ``CONFIG_DISABLE_MOUNTPOINT`` ``CONFIG_NSH_DISABLE_UMOUNT``
``uname`` . ``CONFIG_NSH_DISABLE_UNAME`` ``uname`` . ``CONFIG_NSH_DISABLE_UNAME``
``unset`` ``CONFIG_NSH_VARS`` \|\| ``CONFIG_NSH_DISABLE_UNSET`` ``unset`` ``CONFIG_NSH_VARS`` \|\| ``CONFIG_NSH_DISABLE_UNSET``
! ``CONFIG_DISABLE_ENVIRON`` ! ``CONFIG_DISABLE_ENVIRON``
``urldecode`` ! ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_URLDECODE`` ``urldecode`` ! ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_URLDECODE``
``CONFIG_CODECS_URLCODE`` ``CONFIG_CODECS_URLCODE``
``urlencode`` ! ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_URLENCODE`` ``urlencode`` ! ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_URLENCODE``
``CONFIG_CODECS_URLCODE`` ``CONFIG_CODECS_URLCODE``
``useradd`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_USERADD`` ``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: ``boards/<arch>/<chip>/<board>/defconfig`` file:
=================================== ================================== =================================== ==================================
Configuration Description Configuration Description
=================================== ================================== =================================== ==================================
``CONFIG_NSH_READLINE`` Selects the minimal implementation of ``readline()``. ``CONFIG_NSH_READLINE`` Selects the minimal implementation of ``readline()``.
This minimal implementation provides on backspace for command This minimal implementation provides on backspace for command
line editing. It expects some minimal VT100 command support from the terminal. line editing. It expects some minimal VT100 command support from the terminal.
``CONFIG_NSH_CLE`` Selects the more extensive, EMACS-like command line editor. ``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 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 in the FLASH footprint, and (2) you work with a terminal that
supports extensive VT100 editing commands. Selecting this option supports extensive VT100 editing commands. Selecting this option
will add probably 1.5-2KB to the FLASH footprint. will add probably 1.5-2KB to the FLASH footprint.
``CONFIG_NSH_BUILTIN_APPS`` Support external registered, "builtin" applications that can ``CONFIG_NSH_BUILTIN_APPS`` Support external registered, "builtin" applications that can
be executed from the NSH command line (see apps/README.txt for be executed from the NSH command line (see apps/README.txt for
more information). This required ``CONFIG_BUILTIN`` to enable more information). This required ``CONFIG_BUILTIN`` to enable
NuttX support for "builtin" applications. NuttX support for "builtin" applications.
``CONFIG_NSH_FILEIOSIZE`` Size of a static I/O buffer used for file access (ignored if there ``CONFIG_NSH_FILEIOSIZE`` Size of a static I/O buffer used for file access (ignored if there
is no file system). Default is 1024. is no file system). Default is 1024.
``CONFIG_NSH_STRERROR`` ``strerror(errno)`` makes more readable output but ``CONFIG_NSH_STRERROR`` ``strerror(errno)`` makes more readable output but
``strerror()`` is very large and will not be used unless this ``strerror()`` is very large and will not be used unless this
setting is *y*. This setting depends upon the ``strerror()`` setting is *y*. This setting depends upon the ``strerror()``
having been enabled with ``CONFIG_LIBC_STRERROR``. having been enabled with ``CONFIG_LIBC_STRERROR``.
``CONFIG_NSH_LINELEN`` The maximum length of one command line and of one output line. ``CONFIG_NSH_LINELEN`` The maximum length of one command line and of one output line.
Default: 80 Default: 80
``CONFIG_NSH_DISABLE_SEMICOLON`` By default, you can enter multiple NSH commands on a line ``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 with each command separated by a semicolon. You can disable this
feature to save a little memory on FLASH challenged platforms. feature to save a little memory on FLASH challenged platforms.
Default: n Default: n
``CONFIG_NSH_CMDPARMS`` If selected, then the output from commands, from file applications, ``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 and from NSH built-in commands can be used as arguments to other
commands. The entity to be executed is identified by commands. The entity to be executed is identified by
enclosing the command line in back quotes. For example:: enclosing the command line in back quotes. For example::
set FOO `myprogram $BAR` set FOO `myprogram $BAR`
will execute the program named ``myprogram`` passing it the will execute the program named ``myprogram`` passing it the
value of the environment variable ``BAR``. The value of the value of the environment variable ``BAR``. The value of the
environment variable ``FOO`` is then set output of ``myprogram`` environment variable ``FOO`` is then set output of ``myprogram``
on ``stdout``. Because this feature commits significant on ``stdout``. Because this feature commits significant
resources, it is disabled by default. The ``CONFIG_NSH_CMDPARMS`` interim resources, it is disabled by default. The ``CONFIG_NSH_CMDPARMS`` interim
output will be retained in a temporary file. Full path to a output will be retained in a temporary file. Full path to a
directory where temporary files can be created is taken from directory where temporary files can be created is taken from
``CONFIG_LIBC_TMPDIR`` and it defaults to ``/tmp`` if ``CONFIG_LIBC_TMPDIR`` and it defaults to ``/tmp`` if
``CONFIG_LIBC_TMPDIR`` is not set. ``CONFIG_LIBC_TMPDIR`` is not set.
``CONFIG_NSH_MAXARGUMENTS`` The maximum number of NSH command arguments. Default: 6 ``CONFIG_NSH_MAXARGUMENTS`` The maximum number of NSH command arguments. Default: 6
``CONFIG_NSH_ARGCAT`` Support concatenation of strings with environment variables or ``CONFIG_NSH_ARGCAT`` Support concatenation of strings with environment variables or
command output. For example:: command output. For example::
set FOO XYZ set FOO XYZ
set BAR 123 set BAR 123
set FOOBAR ABC_${FOO}_${BAR} set FOOBAR ABC_${FOO}_${BAR}
would set the environment variable ``FOO`` to ``XYZ``, would set the environment variable ``FOO`` to ``XYZ``,
``BAR`` to ``123`` and ``FOOBAR`` to ``ABC_XYZ_123``. If ``BAR`` to ``123`` and ``FOOBAR`` to ``ABC_XYZ_123``. If
``CONFIG_NSH_ARGCAT`` is not selected, then a slightly small ``CONFIG_NSH_ARGCAT`` is not selected, then a slightly small
FLASH footprint results but then also only simple environment FLASH footprint results but then also only simple environment
variables like ``$FOO`` can be used on the command line. 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 ``CONFIG_NSH_VARS`` By default, there are no internal NSH variables. NSH will use OS
environment variables for all variable storage. If this option, environment variables for all variable storage. If this option,
NSH will also support local NSH variables. These variables are, NSH will also support local NSH variables. These variables are,
for the most part, transparent and work just like the OS for the most part, transparent and work just like the OS
environment variables. The difference is that when you environment variables. The difference is that when you
create new tasks, all of environment variables are create new tasks, all of environment variables are
inherited by the created tasks. NSH local variables are not. inherited by the created tasks. NSH local variables are not.
If this option is enabled (and ``CONFIG_DISABLE_ENVIRON`` is not), If this option is enabled (and ``CONFIG_DISABLE_ENVIRON`` is not),
then a new command called 'export' is enabled. The export then a new command called 'export' is enabled. The export
command works very must like the set command except that is command works very must like the set command except that is
operates on environment variables. When CONFIG_NSH_VARS operates on environment variables. When CONFIG_NSH_VARS
is enabled, there are changes in the behavior of certain commands. is enabled, there are changes in the behavior of certain commands.
See following :ref:`table <nsh_vars_table>`. See following :ref:`table <nsh_vars_table>`.
``CONFIG_NSH_QUOTE`` Enables back-slash quoting of certain characters within the ``CONFIG_NSH_QUOTE`` Enables back-slash quoting of certain characters within the
command. This option is useful for the case where an NSH script command. This option is useful for the case where an NSH script
is used to dynamically generate a new NSH script. In that case, is used to dynamically generate a new NSH script. In that case,
commands must be treated as simple text strings without commands must be treated as simple text strings without
interpretation of any special characters. Special characters interpretation of any special characters. Special characters
such as ``$``, :literal:`\``, ``"``, and others must be such as ``$``, :literal:`\``, ``"``, and others must be
retained intact as part of the test string. This option is retained intact as part of the test string. This option is
currently only available is ``CONFIG_NSH_ARGCAT`` is also currently only available is ``CONFIG_NSH_ARGCAT`` is also
selected. selected.
``CONFIG_NSH_NESTDEPTH`` The maximum number of nested ``if-then[-else]-fi`` <#conditional>`__ ``CONFIG_NSH_NESTDEPTH`` The maximum number of nested ``if-then[-else]-fi`` <#conditional>`__
sequences that are permissible. Default: 3 sequences that are permissible. Default: 3
``CONFIG_NSH_DISABLESCRIPT`` This can be set to *y* to suppress support for scripting. ``CONFIG_NSH_DISABLESCRIPT`` This can be set to *y* to suppress support for scripting.
This setting disables the ```sh`` <#cmdsh>`__, This setting disables the ```sh`` <#cmdsh>`__,
```test`` <#cmdtest>`__, and ```[`` <#cmtest>`__ commands and ```test`` <#cmdtest>`__, and ```[`` <#cmtest>`__ commands and
the ```if-then[-else]-fi`` <#conditional>`__ the ```if-then[-else]-fi`` <#conditional>`__
construct. This would only be set on systems where a minimal construct. This would only be set on systems where a minimal
footprint is a necessity and scripting is not. footprint is a necessity and scripting is not.
``CONFIG_NSH_DISABLE_ITEF`` If scripting is enabled, then then this option can be selected ``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 to suppress support for ``if-then-else-fi`` sequences in
scripts. This would only be set on systems where some minimal scripts. This would only be set on systems where some minimal
scripting is required but ``if-then-else-fi`` is not. 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 ``CONFIG_NSH_DISABLE_LOOPS`` If scripting is enabled, then then this option can be selected
suppress support ``for while-do-done`` and suppress support ``for while-do-done`` and
``until-do-done`` sequences in scripts. This would only be set ``until-do-done`` sequences in scripts. This would only be set
on systems where some minimal scripting is required but looping on systems where some minimal scripting is required but looping
is not. is not.
``CONFIG_NSH_DISABLEBG`` This can be set to *y* to suppress support for background ``CONFIG_NSH_DISABLEBG`` This can be set to *y* to suppress support for background
commands. This setting disables the ```nice`` <#cmdoverview>`__ commands. This setting disables the ```nice`` <#cmdoverview>`__
command prefix and the ```&`` <#cmdoverview>`__ command command prefix and the ```&`` <#cmdoverview>`__ command
suffix. This would only be set on systems where a minimal footprint suffix. This would only be set on systems where a minimal footprint
is a necessity and background command execution is not. is a necessity and background command execution is not.
``CONFIG_NSH_MMCSDMINOR`` If the architecture supports an MMC/SD slot and if the NSH ``CONFIG_NSH_MMCSDMINOR`` If the architecture supports an MMC/SD slot and if the NSH
architecture specific logic is present, this option will provide architecture specific logic is present, this option will provide
the MMC/SD minor number, i.e., the MMC/SD block driver will be 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. registered as ``/dev/mmcsd``\ *N* where *N* is the minor number.
Default is zero. Default is zero.
``CONFIG_NSH_ROMFSETC`` Mount a ROMFS file system at ``/etc`` and provide a startup ``CONFIG_NSH_ROMFSETC`` Mount a ROMFS file system at ``/etc`` and provide a startup
script at ``/etc/init.d/rcS``. script at ``/etc/init.d/rcS``.
The default startup script will mount a FAT FS RAMDISK at The default startup script will mount a FAT FS RAMDISK at
``/tmp`` but the logic is `easily extensible <#startupscript>`__. ``/tmp`` but the logic is `easily extensible <#startupscript>`__.
``CONFIG_NSH_CONSOLE`` If ``CONFIG_NSH_CONSOLE`` is set to *y*, then a serial console ``CONFIG_NSH_CONSOLE`` If ``CONFIG_NSH_CONSOLE`` is set to *y*, then a serial console
front-end is selected. front-end is selected.
Normally, the serial console device is a UART and RS-232 Normally, the serial console device is a UART and RS-232
interface. However, if ``CONFIG_USBDEV`` is defined, interface. However, if ``CONFIG_USBDEV`` is defined,
then a USB serial device may, instead, be used if the one of then a USB serial device may, instead, be used if the one of
the following are defined: the following are defined:
- ``CONFIG_PL2303`` and ``CONFIG_PL2303_CONSOLE``. - ``CONFIG_PL2303`` and ``CONFIG_PL2303_CONSOLE``.
Sets up the Prolifics PL2303 emulation as a console device Sets up the Prolifics PL2303 emulation as a console device
at ``/dev/console``. at ``/dev/console``.
- ``CONFIG_CDCACM`` and ``CONFIG_CDCACM_CONSOLE``. - ``CONFIG_CDCACM`` and ``CONFIG_CDCACM_CONSOLE``.
Sets up the CDC/ACM serial device as a console device at Sets up the CDC/ACM serial device as a console device at
``/dev/console``. ``/dev/console``.
- ``CONFIG_NSH_USBCONSOLE``. If defined, then an arbitrary USB - ``CONFIG_NSH_USBCONSOLE``. If defined, then an arbitrary USB
device may be used to as the NSH console. In this case, device may be used to as the NSH console. In this case,
``CONFIG_NSH_USBCONDEV`` must be defined to indicate which ``CONFIG_NSH_USBCONDEV`` must be defined to indicate which
USB device to use as the console. The advantage of USB device to use as the console. The advantage of
using a device other that ``/dev/console`` is that using a device other that ``/dev/console`` is that
normal debug output can then use ``/dev/console`` while NSH normal debug output can then use ``/dev/console`` while NSH
uses ``CONFIG_NSH_USBCONDEV``. uses ``CONFIG_NSH_USBCONDEV``.
``CONFIG_NSH_USBCONDEV``. If ``CONFIG_NSH_USBCONSOLE`` is ``CONFIG_NSH_USBCONDEV``. If ``CONFIG_NSH_USBCONSOLE`` is
set to 'y', then ``CONFIG_NSH_USBCONDEV`` must also be set to select the USB 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 device used to support the NSH console. This should be set to
the quoted name of a readable/write-able USB driver the quoted name of a readable/write-able USB driver
such as: ``CONFIG_NSH_USBCONDEV="/dev/ttyACM0"``. such as: ``CONFIG_NSH_USBCONDEV="/dev/ttyACM0"``.
If there are more than one USB slots, then a USB device minor If there are more than one USB slots, then a USB device minor
number may also need to be provided: number may also need to be provided:
- ``CONFIG_NSH_UBSDEV_MINOR``: The minor device number of the USB device. Default: 0 - ``CONFIG_NSH_UBSDEV_MINOR``: The minor device number of the USB device. Default: 0
If USB tracing is enabled (``CONFIG_USBDEV_TRACE``), then If USB tracing is enabled (``CONFIG_USBDEV_TRACE``), then
NSH will initialize USB tracing as requested by the following. NSH will initialize USB tracing as requested by the following.
Default: Only USB errors are traced. Default: Only USB errors are traced.
- ``CONFIG_NSH_USBDEV_TRACEINIT``: Show initialization events - ``CONFIG_NSH_USBDEV_TRACEINIT``: Show initialization events
- ``CONFIG_NSH_USBDEV_TRACECLASS``: Show class driver events - ``CONFIG_NSH_USBDEV_TRACECLASS``: Show class driver events
- ``CONFIG_NSH_USBDEV_TRACETRANSFERS``: Show data transfer events - ``CONFIG_NSH_USBDEV_TRACETRANSFERS``: Show data transfer events
- ``CONFIG_NSH_USBDEV_TRACECONTROLLER``: Show controller events - ``CONFIG_NSH_USBDEV_TRACECONTROLLER``: Show controller events
- ``CONFIG_NSH_USBDEV_TRACEINTERRUPTS``: Show interrupt-related events. - ``CONFIG_NSH_USBDEV_TRACEINTERRUPTS``: Show interrupt-related events.
``CONFIG_NSH_ALTCONDEV`` and If ``CONFIG_NSH_CONSOLE`` is set ``CONFIG_NSH_CONDEV`` ``CONFIG_NSH_ALTCONDEV`` and If ``CONFIG_NSH_CONSOLE`` is set ``CONFIG_NSH_CONDEV``
to *y*, then ``CONFIG_NSH_ALTCONDEV`` may also to *y*, then ``CONFIG_NSH_ALTCONDEV`` may also
be selected to enable use of an alternate character device to be selected to enable use of an alternate character device to
support the NSH console. If ``CONFIG_NSH_ALTCONDEV`` is support the NSH console. If ``CONFIG_NSH_ALTCONDEV`` is
selected, then ``CONFIG_NSH_CONDEV`` holds the selected, then ``CONFIG_NSH_CONDEV`` holds the
quoted name of a readable/write-able character quoted name of a readable/write-able character
driver such as: ``CONFIG_NSH_CONDEV="/dev/ttyS1"``. driver such as: ``CONFIG_NSH_CONDEV="/dev/ttyS1"``.
This is useful, for example, to separate the NSH command line This is useful, for example, to separate the NSH command line
from the system console when the system console is used to provide from the system console when the system console is used to provide
debug output. Default: ``stdin`` and ``stdout`` (probably debug output. Default: ``stdin`` and ``stdout`` (probably
"``/dev/console``") "``/dev/console``")
- **NOTE 1:** When any other device other than - **NOTE 1:** When any other device other than
``/dev/console`` is used for a user interface, (1) linefeeds ``/dev/console`` is used for a user interface, (1) linefeeds
(``\n``) will not be expanded to carriage return / linefeeds (``\n``) will not be expanded to carriage return / linefeeds
(``\r\n``). You will need to configure your terminal (``\r\n``). You will need to configure your terminal
program to account for this. program to account for this.
And (2) input is not automatically echoed so you And (2) input is not automatically echoed so you
will have to turn local echo on. will have to turn local echo on.
- **NOTE 2:** This option forces the console of all sessions to - **NOTE 2:** This option forces the console of all sessions to
use NSH_CONDEV. Hence, this option only makes sense for a use NSH_CONDEV. Hence, this option only makes sense for a
system that supports only a single session. This option system that supports only a single session. This option
is, in particular, incompatible with Telnet is, in particular, incompatible with Telnet
sessions because each Telnet session must use a different sessions because each Telnet session must use a different
console device. console device.
``CONFIG_NSH_TELNET`` If ``CONFIG_NSH_TELNET`` is set to *y*, then a TELNET server ``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 front-end is selected. When this option is provided, you may log
into NuttX remotely using telnet in order to access NSH. into NuttX remotely using telnet in order to access NSH.
``CONFIG_NSH_ARCHINIT`` Set ``CONFIG_NSH_ARCHINIT`` if your board provides architecture ``CONFIG_NSH_ARCHINIT`` Set ``CONFIG_NSH_ARCHINIT`` if your board provides architecture
specific initialization via the board-specific function specific initialization via the board-specific function
``board_app_initialize()``. This function will be called early in ``board_app_initialize()``. This function will be called early in
NSH initialization to allow board logic to do such things as NSH initialization to allow board logic to do such things as
configure MMC/SD slots. configure MMC/SD slots.
=================================== ================================== =================================== ==================================
.. _nsh_vars_table: .. _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>). ``export``, in which case the env ironment variable of the same name is set to <b>).
``set`` Causes an error. Lists all NSH variables. ``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> ``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> <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 ``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>. NSH variable has not been set). Unsets NSH local variable <a>.
``env`` Lists all environment variables Lists all environment variables (*only*) ``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, The ROMFS image is, itself, just built into the firmware. By default,
this ``rcS`` start-up script contains the following logic:: this ``rcS`` start-up script contains the following logic::
# Create a RAMDISK and mount it at XXXRDMOUNTPOINTXXX # Create a RAMDISK and mount it at XXXRDMOUNTPOINTXXX
mkrd -m XXXMKRDMINORXXX -s XXMKRDSECTORSIZEXXX XXMKRDBLOCKSXXX mkrd -m XXXMKRDMINORXXX -s XXMKRDSECTORSIZEXXX XXMKRDBLOCKSXXX
@ -80,12 +80,12 @@ The NSH initialization function, ``nsh_initialize()``, be found in
Default: ``/etc`` Default: ``/etc``
By default, the substituted values would yield an ``rcS`` file like:: By default, the substituted values would yield an ``rcS`` file like::
# Create a RAMDISK and mount it at /tmp # Create a RAMDISK and mount it at /tmp
mkrd -m 1 -s 512 1024 mkrd -m 1 -s 512 1024
mkfatfs /dev/ram1 mkfatfs /dev/ram1
mount -t vfat /dev/ram1 /tmp mount -t vfat /dev/ram1 /tmp
This script will, then: 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`. 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. 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:: .. toctree::
:maxdepth: 2 :maxdepth: 2
:caption: Contents :caption: Contents
nsh.rst nsh.rst
commands.rst commands.rst
config.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 - NSH will create a read-only RAM disk (a ROM disk), containing a tiny
ROMFS file system containing the following:: ROMFS file system containing the following::
`--init.d/ `--init.d/
`-- rcS `-- rcS
Where ``rcS`` is the NSH start-up script. Where ``rcS`` is the NSH start-up script.
- NSH will then mount the ROMFS file system at ``/etc``, resulting in:: - NSH will then mount the ROMFS file system at ``/etc``, resulting in::
|--dev/ |--dev/
| `-- ram0 | `-- ram0
`--etc/ `--etc/
`--init.d/ `--init.d/
`-- rcS `-- rcS
- By default, the contents of ``rcS`` script are:: - By default, the contents of ``rcS`` script are::
# Create a RAMDISK and mount it at /tmp # Create a RAMDISK and mount it at /tmp
mkrd -m 1 -s 512 1024 mkrd -m 1 -s 512 1024
mkfatfs /dev/ram1 mkfatfs /dev/ram1
mount -t vfat /dev/ram1 /tmp mount -t vfat /dev/ram1 /tmp
- NSH will execute the script at ``/etc/init.d/rcS`` at start-up - NSH will execute the script at ``/etc/init.d/rcS`` at start-up
(before the first NSH prompt). After execution of the script, the (before the first NSH prompt). After execution of the script, the
root FS will look like:: root FS will look like::
|--dev/ |--dev/
| |-- ram0 | |-- ram0
| `-- ram1 | `-- ram1
|--etc/ |--etc/
| `--init.d/ | `--init.d/
| `-- rcS | `-- rcS
`--tmp/ `--tmp/
**Example Configurations**. Here are some configurations that have **Example Configurations**. Here are some configurations that have
``CONFIG_NSH_ROMFSETC=y`` in the NuttX configuration file. They might ``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 #. The simplest implementation simply uses fixed login credentials and
is selected with:: is selected with::
CONFIG_NSH_LOGIN_FIXED=y CONFIG_NSH_LOGIN_FIXED=y
The fixed login credentials are selected via:: The fixed login credentials are selected via::
CONFIG_NSH_LOGIN_USERNAME=admin 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 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 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 #. NSH can also be configured to defer the entire user credential
verification to platform-specific logic with this setting:: 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 In this case, NSH will call a platform-specific function to perform
the verification of user credentials. The platform-specific logic the verification of user credentials. The platform-specific logic
must provide a function with the following prototype: must provide a function with the following prototype:
.. code-block:: c .. code-block:: c
int platform_user_verify(FAR const char *username, FAR const char *password); int platform_user_verify(FAR const char *username, FAR const char *password);
which is prototyped an described in ``apps/include/nsh.h`` and which which is prototyped an described in ``apps/include/nsh.h`` and which
may be included like: may be included like:
.. code-block:: c .. code-block:: c
#include <apps/nsh.h> #include <apps/nsh.h>
An appropriate place to implement this function might be in the 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 #. A final option is to use a password file contained encrypted password
information. This final option is selected with the following and information. This final option is selected with the following and
described in more detail in the following paragraph:: described in more detail in the following paragraph::
CONFIG_NSH_LOGIN_PASSWD=y CONFIG_NSH_LOGIN_PASSWD=y
Password Files 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 #. The size of dynamically allocated and freed buffer that is used for
file access:: file access::
CONFIG_FSUTILS_PASSWD_IOBUFFER_SIZE=512 CONFIG_FSUTILS_PASSWD_IOBUFFER_SIZE=512
#. And the 128-bit encryption key. The password file currently uses the #. And the 128-bit encryption key. The password file currently uses the
Tiny Encryption Algorithm (TEA), but could be extended to use Tiny Encryption Algorithm (TEA), but could be extended to use
something more powerful. something more powerful.
CONFIG_FSUTILS_PASSWD_KEY1=0x12345678 CONFIG_FSUTILS_PASSWD_KEY1=0x12345678
CONFIG_FSUTILS_PASSWD_KEY2=0x9abcdef0 CONFIG_FSUTILS_PASSWD_KEY2=0x9abcdef0
CONFIG_FSUTILS_PASSWD_KEY3=0x12345678 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 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 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. changes to that configuration.
#. Disable logins: #. Disable logins:
.. code-block:: diff .. code-block:: diff
- CONFIG_NSH_CONSOLE_LOGIN=y - CONFIG_NSH_CONSOLE_LOGIN=y
+ # CONFIG_NSH_CONSOLE_LOGIN is not set + # 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: #. Move the password file to a write-able file system:
.. code-block:: diff .. code-block:: diff
- CONFIG_FSUTILS_PASSWD_PATH="/etc/passwd" - CONFIG_FSUTILS_PASSWD_PATH="/etc/passwd"
+ CONFIG_FSUTILS_PASSWD_PATH="/tmp/passwd" + CONFIG_FSUTILS_PASSWD_PATH="/tmp/passwd"
#. Make the password file modifiable #. Make the password file modifiable
.. code-block:: diff .. code-block:: diff
- CONFIG_FSUTILS_PASSWD_READONLY=y - CONFIG_FSUTILS_PASSWD_READONLY=y
# CONFIG_FSUTILS_PASSWD_READONLY is not set # CONFIG_FSUTILS_PASSWD_READONLY is not set
Now rebuild the simulation. No login should be required to enter the Now rebuild the simulation. No login should be required to enter the
shell and you should find the ```useradd`` <#cmduseradd>`__, shell and you should find the ```useradd`` <#cmduseradd>`__,
```userdel`` <#cmduserdel>`__, and ```passwd`` <#cmdpasswd>`__ commands ```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 #. The content on the ``nsh_romfsimg.h`` header file is generated from a
template directory structure. Create the directory structure:: template directory structure. Create the directory structure::
mkdir etc mkdir etc
mkdir etc/init.d mkdir etc/init.d
And copy your existing startup script into ``etc/init.c`` as ``rcS``. And copy your existing startup script into ``etc/init.c`` as ``rcS``.
#. Save your new password file in the ``etc/`` directory as ``passwd``. #. Save your new password file in the ``etc/`` directory as ``passwd``.
#. Create the new ROMFS image:: #. 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:: #. 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 #. Edit ``nsh_romfsimg.h``: Mark both data definitions as ``const`` so
that the data will be stored in FLASH. 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>`` Simple command ``<cmd>``
Command with re-directed output ``<cmd> > <file> <cmd> >> <file>`` Command with re-directed output ``<cmd> > <file> <cmd> >> <file>``
Background command ``<cmd> &`` Background command ``<cmd> &``
Re-directed background command ``<cmd> > <file> & <cmd> >> <file> &`` Re-directed background command ``<cmd> > <file> & <cmd> >> <file> &``
=============================== ====================================== =============================== ======================================
Where: Where:
* ``<cmd>`` is any one of the simple commands listed later. * ``<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 ``nice`` **'d Background Commands**. NSH executes at the
mid-priority (128). Backgrounded commands can be made to execute mid-priority (128). Backgrounded commands can be made to execute
at higher or lower priorities using ``nice``:: 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 Where ``<niceness>`` is any value between -20 and 19 where lower
(more negative values) correspond to higher priorities. The (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 commands can be used as arguments to other commands. The entity
to be executed is identified by enclosing the command line in to be executed is identified by enclosing the command line in
back quotes. For example, back quotes. For example,
.. code-block:: bash .. code-block:: bash
set FOO myprogram $BAR set FOO myprogram $BAR
Will execute the program named ``myprogram`` passing it the 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 - ``CONFIG_NSH_ARGCAT``: Support concatenation of strings
with environment variables or command output. For example: with environment variables or command output. For example:
.. code-block:: bash .. code-block:: bash
set FOO XYZ set FOO XYZ
set BAR 123 set BAR 123
set FOOBAR ABC_${FOO}_${BAR} set FOOBAR ABC_${FOO}_${BAR}
@ -191,20 +191,20 @@ the ```sh`` <#cmdsh>`__ command).
- ``while-do-done``: Execute ``[sequence of <cmd>]`` as long - ``while-do-done``: Execute ``[sequence of <cmd>]`` as long
as ``<cmd>`` has an exit status of zero. The syntax is as as ``<cmd>`` has an exit status of zero. The syntax is as
follows: follows:
.. code-block:: bash .. code-block:: bash
while <cmd> while <cmd>
do do
[sequence of <cmd>] [sequence of <cmd>]
done done
- ``until-do-done``: Execute ``[sequence of <cmd>]`` as long - ``until-do-done``: Execute ``[sequence of <cmd>]`` as long
as ``<cmd>`` has a non-zero exit status. The syntax is as as ``<cmd>`` has a non-zero exit status. The syntax is as
follows: follows:
.. code-block:: .. code-block::
until <cmd> until <cmd>
do do
[sequence of <cmd>] [sequence of <cmd>]
@ -228,7 +228,7 @@ Built-In Variables
====== ==================================================== ====== ====================================================
``$?`` The result of the last simple command execution. |br| ``$?`` The result of the last simple command execution. |br|
On backgrounded commands, this variable holds only |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 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 - NSH will create a read-only RAM disk (a ROM disk), containing a
tiny ROMFS file system containing the following:: tiny ROMFS file system containing the following::
`--init.d/ `--init.d/
`-- rcS `-- rcS
Where rcS is the NSH start-up script. Where rcS is the NSH start-up script.
- NSH will then mount the ROMFS file system at ``/etc``, - NSH will then mount the ROMFS file system at ``/etc``,
resulting in:: resulting in::
|--dev/ |--dev/
| `-- ram0 | `-- ram0
`--etc/ `--etc/
`--init.d/ `--init.d/
`-- rcS `-- rcS
- By default, the contents of rcS script are:: - By default, the contents of rcS script are::
# Create a RAMDISK and mount it at XXXRDMOUNTPOINTXXX # Create a RAMDISK and mount it at XXXRDMOUNTPOINTXXX
mkrd -m 1 -s 512 1024 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 - NSH will execute the script at ``/etc/init.d/rcS`` at start-up
(before the first NSH prompt). After execution of the script, (before the first NSH prompt). After execution of the script,
the root FS will look like:: the root FS will look like::
|--dev/ |--dev/
| |-- ram0 | |-- ram0
| `-- ram1 | `-- ram1
|--etc/ |--etc/
| `--init.d/ | `--init.d/
| `-- rcS | `-- rcS
`--tmp/ `--tmp/
**Modifying the ROMFS Image**. The contents of the ``/etc`` **Modifying the ROMFS Image**. The contents of the ``/etc``
directory are retained in the file ``apps/nshlib/nsh_romfsimg.h`` 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. of file system but will require copying of all NXFLAT executables to RAM.
- **GCC/ARM/Cortex-M3/4 Only**: - **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**: - **Read-Only Data in RAM**:
With older GCC compilers (at least up to 4.3.3), read-only data must 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**: - **Globally Scoped Function Function Pointers**:
If a function pointer is taken to a statically defined function, If a function pointer is taken to a statically defined function,
then (at least for ARM) GCC will generate a relocation that NXFLAT 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 scope. A fix would involve a change to the GCC compiler as described
in Appendix B. in Appendix B.
- **Special Handling of Callbacks**: - **Special Handling of Callbacks**:
Callbacks through function pointers must be avoided or, when Callbacks through function pointers must be avoided or, when
then cannot be avoided, handled very specially. The reason then cannot be avoided, handled very specially. The reason
@ -109,7 +109,7 @@ Limitations
will be unable to correctly access data memory. Special logic will be unable to correctly access data memory. Special logic
is in place to handle some NuttX callbacks: Signal callbacks is in place to handle some NuttX callbacks: Signal callbacks
and watchdog timer callbacks. But other callbacks (like those 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 Supported Processors
-------------------- --------------------
@ -217,7 +217,7 @@ files. In particular, the CSV files:
interface, and interface, and
#. ``nuttx/libc/libc.csv`` that describes the NuttX C library interface. #. ``nuttx/libc/libc.csv`` that describes the NuttX C library interface.
#. ``nuttx/libc/math.cvs`` that descirbes any math library. #. ``nuttx/libc/math.cvs`` that descirbes any math library.
:: ::
USAGE: ./mksymtab <cvs-file> <symtab-file> USAGE: ./mksymtab <cvs-file> <symtab-file>
@ -254,21 +254,21 @@ example).
* Target 2: * Target 2:
.. code-block:: makefile .. code-block:: makefile
hello-thunk.S: hello.r1 hello-thunk.S: hello.r1
mknxflat -o $@ $^ mknxflat -o $@ $^
* Target 3: * Target 3:
.. code-block:: makefile .. 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 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: * Target 4:
.. code-block:: makefile .. code-block:: makefile
hello: hello.r2 hello: hello.r2
ldnxflat -e main -s 2048 -o $@ $^ 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 linked against user applications. This user callable interfaces are
provided in sub-directories under ``nuttx/libnx``. provided in sub-directories under ``nuttx/libnx``.
``libnx/nx`` ``libnx/nx``
Common callable interfaces that are, logically, part of both nxmu and Common callable interfaces that are, logically, part of both nxmu and
nxsu. nxsu.
``graphics/nxglib`` and ``libnx/nxglib`` ``graphics/nxglib`` and ``libnx/nxglib``
The NuttX tiny graphics library. The directory contains generic The NuttX tiny graphics library. The directory contains generic
utilities support operations on primitive graphics objects and logic utilities support operations on primitive graphics objects and logic
to rasterize directly into a framebuffer or through an LCD driver to rasterize directly into a framebuffer or through an LCD driver
interface. It has no concept of windows (other than the one, interface. It has no concept of windows (other than the one,
framebuffer or LCD window). framebuffer or LCD window).
``graphics/nxbe`` ``graphics/nxbe``
This is the *back-end* of a tiny windowing system. It can be used 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 with either of two front-ends to complete a windowing system (see
``nxmu`` and ``nxsu`` below). It contains most of the important ``nxmu`` and ``nxsu`` below). It contains most of the important
window management logic: clipping, window controls, window drawing, window management logic: clipping, window controls, window drawing,
etc. etc.
``graphics/nxmu`` and ``libnx/nxmu`` ``graphics/nxmu`` and ``libnx/nxmu``
This is the NX multi user *front end*. When combined with the generic This is the NX multi user *front end*. When combined with the generic
*back-end* (``nxbe``), it implements a multi-threaded, multi-user *back-end* (``nxbe``), it implements a multi-threaded, multi-user
windowing system. The files in this directory present the window APIs 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 includes a graphics server that executes on its own thread; multiple
graphics clients then communicate with the server via a POSIX message graphics clients then communicate with the server via a POSIX message
queue to serialize window operations from many threads. queue to serialize window operations from many threads.
``libnx/nxfonts`` ``libnx/nxfonts``
This is where the NXFONTS implementation resides. This is a This is where the NXFONTS implementation resides. This is a
relatively low-level set of charset set/glyph management APIs. See relatively low-level set of charset set/glyph management APIs. See
``include/nuttx/nx/nxfonts.h``. ``include/nuttx/nx/nxfonts.h``.
``libnx/nxtk`` ``libnx/nxtk``
This is where the NXTOOLKIT implementation resides. This toolkit is 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 built on top of NX and works with the multi-user NX front-end. See
``include/nuttx/nx/nxtk.h``. ``include/nuttx/nx/nxtk.h``.
``apps/graphics/NxWidgets`` ``apps/graphics/NxWidgets``
The `NxWidgets <NxWidgets.html>`__ code is provided as a separate The `NxWidgets <NxWidgets.html>`__ code is provided as a separate
package provided in the ``apps/`` repository. 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 The NxTerm driver is built on top of NX and works with the multi-user
NX front-end. See ``include/nuttx/nx/nxterm.h``. NX front-end. See ``include/nuttx/nx/nxterm.h``.
@ -58,9 +58,9 @@ NX Configuration Options
General Configuration Settings General Configuration Settings
------------------------------ ------------------------------
``CONFIG_NX`` ``CONFIG_NX``
Enables overall support for graphics library and 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 Enables RAM backed window support. If this option is selected, then
windows may be optionally created with a RAM framebuffer backing up windows may be optionally created with a RAM framebuffer backing up
the window content. Rending into the window will result in rending the window content. Rending into the window will result in rending
@ -87,21 +87,21 @@ General Configuration Settings
NXGL Configuration Settings NXGL Configuration Settings
--------------------------- ---------------------------
``CONFIG_NX_NPLANES``: ``CONFIG_NX_NPLANES``:
Some YUV color formats requires support for multiple planes, one for Some YUV color formats requires support for multiple planes, one for
each color component. Unless you have such special hardware, this each color component. Unless you have such special hardware, this
value should be undefined or set to 1. 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 NX supports a variety of pixel depths. You can save some memory by
disabling support for unused color depths. 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 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 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 By default, NX builds to use a framebuffer driver (see
``include/nuttx/video/fb.h``). If this option is defined, NX will ``include/nuttx/video/fb.h``). If this option is defined, NX will
build to use an LCD driver (see ``include/nuttx/lcd/lcd.h``). 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 Enable support for anti-aliasing when rendering lines as various
orientations. This option is only available for use with frame buffer orientations. This option is only available for use with frame buffer
drivers and only with 16-, 24-, or 32-bit RGB color formats. drivers and only with 16-, 24-, or 32-bit RGB color formats.
@ -109,11 +109,11 @@ NXGL Configuration Settings
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. 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. Build in support of keypad/keyboard input.
``CONFIG_NX_WRITEONLY``: ``CONFIG_NX_WRITEONLY``:
Define if the underlying graphics device does not support read Define if the underlying graphics device does not support read
operations. Automatically defined if ``CONFIG_NX_LCDDRIVER`` and operations. Automatically defined if ``CONFIG_NX_LCDDRIVER`` and
``CONFIG_LCD_NOGETRUN`` are defined. ``CONFIG_LCD_NOGETRUN`` are defined.
@ -121,11 +121,11 @@ Configuration Settings
NX Server Configuration Settings NX Server Configuration Settings
-------------------------------- --------------------------------
``CONFIG_NX_BLOCKING`` ``CONFIG_NX_BLOCKING``
Open the client message queues in blocking mode. In this case, Open the client message queues in blocking mode. In this case,
``nx_eventhandler()`` will not return until a message is received and ``nx_eventhandler()`` will not return until a message is received and
processed. 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 Specifies the maximum number of messages that can fit in the message
queues. No additional resources are allocated, but this can be set to queues. No additional resources are allocated, but this can be set to
prevent flooding of the client or server with too many messages prevent flooding of the client or server with too many messages
@ -135,17 +135,17 @@ NX Server Configuration Settings
NXTK Configuration Settings NXTK Configuration Settings
--------------------------- ---------------------------
``CONFIG_NXTK_BORDERWIDTH``: ``CONFIG_NXTK_BORDERWIDTH``:
Specifies the width of the border (in pixels) used with framed Specifies the width of the border (in pixels) used with framed
windows. The default is 4. 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. 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. 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 The shiny side color and so is normally brighter. The default is
medium, dark, and light grey, respectively 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 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 over a visible portion of the window. Default: A mouse button must be
clicked over a visible portion of the window. clicked over a visible portion of the window.
@ -153,58 +153,58 @@ NXTK Configuration Settings
NXFONTS Configuration Settings NXFONTS Configuration Settings
------------------------------ ------------------------------
``CONFIG_NXFONTS_CHARBITS``: ``CONFIG_NXFONTS_CHARBITS``:
The number of bits in the character set. Current options are only 7 The number of bits in the character set. Current options are only 7
and 8. The default is 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 This option enables support for a tiny, 17x22 san serif font (font
``ID FONTID_SANS17X22`` == 14). ``ID FONTID_SANS17X22`` == 14).
``CONFIG_NXFONT_SANS20X26``: ``CONFIG_NXFONT_SANS20X26``:
This option enables support for a tiny, 20x26 san serif font (font This option enables support for a tiny, 20x26 san serif font (font
``ID FONTID_SANS20X26`` == 15). ``ID FONTID_SANS20X26`` == 15).
``CONFIG_NXFONT_SANS23X27``: ``CONFIG_NXFONT_SANS23X27``:
This option enables support for a tiny, 23x27 san serif font (font This option enables support for a tiny, 23x27 san serif font (font
``ID FONTID_SANS23X27`` == 1). ``ID FONTID_SANS23X27`` == 1).
``CONFIG_NXFONT_SANS22X29``: ``CONFIG_NXFONT_SANS22X29``:
This option enables support for a small, 22x29 san serif font (font This option enables support for a small, 22x29 san serif font (font
``ID FONTID_SANS22X29`` == 2). ``ID FONTID_SANS22X29`` == 2).
``CONFIG_NXFONT_SANS28X37``: ``CONFIG_NXFONT_SANS28X37``:
This option enables support for a medium, 28x37 san serif font (font This option enables support for a medium, 28x37 san serif font (font
``ID FONTID_SANS28X37`` == 3). ``ID FONTID_SANS28X37`` == 3).
``CONFIG_NXFONT_SANS39X48``: ``CONFIG_NXFONT_SANS39X48``:
This option enables support for a large, 39x48 san serif font (font This option enables support for a large, 39x48 san serif font (font
``ID FONTID_SANS39X48`` == 4). ``ID FONTID_SANS39X48`` == 4).
``CONFIG_NXFONT_SANS17X23B``: ``CONFIG_NXFONT_SANS17X23B``:
This option enables support for a tiny, 17x23 san serif bold font This option enables support for a tiny, 17x23 san serif bold font
(font ``ID FONTID_SANS17X23B`` == 16). (font ``ID FONTID_SANS17X23B`` == 16).
``CONFIG_NXFONT_SANS20X27B``: ``CONFIG_NXFONT_SANS20X27B``:
This option enables support for a tiny, 20x27 san serif bold font This option enables support for a tiny, 20x27 san serif bold font
(font ``ID FONTID_SANS20X27B`` == 17). (font ``ID FONTID_SANS20X27B`` == 17).
``CONFIG_NXFONT_SANS22X29B``: ``CONFIG_NXFONT_SANS22X29B``:
This option enables support for a small, 22x29 san serif bold font This option enables support for a small, 22x29 san serif bold font
(font ID ``FONTID_SANS22X29B`` == 5). (font ID ``FONTID_SANS22X29B`` == 5).
``CONFIG_NXFONT_SANS28X37B``: ``CONFIG_NXFONT_SANS28X37B``:
This option enables support for a medium, 28x37 san serif bold font This option enables support for a medium, 28x37 san serif bold font
(font ID ``FONTID_SANS28X37B`` == 6). (font ID ``FONTID_SANS28X37B`` == 6).
``CONFIG_NXFONT_SANS40X49B``: ``CONFIG_NXFONT_SANS40X49B``:
This option enables support for a large, 40x49 san serif bold font This option enables support for a large, 40x49 san serif bold font
(font ID ``FONTID_SANS40X49B`` == 7). (font ID ``FONTID_SANS40X49B`` == 7).
``CONFIG_NXFONT_SERIF22X29``: ``CONFIG_NXFONT_SERIF22X29``:
This option enables support for a small, 22x29 font (with serifs) This option enables support for a small, 22x29 font (with serifs)
(font ID ``FONTID_SERIF22X29`` == 8). (font ID ``FONTID_SERIF22X29`` == 8).
``CONFIG_NXFONT_SERIF29X37``: ``CONFIG_NXFONT_SERIF29X37``:
This option enables support for a medium, 29x37 font (with serifs) This option enables support for a medium, 29x37 font (with serifs)
(font ID ``FONTID_SERIF29X37`` == 9). (font ID ``FONTID_SERIF29X37`` == 9).
``CONFIG_NXFONT_SERIF38X48``: ``CONFIG_NXFONT_SERIF38X48``:
This option enables support for a large, 38x48 font (with serifs) This option enables support for a large, 38x48 font (with serifs)
(font ID ``FONTID_SERIF38X48`` == 10). (font ID ``FONTID_SERIF38X48`` == 10).
``CONFIG_NXFONT_SERIF22X28B``: ``CONFIG_NXFONT_SERIF22X28B``:
This option enables support for a small, 27x38 bold font (with This option enables support for a small, 27x38 bold font (with
serifs) (font ID ``FONTID_SERIF22X28B`` == 11). serifs) (font ID ``FONTID_SERIF22X28B`` == 11).
``CONFIG_NXFONT_SERIF27X38B``: ``CONFIG_NXFONT_SERIF27X38B``:
This option enables support for a medium, 27x38 bold font (with This option enables support for a medium, 27x38 bold font (with
serifs) (font ID ``FONTID_SERIF27X38B`` == 12). serifs) (font ID ``FONTID_SERIF27X38B`` == 12).
``CONFIG_NXFONT_SERIF38X49B``: ``CONFIG_NXFONT_SERIF38X49B``:
This option enables support for a large, 38x49 bold font (with This option enables support for a large, 38x49 bold font (with
serifs) (font ID ``FONTID_SERIF38X49B`` == 13). serifs) (font ID ``FONTID_SERIF38X49B`` == 13).
@ -213,24 +213,24 @@ NxTerm Configuration Settings
General NxTerm settings. General NxTerm settings.
``CONFIG_NXTERM``: ``CONFIG_NXTERM``:
Enables building of the NxTerm driver. Enables building of the NxTerm driver.
NxTerm output text/graphics options: NxTerm output text/graphics options:
``CONFIG_NXTERM_BPP``: ``CONFIG_NXTERM_BPP``:
Currently, NxTerm supports only a single pixel depth. This Currently, NxTerm supports only a single pixel depth. This
configuration setting must be provided to support that single pixel configuration setting must be provided to support that single pixel
depth. Default: The smallest enabled pixel depth. (see depth. Default: The smallest enabled pixel depth. (see
``CONFIG_NX_DISABLE_*BPP``) ``CONFIG_NX_DISABLE_*BPP``)
``CONFIG_NXTERM_CURSORCHAR``: ``CONFIG_NXTERM_CURSORCHAR``:
The bitmap code to use as the cursor. Default '_' 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 NxTerm needs to remember every character written to the console so
that it can redraw the window. This setting determines the size of that it can redraw the window. This setting determines the size of
some internal memory allocations used to hold the character data. some internal memory allocations used to hold the character data.
Default: 128. Default: 128.
``CONFIG_NXTERM_CACHESIZE``: ``CONFIG_NXTERM_CACHESIZE``:
NxTerm supports caching of rendered fonts. This font caching is NxTerm supports caching of rendered fonts. This font caching is
required for two reasons: (1) First, it improves text performance, required for two reasons: (1) First, it improves text performance,
but more importantly (2) it preserves the font memory. Since the NX 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 server task. ``CONFIG_NXTERM_CACHESIZE`` should be larger than
``CONFIG_MQ_MAXMSGSIZE`` in any event. ``CONFIG_MQ_MAXMSGSIZE`` in any event.
``CONFIG_NXTERM_LINESEPARATION``: ``CONFIG_NXTERM_LINESEPARATION``:
This the space (in rows) between each row of test. Default: 0 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 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 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. so that the text is simply truncated until a new line is encountered.
NxTerm input options: NxTerm input options:
``CONFIG_NXTERM_NXKBDIN``: ``CONFIG_NXTERM_NXKBDIN``:
Take input from the NX keyboard input callback. By default, keyboard Take input from the NX keyboard input callback. By default, keyboard
input is taken from stdin (``/dev/console``). If this option is set, input is taken from stdin (``/dev/console``). If this option is set,
then the interface\ ``nxterm_kdbin()`` is enabled. That interface may then the interface\ ``nxterm_kdbin()`` is enabled. That interface may
be driven by window callback functions so that keyboard input *only* be driven by window callback functions so that keyboard input *only*
goes to the top window. goes to the top window.
``CONFIG_NXTERM_KBDBUFSIZE``: ``CONFIG_NXTERM_KBDBUFSIZE``:
If ``CONFIG_NXTERM_NXKBDIN`` is enabled, then this value may be used If ``CONFIG_NXTERM_NXKBDIN`` is enabled, then this value may be used
to define the size of the per-window keyboard input buffer. Default: to define the size of the per-window keyboard input buffer. Default:
16 16
``CONFIG_NXTERM_NPOLLWAITERS``: ``CONFIG_NXTERM_NPOLLWAITERS``:
The number of threads that can be waiting for read data available. The number of threads that can be waiting for read data available.
Default: 4 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 4. ``include/nuttx/nx/nxfonts.h``. Add you new font as a possible
system default font: system default font:
.. code-block:: c .. code-block:: c
#if defined(CONFIG_NXFONT_SANS23X27) #if defined(CONFIG_NXFONT_SANS23X27)
# define NXFONT_DEFAULT FONTID_SANS23X27 # define NXFONT_DEFAULT FONTID_SANS23X27
#elif defined(CONFIG_NXFONT_MYFONT) #elif defined(CONFIG_NXFONT_MYFONT)
# define NXFONT_DEFAULT FONTID_MYFONT # define NXFONT_DEFAULT FONTID_MYFONT
#endif #endif
Then define the actual font ID. Make sure that the font ID value is Then define the actual font ID. Make sure that the font ID value is
unique: unique:
.. code-block:: c .. code-block:: c
#if defined(CONFIG_NXFONT_SANS23X27) #if defined(CONFIG_NXFONT_SANS23X27)
# define NXFONT_DEFAULT FONTID_SANS23X27 # define NXFONT_DEFAULT FONTID_SANS23X27
#elif defined(CONFIG_NXFONT_MYFONT) #elif defined(CONFIG_NXFONT_MYFONT)
# define NXFONT_DEFAULT FONTID_MYFONT # define NXFONT_DEFAULT FONTID_MYFONT
#endif #endif
New Add the font to the NX build system. There are several files that 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 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 with the *bdf-converter* program. Notice ``NXFONTS_FONTID=2``; this
must be set to the same font ID value that you defined in the must be set to the same font ID value that you defined in the
``include/nuttx/nx/nxfonts.h`` file. ``include/nuttx/nx/nxfonts.h`` file.
.. code-block:: makefile .. code-block:: makefile
genfontsources: genfontsources:
ifeq ($(CONFIG_NXFONT_SANS23X27),y) ifeq ($(CONFIG_NXFONT_SANS23X27),y)
@$(MAKE) -C nxfonts -f Makefile.sources NXFONTS_FONTID=1 EXTRAFLAGS=$(EXTRAFLAGS) @$(MAKE) -C nxfonts -f Makefile.sources NXFONTS_FONTID=1 EXTRAFLAGS=$(EXTRAFLAGS)
endif endif
ifeq ($(CONFIG_NXFONT_MYFONT),y) ifeq ($(CONFIG_NXFONT_MYFONT),y)
@$(MAKE) -C nxfonts -f Makefile.sources NXFONTS_FONTID=2 EXTRAFLAGS=$(EXTRAFLAGS) @$(MAKE) -C nxfonts -f Makefile.sources NXFONTS_FONTID=2 EXTRAFLAGS=$(EXTRAFLAGS)
endif endif
6. ``nuttx/graphics/nxfonts/Make.defs``. Set the make variable 6. ``nuttx/graphics/nxfonts/Make.defs``. Set the make variable
``NXFSET_CSRCS``. ``NXFSET_CSRCS`` determines the name of the font C ``NXFSET_CSRCS``. ``NXFSET_CSRCS`` determines the name of the font C
file to build when ``NXFONTS_FONTID=2``: file to build when ``NXFONTS_FONTID=2``:
.. code-block:: makefile .. code-block:: makefile
ifeq ($(CONFIG_NXFONT_SANS23X27),y) ifeq ($(CONFIG_NXFONT_SANS23X27),y)
NXFSET_CSRCS += nxfonts_bitmaps_sans23x27.c NXFSET_CSRCS += nxfonts_bitmaps_sans23x27.c
endif endif
ifeq ($(CONFIG_NXFONT_MYFONT),y) ifeq ($(CONFIG_NXFONT_MYFONT),y)
NXFSET_CSRCS += nxfonts_bitmaps_myfont.c NXFSET_CSRCS += nxfonts_bitmaps_myfont.c
endif endif
7. ``nuttx/graphics/nxfonts/Makefile.sources``. This is the Makefile 7. ``nuttx/graphics/nxfonts/Makefile.sources``. This is the Makefile
used in step 5 that will actually generate the font C file. So, given 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 auto-generated variable and function names and (again) the name of
the autogenerated file to create (this must be the same name that was the autogenerated file to create (this must be the same name that was
used in ``nuttx/graphics/nxfonts/Make.defs``): used in ``nuttx/graphics/nxfonts/Make.defs``):
.. code-block:: makefile .. code-block:: makefile
ifeq ($(NXFONTS_FONTID),1) ifeq ($(NXFONTS_FONTID),1)
NXFONTS_PREFIX := g_sans23x27_ NXFONTS_PREFIX := g_sans23x27_
GEN_CSRC = nxfonts_bitmaps_sans23x27.c GEN_CSRC = nxfonts_bitmaps_sans23x27.c
@ -393,21 +393,21 @@ CONFIG_NXFONT_SANS23X27 for examaples:
NXFONTS_PREFIX := g_myfont_ NXFONTS_PREFIX := g_myfont_
GEN_CSRC = nxfonts_bitmaps_myfont.c GEN_CSRC = nxfonts_bitmaps_myfont.c
endif endif
8. ``graphics/nxfonts/nxfonts_bitmaps.c``. This is the file that 8. ``graphics/nxfonts/nxfonts_bitmaps.c``. This is the file that
contains the generic font structures. It is used as a "template&qout; contains the generic font structures. It is used as a "template&qout;
file by ``nuttx/graphics/nxfonts/Makefile.sources``\ to create your file by ``nuttx/graphics/nxfonts/Makefile.sources``\ to create your
customized font data set at build time. customized font data set at build time.
.. code-block:: c .. code-block:: c
#if NXFONTS_FONTID == 1 #if NXFONTS_FONTID == 1
# include "nxfonts_sans23x27.h" # include "nxfonts_sans23x27.h"
#elif NXFONTS_FONTID == 2 #elif NXFONTS_FONTID == 2
# include "nxfonts_myfont.h" # include "nxfonts_myfont.h"
#else #else
# error "No font ID specified" # error "No font ID specified"
#endif #endif
Where ``nxfonts_myfont.h`` is the NuttX font file that we generated Where ``nxfonts_myfont.h`` is the NuttX font file that we generated
in step 2 using the *bdf-converter* tool. 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 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 4. The new font information needs to be added to data structures used
by that function: by that function:
.. code-block:: c .. code-block:: c
#ifdef CONFIG_NXFONT_SANS23X27 #ifdef CONFIG_NXFONT_SANS23X27
extern const struct nx_fontpackage_s g_sans23x27_package; extern const struct nx_fontpackage_s g_sans23x27_package;
#endif #endif
@ -439,7 +439,7 @@ CONFIG_NXFONT_SANS23X27 for examaples:
#endif #endif
NULL NULL
}; };
NX Test Coverage NX Test Coverage
================ ================
@ -460,10 +460,10 @@ configurations for building the simulation:
feedback. In this configuration, a very simple, simulated framebuffer feedback. In this configuration, a very simple, simulated framebuffer
driver is used that is based upon a simple region of memory posing as driver is used that is based upon a simple region of memory posing as
video memory. That default configuration can be built as follows:: video memory. That default configuration can be built as follows::
tools/configure.sh sim:nx tools/configure.sh sim:nx
make make
./nuttx ./nuttx
#. The preferred configuration is at #. The preferred configuration is at
``boards/sim/sim/sim/configs/nx11/defconfig``. This configuration ``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 window as a framebuffer. This is a superior test configuration
because the X window appears at your desktop and you can see the NX because the X window appears at your desktop and you can see the NX
output. This preferred configuration can be built as follows:: output. This preferred configuration can be built as follows::
tools/configure sim:nx11 tools/configure sim:nx11
make make
./nuttx ./nuttx
*Update:* The sim target has suffered some bit-rot over the years and *Update:* The sim target has suffered some bit-rot over the years and
so the following caveats need to be added: so the following caveats need to be added:
@ -537,7 +537,7 @@ Function Special Setup/Notes Verified
There is a "fudge factor" that seems There is a "fudge factor" that seems
to eliminate the problem, but there to eliminate the problem, but there
could still be issues in some could still be issues in some
configurations. configurations.
``nxgl_circlepts`` Verified by apps/examples/nxlines. YES ``nxgl_circlepts`` Verified by apps/examples/nxlines. YES
``nxgl_circletraps`` 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 ``nx_openwindow()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES
``<NuttX-Directory>/.config file`` ``<NuttX-Directory>/.config file``
``nx_closewindow()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` YES ``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 ``nx_requestbkgd()`` Verified by ``apps/examples/nxtext`` and YES
``apps/examples/nxhello``. ``apps/examples/nxhello``.
``nx_releasebkgd()`` Verified by ``apps/examples/nxtext`` and YES ``nx_releasebkgd()`` Verified by ``apps/examples/nxtext`` and YES
``apps/examples/nxhello``. ``apps/examples/nxhello``.
``nx_getposition()`` . NO ``nx_getposition()`` . NO
``nx_setposition()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES ``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 ``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 ``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 ``nx_lower()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES
``<NuttX-Directory>/.config`` file ``<NuttX-Directory>/.config`` file
``nx_modal()`` . NO ``nx_modal()`` . NO
``nx_setvisibility()`` Exercized using Twm4Nx YES, Informally ``nx_setvisibility()`` Exercized using Twm4Nx YES, Informally
``nx_ishidden()`` Exercized using Twm4Nx YES, Informally ``nx_ishidden()`` Exercized using Twm4Nx YES, Informally
``nx_fill()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES ``nx_fill()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES
``<NuttX-Directory>/.config`` file ``<NuttX-Directory>/.config`` file
``nx_getrectangle()`` . YES ``nx_getrectangle()`` . YES
``nx_filltrapezoid()`` Verified by ``apps/examples/nxlines``. YES ``nx_filltrapezoid()`` Verified by ``apps/examples/nxlines``. YES
``nx_drawline()`` 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_fillcircle()`` Verified by ``apps/examples/nxlines``. YES
``nx_setbgcolor()`` . YES ``nx_setbgcolor()`` . YES
``nx_move()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the 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 ``nx_bitmap()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES
``<NuttX-Directory>/.config`` file. ``<NuttX-Directory>/.config`` file.
``nx_kbdin()`` . YES ``nx_kbdin()`` . YES
``nx_mousein()`` . YES ``nx_mousein()`` . YES
========================= =============================================================== ======== ========================= =============================================================== ========
@ -640,7 +640,7 @@ Function Special Setup/Notes Verified
NXFONTS API Test Coverage NXFONTS API Test Coverage
------------------------- -------------------------
======================== ============================= ======== ======================== ============================= ========
Function Special Setup/Notes Verified 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 .. figure:: NuttXScreenShot.jpg
:align: center :align: center
**Figure 1**. This screnshot shows the final frame for the NuttX example **Figure 1**. This screnshot shows the final frame for the NuttX example
at ``apps/examples/nx`` running on the simulated, Linux x86 platform with 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 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 NX Header Files
=============== ===============
``include/nuttx/nx/nxglib.h`` ``include/nuttx/nx/nxglib.h``
Describes the NXGLIB C interfaces Describes the NXGLIB C interfaces
``include/nuttx/nx/nx.h`` ``include/nuttx/nx/nx.h``
Describes the NX C interfaces Describes the NX C interfaces
``include/nutt/nxtk.h`` ``include/nutt/nxtk.h``
Describe the NXTOOLKIT C interfaces Describe the NXTOOLKIT C interfaces
``include/nutt/nxfont.h`` ``include/nutt/nxfont.h``
Describe sthe NXFONT C interfaces Describe sthe NXFONT C interfaces
.. toctree:: .. toctree::
:Caption: User APIs :Caption: User APIs
nxgl.rst nxgl.rst
nx.rst nx.rst
nxtk.rst nxtk.rst
@ -171,4 +171,4 @@ NX Header Files
nxcursor.rst nxcursor.rst
sample.rst sample.rst
appendix.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 .. c:struct:: nx_callback_s
.. code-block:: c .. code-block:: c
struct nx_callback_s struct nx_callback_s
{ {
void (*redraw)(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect, 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, ``CONFIG_BOARD_LATE_INITIALIZE`` is defined in the configuration. Or,
the board startup logic can execute under control of the application the board startup logic can execute under control of the application
by calling :c:func:`boardctl` as: by calling :c:func:`boardctl` as:
.. code-block:: c .. code-block:: c
boardctl(BOARDIOC_INIT, arg) boardctl(BOARDIOC_INIT, arg)
The board initialization logic will run in either case and the simple 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. waiting to accept connections from NX clients.
A negated ``errno`` value is returned on failure. The ``errno`` value A negated ``errno`` value is returned on failure. The ``errno`` value
indicates the nature of the failure. indicates the nature of the failure.
NX Server Callbacks NX Server Callbacks
=================== ===================
@ -107,12 +107,12 @@ NX Server Callbacks
NX requests that the client re-draw the portion of the NX requests that the client re-draw the portion of the
window within with rectangle. window within with rectangle.
:param hwnd: :param hwnd:
The handle created by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd` The handle created by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd`
:param rect: :param rect:
The rectangle that needs to be re-drawn (in window relative The rectangle that needs to be re-drawn (in window relative
coordinates) coordinates)
:param more: :param more:
true: More re-draw requests will follow true: More re-draw requests will follow
:param arg: :param arg:
User provided argument (see :c:func:`nx_openwindow`) 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 The size or position of the window has changed (or the
window was just created with zero size. window was just created with zero size.
:param hwnd: :param hwnd:
The handle created by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd` The handle created by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd`
:param size: :param size:
The size of the window The size of the window
@ -155,11 +155,11 @@ NX Server Callbacks
New keyboard/keypad data is available for the window. 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` 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[] The number of characters that are available in ch[]
:param ch: :param ch:
The array of characters The array of characters
:param arg: :param arg:
User provided argument (see :c:func:`nx_openwindow`) 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. 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`, This callback is the response from :c:func:`nx_block`,
:c:func:`nxtk_block`. Those blocking interfaces are used :c:func:`nxtk_block`. Those blocking interfaces are used
to assure that no further messages are directed to the window. 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. callbacks are processed. Then the window may be safely closed.
Closing the window prior with pending callbacks can lead to bad Closing the window prior with pending callbacks can lead to bad
behavior when the callback is executed. behavior when the callback is executed.
- ``NXEVENT_SYNCHED``: Synchronization handshake - ``NXEVENT_SYNCHED``: Synchronization handshake
This completes the handshake started by This completes the handshake started by
:c:func:`nx_synch`, or :c:func:`nxtk_synch`. :c:func:`nx_synch`, or :c:func:`nxtk_synch`.
Those interfaces send a synchronization messages to the NX server 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 synchronization is sometimes necessary to assure that the client and
server are working together properly. server are working together properly.
:param hwnd: :param hwnd:
TWindow handle of window receiving the event TWindow handle of window receiving the event
:param event: :param event:
The server event The server event
:param arg1: :param arg1:
User provided argument (see :c:func:`nx_openwindow`, User provided argument (see :c:func:`nx_openwindow`,
:c:func:`nx_requestbkgd`, or :c:func:`nxtk_opentoolbar`) :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`, TUser provided argument (see :c:func:`nx_block`, :c:func:`nxtk_block`,
:c:func:`nx_synch`, or :c:func:`nxtk_synch`) :c:func:`nx_synch`, or :c:func:`nxtk_synch`)
.. c:macro:: nx_run(fb) .. c:macro:: nx_run(fb)
.. code-block:: c .. code-block:: c
#define nx_run(fb) nx_runinstance(NX_DEFAULT_SERVER_MQNAME, dev) #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) .. 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 This is the server entry point. It does not return; the
@ -227,9 +227,9 @@ NX Server Callbacks
.. c:macro:: nx_connect(cb) .. c:macro:: nx_connect(cb)
.. code-block:: c .. code-block:: c
#define nx_connect(cb) nx_connectinstance(NX_DEFAULT_SERVER_MQNAME) #define nx_connect(cb) nx_connectinstance(NX_DEFAULT_SERVER_MQNAME)
.. c:function:: NXHANDLE nx_connectinstance(FAR const char *svrmqname); .. c:function:: NXHANDLE nx_connectinstance(FAR const char *svrmqname);
Open a connection from a client to the NX server. One 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 :param svrmqname: The name for the server incoming message queue
:return: Success: A non-NULL handle used with subsequent NX accesses :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) .. c:function:: void nx_disconnect(NXHANDLE handle)
Disconnect a client from the NX server and/or free 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 prior with pending callbacks can lead to bad behavior when the callback
is executed. 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 :param arg: An argument that will accompany the block messages (This is ``arg2`` in
the event callback). the event callback).
@ -341,7 +341,7 @@ NX Server Callbacks
server are fully synchronized in time. server are fully synchronized in time.
Usage by the window client might be something like this: Usage by the window client might be something like this:
.. code-block:: c .. code-block:: c
extern bool g_synched; extern bool g_synched;
@ -376,7 +376,7 @@ NX Server Callbacks
.. c:function:: NXWINDOW nx_openwindow(NXHANDLE handle, uint8_t flags, \ .. c:function:: NXWINDOW nx_openwindow(NXHANDLE handle, uint8_t flags, \
FAR const struct nx_callback_s *cb, \ FAR const struct nx_callback_s *cb, \
FAR void *arg); FAR void *arg);
Create a new window. Create a new window.
:param handle: The handle returned by ```nx_connect()`` <#nxconnectinstance>`__. :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. :param arg: User provided value that will be returned with NX callbacks.
:return: Success: A non-NULL handle used with subsequent NX accesses :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) .. 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, \ .. c:function:: int nx_fill(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect, \
nxgl_mxpixel_t color[CONFIG_NX_NPLANES]); nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
Fill the specified rectangle in the window with the Fill the specified rectangle in the window with the
specified color. specified color.
@ -608,7 +608,7 @@ NX Server Callbacks
:param color: The color to use to fill the line :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 :param caps: Draw a circular cap on the ends of the line to support better line
joins. One of:: joins. One of::
/* Line caps */ /* Line caps */
#define NX_LINECAP_NONE 0x00, /* No 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 The image is provided a a 2-bits-per-pixel image. The two bit incoding
is as following: is as following:
- 00: The transparent background. - 00: The transparent background.
- 01: Color1: The main color of the cursor. - 01: Color1: The main color of the cursor.
- 10: Color2: The color of any border. - 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 This structure describes one contiguous grouping of glyphs that can be
described by an array starting with encoding ``first`` and extending described by an array starting with encoding ``first`` and extending
@ -84,7 +84,7 @@ NXFONTS types
Return font bitmap information for the selected Return font bitmap information for the selected
character encoding. 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`. :param handle: A font handle previously returned by :c:func:`nxf_getfonthandle`.
:return: An instance of :c:struct:`nx_fontbitmap_s` describing the glyph. :return: An instance of :c:struct:`nx_fontbitmap_s` describing the glyph.
@ -92,7 +92,7 @@ NXFONTS types
uint16_t width, uint16_t stride, \ uint16_t width, uint16_t stride, \
FAR const struct nx_fontbitmap_s *bm, \ FAR const struct nx_fontbitmap_s *bm, \
nxgl_mxpixel_t color); nxgl_mxpixel_t color);
.. c:function:: int nxf_convert_4bpp(FAR uint8_t *dest, uint16_t height, \ .. c:function:: int nxf_convert_4bpp(FAR uint8_t *dest, uint16_t height, \
uint16_t width, uint16_t stride, \ uint16_t width, uint16_t stride, \
FAR const struct nx_fontbitmap_s *bm, \ FAR const struct nx_fontbitmap_s *bm, \
@ -113,7 +113,7 @@ NXFONTS types
uint16_t width, uint16_t stride, \ uint16_t width, uint16_t stride, \
FAR const struct nx_fontbitmap_s *bm, \ FAR const struct nx_fontbitmap_s *bm, \
nxgl_mxpixel_t color); nxgl_mxpixel_t color);
Convert the 1BPP font to a new pixel depth. Convert the 1BPP font to a new pixel depth.
:param dest: The destination buffer provided by the caller. :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``. if 24, and 32 resolution support is disabled, or ``uint32_t``.
.. c:type:: nxgl_coord_t .. c:type:: nxgl_coord_t
A given coordinate is limited to the screen height an A given coordinate is limited to the screen height an
width. If either of those values exceed 32,767 pixels, then the width. If either of those values exceed 32,767 pixels, then the
following will have to need to change: following will have to need to change:
.. c:struct:: nxgl_point_s .. c:struct:: nxgl_point_s
Describes a point on the display: Describes a point on the display:
.. code-block:: c .. code-block:: c
struct nxgl_point_s struct nxgl_point_s
{ {
nxgl_coord_t x; /* X position, range: 0 to screen width - 1 */ nxgl_coord_t x; /* X position, range: 0 to screen width - 1 */
@ -39,28 +39,28 @@ NXGL Types
}; };
.. c:struct:: nxgl_size_s .. c:struct:: nxgl_size_s
Describes the size of a rectangular region. Describes the size of a rectangular region.
.. code-block:: c .. code-block:: c
struct nxgl_size_s struct nxgl_size_s
{ {
nxgl_coord_t w; /* Width in pixels */ nxgl_coord_t w; /* Width in pixels */
nxgl_coord_t h; /* Height in rows */ nxgl_coord_t h; /* Height in rows */
}; };
.. c:struct:: nxgl_rect_s .. c:struct:: nxgl_rect_s
Describes a positioned rectangle on the display. Describes a positioned rectangle on the display.
.. code-block:: c .. code-block:: c
struct nxgl_rect_s struct nxgl_rect_s
{ {
struct nxgl_point_s pt1; /* Upper, left-hand corner */ struct nxgl_point_s pt1; /* Upper, left-hand corner */
struct nxgl_point_s pt2; /* Lower, right-hand corner */ struct nxgl_point_s pt2; /* Lower, right-hand corner */
}; };
.. c:struct:: nxgl_run_s .. c:struct:: nxgl_run_s
@ -68,30 +68,30 @@ NXGL Types
that the start/end positions have fractional precision. This is that the start/end positions have fractional precision. This is
necessary for good joining of trapezoids when a more complex shape is necessary for good joining of trapezoids when a more complex shape is
decomposed into trapezoids. decomposed into trapezoids.
.. code-block:: c .. code-block:: c
struct nxgl_run_s struct nxgl_run_s
{ {
b16_t x1; /* Left X position, range: 0 to x2 */ b16_t x1; /* Left X position, range: 0 to x2 */
b16_t x2; /* Right X position, range: x1 to screen width - 1 */ 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 */ nxgl_coord_t y; /* Top Y position, range: 0 to screen height - 1 */
}; };
.. c:struct:: nxgl_trapezoid_s .. c:struct:: nxgl_trapezoid_s
Describes a horizontal trapezoid on the Describes a horizontal trapezoid on the
display in terms the run at the top of the trapezoid and the run at the display in terms the run at the top of the trapezoid and the run at the
bottom. bottom.
.. code-block:: c .. code-block:: c
struct nxgl_trapezoid_s struct nxgl_trapezoid_s
{ {
struct nxgl_run_s top; /* Top run */ struct nxgl_run_s top; /* Top run */
struct nxgl_run_s bot; /* bottom 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) .. 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. 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], \ .. 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 *rect1, \
FAR const struct nxgl_rect_s *rect2); FAR const struct nxgl_rect_s *rect2);
Return the regions of rectangle ``rect1`` that do not Return the regions of rectangle ``rect1`` that do not
intersect with ``rect2``. This will four rectangles, some of which may intersect with ``rect2``. This will four rectangles, some of which may
be degenerate (and can be picked off with :c:func:`nxgl_nullrect`). be degenerate (and can be picked off with :c:func:`nxgl_nullrect`).
.. c:function:: bool nxgl_rectoverlap(FAR struct nxgl_rect_s *rect1, \ .. c:function:: bool nxgl_rectoverlap(FAR struct nxgl_rect_s *rect1, \
FAR struct nxgl_rect_s *rect2); FAR struct nxgl_rect_s *rect2);
Return true if the two rectangles overlap. Return true if the two rectangles overlap.
.. c:function:: bool nxgl_rectinside(FAR const struct nxgl_rect_s *rect, \ .. c:function:: bool nxgl_rectinside(FAR const struct nxgl_rect_s *rect, \
FAR const struct nxgl_point_s *pt); FAR const struct nxgl_point_s *pt);
Return true if the point ``pt`` lies within ``rect``. Return true if the point ``pt`` lies within ``rect``.
.. c:function:: void nxgl_rectsize(FAR struct nxgl_size_s *size, \ .. c:function:: void nxgl_rectsize(FAR struct nxgl_size_s *size, \
FAR const struct nxgl_rect_s *rect); FAR const struct nxgl_rect_s *rect);
Return the size of the specified rectangle. Return the size of the specified rectangle.
.. c:function:: bool nxgl_nullrect(FAR const struct nxgl_rect_s *rect); .. 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, \ .. c:function:: void nxgl_runoffset(FAR struct nxgl_run_s *dest, \
FAR const struct nxgl_run_s *src, \ FAR const struct nxgl_run_s *src, \
nxgl_coord_t dx, nxgl_coord_t dy); nxgl_coord_t dx, nxgl_coord_t dy);
Offset the run position by the specified ``dx``, ``dy`` Offset the run position by the specified ``dx``, ``dy``
values. values.
.. c:function:: void nxgl_runcopy(FAR struct nxgl_run_s *dest, \ .. c:function:: void nxgl_runcopy(FAR struct nxgl_run_s *dest, \
FAR const struct nxgl_run_s *src); FAR const struct nxgl_run_s *src);
This is essentially ``memcpy()``\ for runs. We don't do This is essentially ``memcpy()``\ for runs. We don't do
structure assignments because some compilers are not good at that. structure assignments because some compilers are not good at that.
.. c:function:: void nxgl_trapoffset(FAR struct nxgl_trapezoid_s *dest, \ .. c:function:: void nxgl_trapoffset(FAR struct nxgl_trapezoid_s *dest, \
FAR const struct nxgl_trapezoid_s *src, \ FAR const struct nxgl_trapezoid_s *src, \
nxgl_coord_t dx, nxgl_coord_t dy); nxgl_coord_t dx, nxgl_coord_t dy);
Offset the trapezoid position by the specified ``dx``, Offset the trapezoid position by the specified ``dx``,
``dy`` values. ``dy`` values.
.. c:function:: void nxgl_trapcopy(FAR struct nxgl_trapezoid_s *dest, \ .. c:function:: void nxgl_trapcopy(FAR struct nxgl_trapezoid_s *dest, \
FAR const struct nxgl_trapezoid_s *src); FAR const struct nxgl_trapezoid_s *src);
This is essentially ``memcpy()``\ for trapezoids. We This is essentially ``memcpy()``\ for trapezoids. We
don't do structure assignments because some compilers are not good at don't do structure assignments because some compilers are not good at
that. that.
.. c:function:: void nxgl_colorcopy(nxgl_mxpixel_t dest[CONFIG_NX_NPLANES], \ .. c:function:: void nxgl_colorcopy(nxgl_mxpixel_t dest[CONFIG_NX_NPLANES], \
const nxgl_mxpixel_t src[CONFIG_NX_NPLANES]); const nxgl_mxpixel_t src[CONFIG_NX_NPLANES]);
This is essentially ``memcpy()``\ for colors. This does This is essentially ``memcpy()``\ for colors. This does
very little for us other than hide all of the conditional compilation very little for us other than hide all of the conditional compilation
for planar colors in one place. 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. - 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. - 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 - 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, \ .. c:function:: void nxgl_circlepts(FAR const struct nxgl_point_s *center, nxgl_coord_t radius, \
FAR struct nxgl_point_s *circle); 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 coordinate system for each sub-window begins at the top left
corner of the subwindow. This means that toolbar logic need not corner of the subwindow. This means that toolbar logic need not
be concerned about client window geometry (and vice versa) and, 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 .. c:type:: FAR void *NXTKWINDOW
This is the handle that can be used to access the window data region. This is the handle that can be used to access the window data region.
.. c:function:: int nxtk_block(NXWINDOW hwnd, FAR void *arg) .. 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. server are fully synchronized in time.
Usage by the window client might be something like this: Usage by the window client might be something like this:
.. code-block:: c .. code-block:: c
extern bool g_synched; extern bool g_synched;
extern sem_t g_synch_sem; extern sem_t g_synch_sem;
@ -91,7 +91,7 @@ these sub-windows to be managed more-or-less independently:
{ {
-- Handle the error -- -- Handle the error --
} }
} }
When the window listener thread receives the ``NXEVENT_SYNCHED`` event, When the window listener thread receives the ``NXEVENT_SYNCHED`` event,
it would set ``g_synched`` to ``true`` and post ``g_synch_sem``, waking 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>`__) User provided argument (see ```nx_openwindow()`` <#nxopenwindow>`__)
:return: Success: A non-NULL handle used with subsequent NXTK window accesses :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); .. 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 Lower the window containing the specified client
sub-window to the bottom of the display. sub-window to the bottom of the display.
:param hfwnd: :param hfwnd:
A handle previously returned by A handle previously returned by
```nxtk_openwindow()`` <#nxtkopenwindow>`__ specifying the window to ```nxtk_openwindow()`` <#nxtkopenwindow>`__ specifying the window to
be lowered. 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 is reported by ``nxtk_ishidden()``. ``nxtk_synch()`` may be used if
temporal synchronization is required. temporal synchronization is required.
:param hfwnd: :param hfwnd:
The handle returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__ The handle returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__
that identifies the window to be queried. 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 Draw a circular outline using the specified line
thickness and color. thickness and color.
:param hfwnd: :param hfwnd:
A handle previously returned by A handle previously returned by
```nxtk_openwindow()`` <#nxtkopenwindow>`__. ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
:param center: :param center:
@ -371,7 +371,7 @@ these sub-windows to be managed more-or-less independently:
Fill a circular region using the specified color. Fill a circular region using the specified color.
:param hfwnd: :param hfwnd:
A handle previously returned by A handle previously returned by
```nxtk_openwindow()`` <#nxtkopenwindow>`__. ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
:param center: :param center:
@ -548,16 +548,16 @@ these sub-windows to be managed more-or-less independently:
:param caps: :param caps:
Draw a circular cap on the ends of the line to support better line Draw a circular cap on the ends of the line to support better line
joins. One of: joins. One of:
.. code-block:: c .. code-block:: c
/* Line caps */ /* Line caps */
#define NX_LINECAP_NONE 0x00, /* No 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_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_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 */ #define NX_LINECAP_BOTH 0x03 /* Line cap on both ends of the vector only */
:return: ``OK`` on success; ``ERROR`` on failure with :return: ``OK`` on success; ``ERROR`` on failure with
``errno`` set appropriately ``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 Draw a circular outline using the specified line
thickness and color. thickness and color.
:param hfwnd: :param hfwnd:
A handle previously returned by A handle previously returned by
```nxtk_openwindow()`` <#nxtkopenwindow>`__. ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
:param center: :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 Move a rectangular region within the toolbar sub-window
of a framed window. of a framed window.
:param hfwnd: :param hfwnd:
A handle identifying sub-window containing the toolbar within which A handle identifying sub-window containing the toolbar within which
the move is to be done. This handle must have previously been the move is to be done. This handle must have previously been
returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__. returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
@ -633,10 +633,10 @@ these sub-windows to be managed more-or-less independently:
:param hfwnd: :param hfwnd:
A handle previously returned by A handle previously returned by
```nxtk_openwindow()`` <#nxtkopenwindow>`__. ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
:param dest: :param dest:
Describes the rectangular region on in the toolbar sub-window will Describes the rectangular region on in the toolbar sub-window will
receive the bit map. receive the bit map.
:param src: :param src:
The start of the source image. The start of the source image.
:param origin: :param origin:
The origin of the upper, left-most corner of the full bitmap. Both 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 conflicting ways. In the NuttX PM logic, we will use the following
terminology: terminology:
``NORMAL`` ``NORMAL``
The normal, full power operating mode. The normal, full power operating mode.
``IDLE`` ``IDLE``
This is still basically normal operational mode, the system is, This is still basically normal operational mode, the system is,
however, ``IDLE`` and some simple simple steps to reduce power however, ``IDLE`` and some simple simple steps to reduce power
consumption provided that they do not interfere with normal consumption provided that they do not interfere with normal
Operation. Simply dimming the a backlight might be an example Operation. Simply dimming the a backlight might be an example
some that that would be done when the system is idle. some that that would be done when the system is idle.
``STANDBY`` ``STANDBY``
Standby is a lower power consumption mode that may involve more Standby is a lower power consumption mode that may involve more
extensive power management steps such has disabling clocking or extensive power management steps such has disabling clocking or
setting the processor into reduced power consumption modes. In setting the processor into reduced power consumption modes. In
this state, the system should still be able to resume normal this state, the system should still be able to resume normal
activity almost immediately. activity almost immediately.
``SLEEP`` ``SLEEP``
The lowest power consumption mode. The most drastic power The lowest power consumption mode. The most drastic power
reduction measures possible should be taken in this state. It reduction measures possible should be taken in this state. It
may require some time to get back to normal operation from may require some time to get back to normal operation from
``SLEEP`` (some MCUs may even require going through reset). ``SLEEP`` (some MCUs may even require going through reset).
.. c:enum:: pm_state_e .. c:enum:: pm_state_e
These various states are represented with type :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. and prevent entering reduced power states.
:param domain: Identifies the domain of the new PM activity :param domain: Identifies the domain of the new PM activity
:param priority: :param priority:
Activity priority, range 0-9. Larger values correspond to Activity priority, range 0-9. Larger values correspond to
higher priorities. Higher priority activity can prevent the higher priorities. Higher priority activity can prevent the
system from entering reduced power states for a longer period 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 state change mode by returning a non-zero value from the callback
function. function.
:param cb: :param cb:
Returned to the driver. The driver version of the callback Returned to the driver. The driver version of the callback
structure may include additional, driver-specific state data at structure may include additional, driver-specific state data at
the end of the structure. the end of the structure.
:param domain: :param domain:
Identifies the activity domain of the state change Identifies the activity domain of the state change
:param pmstate: :param pmstate:
Identifies the new PM state Identifies the new PM state
:return: :return:
Zero (``OK``) means the event was successfully Zero (``OK``) means the event was successfully
processed and that the driver is prepared for the PM state change. processed and that the driver is prepared for the PM state change.
Non-zero means that the driver is not prepared to perform the 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 callback is called after all drivers have had the opportunity to
prepare for the new power state. prepare for the new power state.
:param cb: :param cb:
Returned to the driver. The driver version of the callback Returned to the driver. The driver version of the callback
structure may include additional, driver-specific state data at structure may include additional, driver-specific state data at
the end of the structure. the end of the structure.
:param domain: :param domain:
Identifies the activity domain of the state change Identifies the activity domain of the state change
:param pmstate: :param pmstate:
Identifies the new PM state Identifies the new PM state
The driver already agreed to transition 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 dlc to CAN FD len sizes named
.. code-block:: c .. code-block:: c
extern const uint8_t can_dlc_to_len[16]; extern const uint8_t can_dlc_to_len[16];
extern const uint8_t len_to_can_dlc[65]; 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 controlling the SYSLOG output only form that process. There
will be a separate mask accessible only in the kernel code to will be a separate mask accessible only in the kernel code to
control kernel SYSLOG output. control kernel SYSLOG output.
The above are all standard interfaces as defined at The above are all standard interfaces as defined at
`OpenGroup.org <http://pubs.opengroup.org/onlinepubs/009695399/functions/closelog.html>`__. `OpenGroup.org <http://pubs.opengroup.org/onlinepubs/009695399/functions/closelog.html>`__.
Those interfaces are available for use by application software. 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 Debug Interfaces
---------------- ----------------
@ -166,7 +166,7 @@ The channel interface is instantiated by calling
:return: :return:
Zero (OK)is returned on success. A negated errno value is Zero (OK)is returned on success. A negated errno value is
returned on any failure. returned on any failure.
SYSLOG Channel Initialization SYSLOG Channel Initialization
----------------------------- -----------------------------
@ -423,14 +423,14 @@ SYSLOG file channel:
NOTE interrupt level SYSLOG output will be lost in this case NOTE interrupt level SYSLOG output will be lost in this case
unless the interrupt buffer is used. unless the interrupt buffer is used.
:param devpath: :param devpath:
The full path to the file to be used for SYSLOG The full path to the file to be used for SYSLOG
output. This may be an existing file or not. If the file output. This may be an existing file or not. If the file
exists, ``syslog_file_channel()`` will append new SYSLOG data exists, ``syslog_file_channel()`` will append new SYSLOG data
to the end of the file. If it does not, then to the end of the file. If it does not, then
``syslog_file_channel()`` will create the file. ``syslog_file_channel()`` will create the file.
:return: :return:
Zero (``OK``) is returned on success; a Zero (``OK``) is returned on success; a
negated ``errno`` value is returned on any failure. 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 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, go into ``Documentation`` directory. Then,
1. Install Sphinx and other dependencies using pipenv. 1. Install Sphinx and other dependencies using pipenv.
You may also find it helpful on platforms such as Windows and MacOS to use *pyenv* 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 to manage your python installation. You can read about installing that on the
project `site <https://github.com/pyenv/pyenv#installation>`_. project `site <https://github.com/pyenv/pyenv#installation>`_.
.. code-block:: console .. code-block:: console
$ pip3 install pipenv $ pip3 install pipenv
$ pipenv install $ pipenv install
$ # activate the virtual environent $ # activate the virtual environent
$ pipenv shell $ pipenv shell
2. Build documentation: 2. Build documentation:
.. code-block:: console .. code-block:: console
$ make html $ make html
The resulting HTMLs will end up under ``_build/html``. You can open your browser at the root with: The resulting HTMLs will end up under ``_build/html``. You can open your browser at the root with:
.. code-block:: console .. code-block:: console
$ xdg-open _build/html/index.html $ xdg-open _build/html/index.html
Contributing Contributing
============ ============
@ -85,35 +85,35 @@ Sections should look like this:
Subsection Subsection
========== ==========
Subsubsection Subsubsection
------------- -------------
Code 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: This means for example that a function should be documented as:
.. code-block:: RST .. code-block:: RST
.. c:function:: bool myfunction(int arg1, int arg2) .. c:function:: bool myfunction(int arg1, int arg2)
Here the function should be described Here the function should be described
:param arg1: Description of arg1 :param arg1: Description of arg1
:param arg2: Description of arg2 :param arg2: Description of arg2
:return: Description of return value :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, 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: it is acceptable to use RST standard `::`. This is specially useful and compact when used in the following mode:
.. code-block:: RST .. code-block:: RST
The text file should have the following content:: The text file should have the following content::
Line1 Line1
Line2 Line2
Line3 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. 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 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 .. code-block:: RST
This is a Section This is a Section
================= =================
:ref:`This is a Section` is a link to this very same 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>```. If the target is in a different file, you can refer it with: ``:ref:`link text </pathtorst:Section Name>```.
Notes and TODOS Notes and TODOS
@ -176,10 +176,10 @@ Generally, you should follow this format:
.. code-block:: RST .. code-block:: RST
.. directive:: .. directive::
child content child content
non-child content which appears after previous directive non-child content which appears after previous directive
Note the line between directive and content and the indentation. Note the line between directive and content and the indentation.

2
Documentation/contributing/index.rst
View file

@ -1,7 +1,7 @@
Contributing 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): and documentation (the one you are reading now):
.. toctree:: .. 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`` - 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 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. 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, 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 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 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. 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 - 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. 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 - 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>`. 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 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. will have to authorize this and submit the appropriate license agreements.
- If you are submitting third-party code: - 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, 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. 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 - 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. 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 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). (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`) - ``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`` - ``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: NOTES:
1. See include/nuttx/usb/usbdev_trace.h 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: In the above example you can see that:
- **1**. The serial class USB setup method was called for the USB - **1**. The serial class USB setup method was called for the USB
serial class. This is the corresponds to the following logic in serial class. This is the corresponds to the following logic in
``drivers/usbdev/pl2303.c``: ``drivers/usbdev/pl2303.c``:
.. code-block:: c .. code-block:: c
static int pl2303_setup(FAR struct uart_dev_s *dev) 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 - **2**. An error occurred while processing the setup command because
no configuration has yet been selected by the host. This corresponds no configuration has yet been selected by the host. This corresponds
to the following logic in ``drivers/usbdev/pl2303.c``: to the following logic in ``drivers/usbdev/pl2303.c``:
.. code-block:: c .. code-block:: c
static int pl2303_setup(FAR struct uart_dev_s *dev) 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). . (or increase the rate at which the trace buffer is emptied).
``CONFIG_USBDEV_TRACE_STRINGS=y`` Optionally, convert trace ID numbers to strings. ``CONFIG_USBDEV_TRACE_STRINGS=y`` Optionally, convert trace ID numbers to strings.
. This feature may not be supported by all drivers. . This feature may not be supported by all drivers.
=========================================== =================================================== =========================================== ===================================================
=========================================== =================================================== =========================================== ===================================================
Application Configuration -> NSH LIbrary . Application Configuration -> NSH LIbrary .
``CONFIG_NSH_USBDEV_TRACE=n`` Make sure that any built-in tracing from NSH is disabled. ``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 ``CONFIG_NSH_ARCHINIT=y`` Enable this option only if your board-specific logic
. has logic to automatically start the USB monitor. . has logic to automatically start the USB monitor.
. Otherwise the USB monitor can be started or stopped . Otherwise the USB monitor can be started or stopped
. with the usbmon_start and usbmon_stop commands from the NSH console. . with the usbmon_start and usbmon_stop commands from the NSH console.
=========================================== =================================================== =========================================== ===================================================
=============================================== ============================================ =============================================== ============================================
Application Configuration -> System NSH Add-Ons . Application Configuration -> System NSH Add-Ons .
``CONFIG_USBMONITOR=y`` Enable the USB monitor daemon ``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 . If you lose buffered USB trace data, then dropping
. this value will help by increasing the rate at which . this value will help by increasing the rate at which
. the USB trace buffer is emptied. . 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_TRACECLASS=y`` .
``CONFIG_USBMONITOR_TRACETRANSFERS=y`` . ``CONFIG_USBMONITOR_TRACETRANSFERS=y`` .
``CONFIG_USBMONITOR_TRACECONTROLLER=y`` . ``CONFIG_USBMONITOR_TRACECONTROLLER=y`` .
``CONFIG_USBMONITOR_TRACEINTERRUPTS=y`` . ``CONFIG_USBMONITOR_TRACEINTERRUPTS=y`` .
=============================================== ============================================ =============================================== ============================================
NOTE: If USB debug output is also enabled, both outputs will appear on NOTE: If USB debug output is also enabled, both outputs will appear on
the serial console. However, the debug output will be asynchronous with the serial console. However, the debug output will be asynchronous with

8
Documentation/index.rst
View file

@ -1,12 +1,12 @@
.. note:: .. 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 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 formatting errors. You can help contribute fixes or improvements to this documentation
by following these :doc:`instructions <contributing/documentation>`. by following these :doc:`instructions <contributing/documentation>`.
.. tip:: .. 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 NuttX Documentation
=================== ===================
@ -31,5 +31,5 @@ Last Updated: |today|
releases/index.rst releases/index.rst
contributing/index.rst contributing/index.rst
glossary.rst glossary.rst
.. include:: substitutions.rst .. include:: substitutions.rst

70
Documentation/make.bat
View file

@ -1,35 +1,35 @@
@ECHO OFF @ECHO OFF
pushd %~dp0 pushd %~dp0
REM Command file for Sphinx documentation REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" ( if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build set SPHINXBUILD=sphinx-build
) )
set SOURCEDIR=. set SOURCEDIR=.
set BUILDDIR=_build set BUILDDIR=_build
if "%1" == "" goto help if "%1" == "" goto help
%SPHINXBUILD% >NUL 2>NUL %SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 ( if errorlevel 9009 (
echo. echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH. echo.may add the Sphinx directory to PATH.
echo. echo.
echo.If you don't have Sphinx installed, grab it from echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/ echo.http://sphinx-doc.org/
exit /b 1 exit /b 1
) )
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end goto end
:help :help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
:end :end
popd 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 $ cd nuttx
$ ./tools/configure.sh -L | less $ ./tools/configure.sh -L | less
The output is in the format ``<board name>:<board configuration>``. You will see that 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 generally all boards support the ``nsh`` configuration which is a good sarting point
since it enables booting into the interactive command line 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 $ cd nuttx
$ ./tools/configure.sh -l stm32f4discovery:nsh $ ./tools/configure.sh -l stm32f4discovery:nsh
The ``-l`` tells use that we're on Linux (macOS and Windows builds are The ``-l`` tells use that we're on Linux (macOS and Windows builds are
possible). Use the ``-h`` argument to see all available options. 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/ $ cd nuttx/
$ make menuconfig $ make menuconfig
.. todo:: .. todo::
Explain some useful options. Explain some useful options.
@ -63,18 +63,18 @@ We can now build NuttX. To do so, you can simply run:
$ cd nuttx/ $ cd nuttx/
$ make make $ make make
The build will complete by generating the binary outputs The build will complete by generating the binary outputs
inside `nuttx` directory. Typically this includes the `nuttx` inside `nuttx` directory. Typically this includes the `nuttx`
ELF file (suitable for debugging using `gdb`) and a `nuttx.bin` 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: To clean the build, you can do:
.. code-block:: console .. code-block:: console
$ make clean $ make clean
.. warning:: .. warning::
At the moment it is recommended that after modifying the At the moment it is recommended that after modifying the
configuration you first clean before building again. This configuration you first clean before building again. This

2
Documentation/quickstart/index.rst
View file

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

36
Documentation/quickstart/install.rst
View file

@ -14,7 +14,7 @@ Prerequisites
.. tabs:: .. tabs::
.. tab:: Linux .. tab:: Linux
#. Install system packages #. Install system packages
.. code-block:: console .. code-block:: console
@ -63,7 +63,7 @@ Prerequisites
gcc-g++ gperf libncurses-devel gcc-g++ gperf libncurses-devel
flex gdb libmpfr-devel flex gdb libmpfr-devel
git unzip zlib-devel git unzip zlib-devel
To complete the installation of prerequisites, you need to install `kconfig-frontends` To complete the installation of prerequisites, you need to install `kconfig-frontends`
as instructed in the :doc:`quickstart` guide. 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 according to your target platform. Some Operating Systems
such as Linux distribute toolchains for various architectures. such as Linux distribute toolchains for various architectures.
This is usually an easy choice however you should be aware 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 problems and it may better to use a widely used build from
another source. another source.
@ -84,15 +84,15 @@ ARM architecture:
.. tabs:: .. tabs::
.. code-tab:: console Ubuntu (deb) .. code-tab:: console Ubuntu (deb)
$ apt install gcc-arm-none-eabi binutils-arm-none-eabi $ apt install gcc-arm-none-eabi binutils-arm-none-eabi
.. tab:: From arm.com .. tab:: From arm.com
First, create a directory to hold the toolchain: First, create a directory to hold the toolchain:
.. code-block:: console .. code-block:: console
$ usermod -a -G users $USER $ usermod -a -G users $USER
$ # get a login shell that knows we're in this group: $ # get a login shell that knows we're in this group:
$ su - $USER $ su - $USER
@ -100,25 +100,25 @@ ARM architecture:
$ sudo chgrp -R users /opt/gcc $ sudo chgrp -R users /opt/gcc
$ sudo chmod -R u+rw /opt/gcc $ sudo chmod -R u+rw /opt/gcc
$ cd /opt/gcc $ cd /opt/gcc
Download and extract toolchain: Download and extract toolchain:
.. code-block:: console .. code-block:: console
$ HOST_PLATFORM=x86_64-linux # use "mac" for macOS. $ 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) $ # 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 $ 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 $ tar xf gcc-arm-none-eabi-9-2019-q4-major-${HOST_PLATFORM}.tar.bz2
Add the toolchain to your `PATH`: Add the toolchain to your `PATH`:
.. code-block:: console .. code-block:: console
$ echo "export PATH=/opt/gcc/gcc-arm-none-eabi-9-2019-q4-major/bin:$PATH" >> ~/.bashrc $ 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. 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 There are hints on how to get the latest tool chains for most supported
architectures in the Apache NuttX CI helper architectures in the Apache NuttX CI helper
`script <https://github.com/apache/incubator-nuttx-testing/blob/master/cibuild.sh>`_ `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. Now that all required tools are installed, you need to download NuttX source-code.
.. tabs:: .. tabs::
.. tab:: Development (Git) .. tab:: Development (Git)
Apache NuttX is `actively developed on GitHub <https://github.com/apache/incubator-nuttx/>`_. 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). # optionally, zipball is also available (for Windows users).
.. tab:: Stable Release .. tab:: Stable Release
Apache NuttX releases are published on the project `Downloads <https://nuttx.apache.org/download/>`_ 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. 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. 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:: .. tabs::
.. code-tab:: console Ubuntu 20.04 LTS and later .. code-tab:: console Ubuntu 20.04 LTS and later
$ apt install kconfig-frontends $ 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> $ ./tools/configure.sh -l <board-name>:<config-dir>
# for instance: # for instance:
$ ./tools/configure.sh -l sama5d27-xult:nsh $ ./tools/configure.sh -l sama5d27-xult:nsh
#. Customize Your Configuration (Optional) #. 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 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 $ 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. 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 #. Compile Apache NuttX
.. code-block:: bash .. 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 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 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: To install the stable version of openocd you can do:
.. code-block:: console .. code-block:: console
$ apt install openocd $ apt install openocd
.. todo:: add instructions for other platforms .. todo:: add instructions for other platforms
You should note that openocd project has not made stable releases for long 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 $ ./bootstrap
$ ./configure --prefix install/ $ ./configure --prefix install/
$ make install $ make install
The resulting installation will be under ``openocd/install``. You can add The resulting installation will be under ``openocd/install``. You can add
``openocd/install/bin`` to your ``PATH``. ``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/ $ cd nuttx/
$ openocd -f interface/st-link-v2.cfg -f target/stm32f1x.cfg -c 'init' \ $ openocd -f interface/st-link-v2.cfg -f target/stm32f1x.cfg -c 'init' \
-c 'program nuttx/nuttx.bin verify reset' -c 'shutdown' -c 'program nuttx/nuttx.bin verify reset' -c 'shutdown'
Access NuttShell Access NuttShell
================ ================
@ -64,13 +64,13 @@ of your choice where you will see the ``nsh>`` prompt:
.. tabs:: .. tabs::
.. code-tab:: console picocom (CLI) .. code-tab:: console picocom (CLI)
$ picocom -b 115200 /dev/ttyUSB0 $ picocom -b 115200 /dev/ttyUSB0
.. code-tab:: console gtkterm (GUI) .. code-tab:: console gtkterm (GUI)
$ gtkterm -s 115200 -p /dev/ttyUSB0 $ gtkterm -s 115200 -p /dev/ttyUSB0
Debugging Debugging
========= =========
@ -80,20 +80,20 @@ Using ``openocd`` you can also debug NuttX. To do so, first run:
.. code-block:: console .. code-block:: console
$ openocd -f interface/st-link-v2.cfg -f target/stm32f1x.cfg $ openocd -f interface/st-link-v2.cfg -f target/stm32f1x.cfg
which will start a GDB server. Then, start ``gdb`` as: which will start a GDB server. Then, start ``gdb`` as:
.. code-block:: console .. code-block:: console
$ cd nuttx/ $ cd nuttx/
$ gdb-multiarch nuttx/nuttx $ gdb-multiarch nuttx/nuttx
Inside ``gdb`` console, connect to the ``openocd`` server with: Inside ``gdb`` console, connect to the ``openocd`` server with:
.. code-block:: .. code-block::
(gdb) target extended-remote :3333 (gdb) target extended-remote :3333
You can debug using standard ``gdb`` commands. You can debug using standard ``gdb`` commands.
Advanced Debugging with JTAG Advanced Debugging with JTAG

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

@ -1,6 +1,6 @@
==================== ====================
Address Environments Address Environments
==================== ====================
CPUs that support memory management units (MMUs) may provide CPUs that support memory management units (MMUs) may provide
*address environments* within which tasks and their child threads *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 This function is called when a new task is created in order to
instantiate an address environment for the new task group. 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 :param textsize: The size (in bytes) of the ``.text`` address
environment needed by the task. This region may be read/execute 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 Return the virtual .text address associated with the newly create
address environment. This function is used by the binary loaders 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 :param addrenv: The representation of the task address environment
previously returned by ``up_addrenv_create()``. previously returned by ``up_addrenv_create()``.
:param vtext: The location to return the virtual address. :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) .. 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 Return the virtual .text address associated with the newly create
address environment. This function is used by the binary loaders 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 :param addrenv: The representation of the task address environment
previously returned by ``up_addrenv_create()``. 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. offset into the common region.
:param vdata: The location to return the virtual address. :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) .. c:function:: ssize_t up_addrenv_heapsize(FAR const group_addrenv_t *addrenv)
Return the initial heap allocation size. That is the amount of Return the initial heap allocation size. That is the amount of
memory allocated by up_addrenv_create() when the heap memory memory allocated by up_addrenv_create() when the heap memory
region was first created. This may or may not differ from the 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 :param addrenv: The representation of the task address environment
previously returned by ``up_addrenv_create()``. previously returned by ``up_addrenv_create()``.
:return: The initial heap size allocated is returned on success; :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) .. 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 (via up_addrenv_create()), this function may be called to instantiate
that address environment in the virtual address space. This might be 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 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 :param addrenv: The representation of the task address environment
previously returned by ``up_addrenv_create()``. 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 platform-specific representation that may or may not be
different from ``group_addrenv_t``. 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) .. c:function:: int up_addrenv_restore(save_addrenv_t oldenv)
After an address environment has been temporarily instantiated After an address environment has been temporarily instantiated
by up_addrenv_select, this function may be called to restore 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 :param oldenv: The platform-specific representation of the address
environment previously returned by ``up_addrenv_select()``. 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 Duplicate an address environment. This does not copy the underlying
memory, only the representation that can be used to instantiate 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 src: The address environment to be copied.
:param dest: The location to receive the copied address :param dest: The location to receive the copied address
environment. 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) .. 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 :param ctcb: The TCB of the thread needing the address
environment. 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) .. 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 to release its reference to an address environment. The address
environment, however, should persist until up_addrenv_destroy() environment, however, should persist until up_addrenv_destroy()
is called when the task group is itself destroyed. Any resources 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 group: The group to which the thread belonged.
:param tcb: The TCB of the task or thread whose the address :param tcb: The TCB of the task or thread whose the address
environment will be released. 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) .. 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. to instantiate an address environment for the new thread's stack.
up_addrenv_ustackalloc() is essentially the allocator of the up_addrenv_ustackalloc() is essentially the allocator of the
physical memory for the new task's stack. 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 environment needed by the task. This region may be read/write
only. 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) .. c:function:: int up_addrenv_ustackfree(FAR struct tcb_s *tcb)
This function is called when any thread exits. This function then This function is called when any thread exits. This function then
destroys the defunct address environment for the thread's stack, 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 :param tcb: The TCB of the thread that no longer requires the
stack address environment. 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 tcb: The TCB of the thread with the stack address environment of interest.
:param vstack: The location to return the stack virtual base address. :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) .. 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 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 new thread's kernel stack. This function may be called for certain
terminating threads which have no kernel stack. It must be 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. :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); .. 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 :param tcb: The TCB of the thread that no longer requires the
kernel stack. 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. of the argument is determined by the specific command.
:return: On success zero (OK) is returned; -1 (ERROR) is :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 Configuration Options
===================== =====================
``CONFIG_MM_IOB`` ``CONFIG_MM_IOB``
Enables generic I/O buffer support. This setting will build the Enables generic I/O buffer support. This setting will build the
common I/O buffer (IOB) support library. common I/O buffer (IOB) support library.
``CONFIG_IOB_NBUFFERS`` ``CONFIG_IOB_NBUFFERS``
Number of pre-allocated I/O buffers. Each packet is represented Number of pre-allocated I/O buffers. Each packet is represented
by a series of small I/O buffers in a chain. This setting by a series of small I/O buffers in a chain. This setting
determines the number of preallocated I/O buffers available for 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 is enabled (neither ``CONFIG_NET_TCP_WRITE_BUFFERS`` nor
``CONFIG_NET_TCP``), 24 if only TCP/UDP is enabled, and 36 if ``CONFIG_NET_TCP``), 24 if only TCP/UDP is enabled, and 36 if
both TCP/UDP and write buffering are enabled. 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 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 series of small I/O buffers in a chain. This setting determines
the data payload each preallocated I/O buffer. The default the data payload each preallocated I/O buffer. The default
value is 196 bytes. value is 196 bytes.
``CONFIG_IOB_NCHAINS`` ``CONFIG_IOB_NCHAINS``
Number of pre-allocated I/O buffer chain heads. These tiny Number of pre-allocated I/O buffer chain heads. These tiny
nodes are used as *containers* to support queueing of I/O nodes are used as *containers* to support queueing of I/O
buffer chains. This will limit the number of I/O transactions 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 zero if nether TCP nor UDP is enabled (i.e., neither
``CONFIG_NET_TCP`` && !\ ``CONFIG_NET_UDP`` or eight if either ``CONFIG_NET_TCP`` && !\ ``CONFIG_NET_UDP`` or eight if either
is enabled. is enabled.
``CONFIG_IOB_THROTTLE`` ``CONFIG_IOB_THROTTLE``
I/O buffer throttle value. TCP write buffering and read-ahead I/O buffer throttle value. TCP write buffering and read-ahead
buffer use the same pool of free I/O buffers. In order to buffer use the same pool of free I/O buffers. In order to
prevent uncontrolled incoming TCP packets from hogging all of 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. denied to the read-ahead logic before TCP writes are halted.
The default 0 if neither TCP write buffering nor TCP read-ahead The default 0 if neither TCP write buffering nor TCP read-ahead
buffering is enabled. Otherwise, the default is 8. 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 Force I/O buffer debug. This option will force debug output
from I/O buffer logic. This is not normally something that 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 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()``). interfaces (such as ``stm32_led_initialize()``).
.. c:function:: void board_autoled_on(int led) .. c:function:: void board_autoled_on(int led)
Called to instantiate the LED Called to instantiate the LED
presentation of the event. The ``led`` argument is one of the presentation of the event. The ``led`` argument is one of the
definitions provided in ``<board-name>/include/board.h``. definitions provided in ``<board-name>/include/board.h``.
.. c:function:: void board_autoled_off(int led) .. c:function:: void board_autoled_off(int led)
Called to terminate the LED Called to terminate the LED
presentation of the event. The ``led`` argument is one of the presentation of the event. The ``led`` argument is one of the
definitions provided in ``<board-name>/include/board.h``. Note 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 */ unsigned int flag; /* Filter mode flag */
#ifdef CONFIG_SMP #ifdef CONFIG_SMP
unsigned int cpuset; /* The set of monitored CPUs */ unsigned int cpuset; /* The set of monitored CPUs */
#endif #endif
}; };
- ``flag`` : Filter mode flag. The bitwise OR of the following defines are available. - ``flag`` : Filter mode flag. The bitwise OR of the following defines are available.
.. c:macro:: NOTE_FILTER_MODE_FLAG_ENABLE .. c:macro:: NOTE_FILTER_MODE_FLAG_ENABLE
Enable instrumentation Enable instrumentation
.. c:macro:: NOTE_FILTER_MODE_FLAG_SYSCALL .. c:macro:: NOTE_FILTER_MODE_FLAG_SYSCALL
Enable syscall instrumentation Enable syscall instrumentation
.. c:macro:: NOTE_FILTER_MODE_FLAG_IRQ .. c:macro:: NOTE_FILTER_MODE_FLAG_IRQ
Enable IRQ instrumentaiton Enable IRQ instrumentaiton
- ``cpuset`` : (SMP only) Monitor only CPUs in the bitset. Bit 0=CPU0, Bit1=CPU1, etc. - ``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. The overwrite mode takes one of the following values.
.. c:macro:: NOTERAM_MODE_OVERWRITE_DISABLE .. c:macro:: NOTERAM_MODE_OVERWRITE_DISABLE
Overwrite mode is disabled. When the buffer is full, accepting the data will be stopped. Overwrite mode is disabled. When the buffer is full, accepting the data will be stopped.
.. c:macro:: NOTERAM_MODE_OVERWRITE_ENABLE .. 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. the tick-less OS expires.
**Assumptions**: Base code implementation assumes that this **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); .. c:function:: void nxsched_alarm_expiration(void);
@ -40,7 +40,7 @@ OS List Management APIs
the tick-less OS expires. the tick-less OS expires.
**Assumptions**: Base code implementation assumes that this **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) .. 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) .. 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 :param pages: A pointer to the first element in a array of
physical address, each corresponding to one page of memory. physical address, each corresponding to one page of memory.
@ -23,16 +23,16 @@ below:
:param vaddr: The virtual address corresponding to the beginning :param vaddr: The virtual address corresponding to the beginning
of the (contiguous) virtual address region. 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) .. 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 :param vaddr: The virtual address corresponding to the beginning
of the (contiguous) virtual address region. of the (contiguous) virtual address region.
:param npages: T The number of pages to be unmapped. :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) .. 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. :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 either SP_LOCKED if the spinlock was previously locked
(meaning that the test-and-set operation failed to obtain the lock) (meaning that the test-and-set operation failed to obtain the lock)
or SP_UNLOCKED if the spinlock was previously unlocked 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) .. c:function:: int up_cpu_index(void)
Return an index in the range of 0 through (CONFIG_SMP_NCPUS-1) 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 :return: An integer index in the range of 0 through
(CONFIG_SMP_NCPUS-1) that corresponds to the (CONFIG_SMP_NCPUS-1) that corresponds to the
currently executing CPU. currently executing CPU.
.. c:function:: int up_cpu_start(int 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 numeric value in the range of from one to
``(CONFIG_SMP_NCPUS-1)``). (CPU 0 is already active). ``(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) .. 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) .. 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 restoring the state of the task at the head of the
``g_assignedtasks[cpu]`` list, and resume normal tasking. ``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 :param cpu: The index of the CPU being resumed. This will not be
the index of the currently executing CPU. 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 #. Initially an accumulator is zero an the match value is
programmed to 328: programmed to 328:
.. code-block:: c .. code-block:: c
accumulator = 0; accumulator = 0;
match = 328; match = 328;
@ -66,9 +66,9 @@ run. Consider this example implementation:
that, in this reflects, 100\* the error in interval that just that, in this reflects, 100\* the error in interval that just
passed. So on the first timer interrupt, the accumulator would passed. So on the first timer interrupt, the accumulator would
be updated like: be updated like:
.. code-block:: c .. code-block:: c
if (match == 328) if (match == 328)
{ {
accumulator += 32; // 100*(328 - 327.68) accumulator += 32; // 100*(328 - 327.68)
@ -76,13 +76,13 @@ run. Consider this example implementation:
else else
{ {
accumulator -= 68; // (100*(327 - 327.68) accumulator -= 68; // (100*(327 - 327.68)
} }
#. And on that same timer interrupt a new match value would be #. And on that same timer interrupt a new match value would be
programmed: programmed:
.. code-block:: c .. code-block:: c
if (accumulator < 0) if (accumulator < 0)
{ {
match = 328; match = 328;
@ -91,7 +91,7 @@ run. Consider this example implementation:
{ {
match = 327; match = 327;
} }
In this way, the timer interval is controlled from In this way, the timer interval is controlled from
interrupt-to-interrupt to produce an average frequency of exactly interrupt-to-interrupt to produce an average frequency of exactly
100Hz. 100Hz.
@ -101,10 +101,10 @@ Hardware
To enable hardware module use the following configuration options: To enable hardware module use the following configuration options:
``CONFIG_RTC`` ``CONFIG_RTC``
Enables general support for a hardware RTC. Specific Enables general support for a hardware RTC. Specific
architectures may require other specific settings. architectures may require other specific settings.
``CONFIG_RTC_EXTERNAL`` ``CONFIG_RTC_EXTERNAL``
Most MCUs include RTC hardware built into the chip. Other RTCs, Most MCUs include RTC hardware built into the chip. Other RTCs,
*external* MCUs, may be provided as separate chips typically *external* MCUs, may be provided as separate chips typically
interfacing with the MCU via a serial interface such as SPI or 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. booted and can support the required serial communications.
``CONFIG_RTC_EXTERNAL`` will configure the operating system so ``CONFIG_RTC_EXTERNAL`` will configure the operating system so
that it defers initialization of its time facilities. 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 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 counter that keeps the time when power is down, and (2) A full
date / time RTC the provides the date and time information, 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 specifies this second kind of RTC. In this case, the RTC is
used to "seed"" the normal NuttX timer and the NuttX system used to "seed"" the normal NuttX timer and the NuttX system
timer provides for higher resolution time. timer provides for higher resolution time.
``CONFIG_RTC_HIRES`` ``CONFIG_RTC_HIRES``
If ``CONFIG_RTC_DATETIME`` not selected, then the simple, If ``CONFIG_RTC_DATETIME`` not selected, then the simple,
battery backed counter is used. There are two different battery backed counter is used. There are two different
implementations of such simple counters based on the time 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, If ``CONFIG_RTC_HIRES`` is enabled in the NuttX configuration,
then the RTC provides higher resolution time and completely then the RTC provides higher resolution time and completely
replaces the system timer for purpose of date and time. 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 If ``CONFIG_RTC_HIRES`` is defined, then the frequency of the
high resolution RTC must be provided. If ``CONFIG_RTC_HIRES`` high resolution RTC must be provided. If ``CONFIG_RTC_HIRES``
is not defined, ``CONFIG_RTC_FREQUENCY`` is assumed to be one. 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 Enable if the RTC hardware supports setting of an alarm. A
callback function will be executed when the alarm goes off 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() 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). and the interval timer is ready for use (but not actively timing).
The naming will depend on the architecture so for STM32 ``archname`` will 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 **Assumptions**: Called early in the initialization sequence before
any special concurrency protections are required. any special concurrency protections are required.
@ -395,12 +395,12 @@ timer implementation:
:param ts: Provides the location in which to return the up-time.. :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 **Assumptions**: Called from the normal tasking context. The
implementation must provide whatever mutual exclusion is necessary implementation must provide whatever mutual exclusion is necessary
for correct operation. This can include disabling interrupts in 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) .. 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 time should be returned if the timer is not active. ``ts`` may
be ``NULL`` in which case the time is not returned 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 **Assumptions**: May be called from interrupt level handling or
from the normal tasking level. interrupts may need to be disabled 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) .. 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 occur. When the alarm occurs the timer logic will call
``nxsched_timer_expiration()``. ``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 **Assumptions**: May be called from interrupt level handling or
from the normal tasking level. Interrupts may need to be 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) .. 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 :param ts: Location to return the remaining time. Zero should be
returned if the timer is not active. 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 **Assumptions**: May be called from interrupt level handling or
from the normal tasking level. interrupts may need to be 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_start(FAR const struct timespec *ts) .. 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 :param ts: Provides the time interval until
``nxsched_timer_expiration()`` is called. ``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 **Assumptions**: May be called from interrupt level handling
or from the normal tasking level. Interrupts may need to be 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 Watchdog Timer Interfaces
========================= =========================
@ -562,18 +562,18 @@ with NuttX tasks.
watchdog time expires. Zero means either that wdog is not valid or watchdog time expires. Zero means either that wdog is not valid or
that the wdog has already expired. 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, **Watchdog Timer Callback**: when a watchdog expires,
the callback function with this type is the callback function with this type is
called. called.
The argument is passed as scalar ``wdparm_t`` values. For The argument is passed as scalar ``wdparm_t`` values. For
systems where the ``sizeof(pointer) < sizeof(uint32_t)``, the systems where the ``sizeof(pointer) < sizeof(uint32_t)``, the
following union defines the alignment of the pointer within the following union defines the alignment of the pointer within the
``uint32_t``. For example, the SDCC MCS51 general pointer is ``uint32_t``. For example, the SDCC MCS51 general pointer is
24-bits, but ``uint32_t`` is 32-bits (of course). 24-bits, but ``uint32_t`` is 32-bits (of course).
We always have ``sizeof(pointer) <= sizeof(uintptr_t)`` by We always have ``sizeof(pointer) <= sizeof(uintptr_t)`` by
definition. 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 until the worker is invoked. Zero means to perform the work
immediately. 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) .. 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. :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) .. 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. :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) .. 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. :return: The task ID of the worker thread is returned on success.
A negated ``errno`` value is returned on failure. A negated ``errno`` value is returned on failure.
.. c:function:: void lpwork_boostpriority(uint8_t reqprio) .. c:function:: void lpwork_boostpriority(uint8_t reqprio)
Called by the work queue client to assure that 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_getstacksize`
- :c:func:`task_spawnattr_setstacksize` - :c:func:`task_spawnattr_setstacksize`
- :c:func:`posix_spawn_file_actions_init` - :c:func:`posix_spawn_file_actions_init`
Functions Functions
--------- ---------
.. c:function:: int task_create(char *name, int priority, int stack_size, main_t entry, char * const argv[]) .. 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 This function creates and activates a new task with a
specified priority and returns its system-assigned ID. 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 :param argv: A pointer to an array of input parameters. The array should
be terminated with a NULL argv[] value. If no parameters are be terminated with a NULL argv[] value. If no parameters are
required, argv may be NULL. required, argv may be NULL.
:return: the non-zero task ID of the new task or ERROR if memory is :return: the non-zero task ID of the new task or ERROR if memory is
insufficient or the task cannot be created insufficient or the task cannot be created
(```errno`` <#ErrnoAccess>`__ is not set). (```errno`` <#ErrnoAccess>`__ is not set).
**Defined in:** ``sched.h`` **Defined in:** ``sched.h``
**POSIX Compatibility:** This is a NON-POSIX interface. VxWorks provides **POSIX Compatibility:** This is a NON-POSIX interface. VxWorks provides
the following similar interface: the following similar interface:
.. code-block:: c .. code-block:: c
int taskSpawn(char *name, int priority, int options, int stackSize, FUNCPTR entryPt, 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. - Restart of the currently running task is not supported by NuttX.
- The VxWorks description says that the ID, priority, etc. take the - The VxWorks description says that the ID, priority, etc. take the
value that they had when the task was *terminated*. value that they had when the task was *terminated*.
.. c:function:: int task_setcancelstate(int state, int *oldstate) .. c:function:: int task_setcancelstate(int state, int *oldstate)
This function atomically sets This function atomically sets
@ -305,7 +305,7 @@ Functions
the functionality of ``pthread_testcancel()`` to tasks and supports use the functionality of ``pthread_testcancel()`` to tasks and supports use
of ``task_delete()``. of ``task_delete()``.
.. c:function:: void exit(int code) .. c:function:: void exit(int code)
.. c:function:: void _exit(int code) .. c:function:: void _exit(int code)
.. #include <sched.h> .. #include <sched.h>
@ -793,7 +793,7 @@ Functions
FAR const posix_spawn_file_actions_t *file_actions, \ FAR const posix_spawn_file_actions_t *file_actions, \
FAR const posix_spawnattr_t *attr, \ FAR const posix_spawnattr_t *attr, \
FAR char * const argv[], FAR char * const envp[]) FAR char * const argv[], FAR char * const envp[])
The ``task_spawn()`` function will create a new, child The ``task_spawn()`` function will create a new, child
task, where the entry point to the task is an address in memory. 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: name. Differences from the full POSIX implementation include:
- The range of priority values for the POSIX call is 0 to 255. - 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 .. 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 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) .. c:function:: int sched_getparam(pid_t pid, FAR struct sched_param *param)
This function gets the scheduling priority of the task This function gets the scheduling priority of the task
specified by pid. 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 within the task group. Members of a task group share certain
resources such as environment variables, file descriptors, ``FILE`` resources such as environment variables, file descriptors, ``FILE``
streams, sockets, pthread keys and open message queues. streams, sockets, pthread keys and open message queues.
- :c:func:`atexit` - :c:func:`atexit`
- :c:func:`on_exit` - :c:func:`on_exit`
.. note:: .. note::
Behavior of features related to task group's depend of Behavior of features related to task group's depend of
NuttX configuration settings. See the discussion of "Parent and NuttX configuration settings. See the discussion of "Parent and
Child Tasks," below. See also the\ `NuttX Child Tasks," below. See also the\ `NuttX
@ -132,9 +132,9 @@ Functions
**POSIX Compatibility:** This is a NON-POSIX interface. VxWorks provides **POSIX Compatibility:** This is a NON-POSIX interface. VxWorks provides
the comparable interface: the comparable interface:
.. code-block:: c .. code-block:: c
STATUS taskLock(void); STATUS taskLock(void);
.. c:function:: int sched_unlock(void) .. c:function:: int sched_unlock(void)
@ -147,10 +147,10 @@ Functions
task will execute. task will execute.
:return: OK or ERROR. :return: OK or ERROR.
**POSIX Compatibility:** This is a NON-POSIX interface. VxWorks provides **POSIX Compatibility:** This is a NON-POSIX interface. VxWorks provides
the comparable interface: the comparable interface:
.. code-block:: c .. code-block:: c
STATUS taskUnlock(void); STATUS taskUnlock(void);
@ -168,7 +168,7 @@ Functions
.. c:function:: ipid_t waitpid(pid_t pid, int *stat_loc, int options) .. c:function:: ipid_t waitpid(pid_t pid, int *stat_loc, int options)
.. note:: .. note::
The following discussion is a general description of the The following discussion is a general description of the
``waitpid()`` interface. However, as of this writing, the ``waitpid()`` interface. However, as of this writing, the
implementation of ``waitpid()`` is incomplete (but usable). If 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 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 with the status of the process. The ``si_signo`` member will always be
equal to ``SIGCHLD``. equal to ``SIGCHLD``.
:return: If ``waitid()`` returns due to the change of state :return: If ``waitid()`` returns due to the change of state
of one of its children, 0 is returned. Otherwise, -1 is returned and of one of its children, 0 is returned. Otherwise, -1 is returned and
``errno`` is set to indicate the error. ``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 **POSIX Compatibility:** Comparable to the POSIX interface of the same
name. name.
.. c:function:: int sem_timedwait(sem_t *sem, const struct timespec *abstime) .. c:function:: int sem_timedwait(sem_t *sem, const struct timespec *abstime)
This function will lock the semaphore referenced by sem 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 return the pointer, ``buf``, provided by the caller. Otherwise, a NULL
will be returned to indicate the error. 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 Converts the time provided in seconds
since the epoch to a string representation. ``ctime()`` is re-entrant. 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 default actions dependent upon addition configuration settings as
summarized in the following table: summarized in the following table:
======= ==================== ========================= ======= ==================== =========================
Signal Action Additional Configuration Signal Action Additional Configuration
======= ==================== ========================= ======= ==================== =========================
SIGUSR1 Abnormal Termination CONFIG_SIG_SIGUSR1_ACTION SIGUSR1 Abnormal Termination CONFIG_SIG_SIGUSR1_ACTION
@ -236,7 +236,7 @@ provided by NuttX:
:param signo: The signal number to act on :param signo: The signal number to act on
:return: :return:
- Zero is returned upon successful completion, otherwise -1 (``ERROR``) - Zero is returned upon successful completion, otherwise -1 (``ERROR``)
is returned with the errno set appropriately. The ``errno`` value of is returned with the errno set appropriately. The ``errno`` value of
``EINVAL``, for example, would indicate that ``signo`` argument is ``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 signo: The signal number to operate on
:param disp: The new disposition of the signal :param disp: The new disposition of the signal
:return: :return:
- Upon successful completion, ``sigset()`` will the previous - Upon successful completion, ``sigset()`` will the previous
disposition of the signal. Otherwise, ``SIG_ERR`` will be returned disposition of the signal. Otherwise, ``SIG_ERR`` will be returned
and ``errno`` set to indicate the error. and ``errno`` set to indicate the error.
@ -279,7 +279,7 @@ provided by NuttX:
:param how: How the signal mask will be changed. :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_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. - ``SIG_SETMASK`` The resulting set is the signal set pointed to by the ``set`` input parameter.
:param set: Location of the new signal mask :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 - ``pthread_setspecific()`` may be called from a thread-specific data
destructor function. destructor function.
.. c:function:: void *pthread_getspecific(pthread_key_t key) .. c:function:: void *pthread_getspecific(pthread_key_t key)
The ``pthread_getspecific()`` function returns the value currently bound 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) .. c:function:: FAR char *getenv(const char *name)
Searches the environment list for a string that matches Searches the environment list for a string that matches
the string pointed to by ``name``. the string pointed to by ``name``.
:param name: The name of the variable to find. :param name: The name of the variable to find.
:return: :return:
The value of the variable (read-only) or NULL on failure. 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 :param string: ``name=value`` string describing the environment setting to
add/modify. add/modify.
:return: Zero on success. :return: Zero on success.
.. c:function:: int clearenv(void) .. 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]) .. c:function:: int pipe(int fd[2])
Creates a pair of file descriptors, pointing to a pipe inode, 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 :param fd: The user provided array in which to catch the pipe file
descriptors. ``fd[0]`` is for reading, ``fd[1]`` is for writing. 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); .. c:function:: int mkfifo(FAR const char *pathname, mode_t mode);
mkfifo() makes a FIFO device driver file with name pathname. Unlike Linux, 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 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 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. 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. until at least one thread has opened the FIFO for writing.
If all threads that write to the FIFO have closed, subsequent calls to 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). create (if not already created).
:param mode: Ignored for now :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) ``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); .. 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 :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 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 type: (see sys/socket.h)
:param protocol: (see sys/socket.h) :param protocol: (see sys/socket.h)
:return: :return:
0 on success; -1 on error with 0 on success; -1 on error with
``errno`` set appropriately: ``errno`` set appropriately:
@ -278,7 +278,7 @@ the following paragraphs.
.. c:function:: ssize_t recv(int sockfd, void *buf, size_t len, int flags); .. c:function:: ssize_t recv(int sockfd, void *buf, size_t len, int flags);
The ``recv()`` call is identical to The ``recv()`` call is identical to
```recvfrom()`` <#recvfrom>`__ with a NULL ``from`` parameter. ```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:`shmat`
- :c:func:`shmctl` - :c:func:`shmctl`
- :c:func:`shmdt` - :c:func:`shmdt`
Functions Functions
--------- ---------
@ -83,7 +83,7 @@ Functions
because user and group IDs are not yet supported by NuttX. because user and group IDs are not yet supported by NuttX.
.. c:function:: void *shmat(int shmid, FAR const void *shmaddr, int shmflg) .. c:function:: void *shmat(int shmid, FAR const void *shmaddr, int shmflg)
Attaches the shared memory Attaches the shared memory
segment associated with the shared memory identifier specified by segment associated with the shared memory identifier specified by
``shmid`` to the address space of the calling process. The segment is ``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 - ``EINVAL``. The value of ``shmaddr`` is not the data segment start
address of a shared memory segment. 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 :maxdepth: 1
:caption: Contents :caption: Contents
:glob: :glob:
*_* *_*
structures.rst 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 A pointer to the thread-specific ``errno`` value is available through a
function call: function call:
.. c:function:: int *__errno(void) .. c:function:: int *__errno(void)
``__errno()`` returns a pointer to the thread-specific ``__errno()`` returns a pointer to the thread-specific
``errno`` value. Note that the symbol ``errno`` is defined to be ``errno`` value. Note that the symbol ``errno`` is defined to be
``__errno()`` so that the usual access by referencing the symbol ``__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:: 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 :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 .. c:struct:: sched_param

2
Documentation/releases/index.rst
View file

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