You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@nuttx.apache.org by bt...@apache.org on 2020/08/24 17:30:11 UTC
[incubator-nuttx] branch master updated (0c59b3f -> 4076674)
This is an automated email from the ASF dual-hosted git repository.
btashton pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git.
from 0c59b3f nrf52832_sparkfun: recreate files from proper Apache sources
new 5e1dab3 sphinx doc
new 04d31a1 finished NX document migration
new 7102157 convert acronyms.txt to glossary.rst
new 6d89ae8 move last content from old docs to new docs; remove old docs
new 4276d62 rename doc/ -> Documentation/
new 6bcbbc3 backport watchdog API changes to new documentation (PRs: #1534 #1545 and #1565)
new 2fb9910 backport SocketCAN documentation to new docs (PR #1533)
new 4a38a15 convert TODOs to actual TODO banner and improve general presentation of different sections
new b3a269b fix link
new 76637cb complete improving presentation of sections
new 3f723a2 add basic documentation contributing guidelines
new d9be1df add basic support for multiple versions
new 8e56cf8 added hyperlinks to supported platforms page
new 911cc3f fix wrong "todo" placement
new 896ba15 support specifying top alignment for tables
new 1f53dd0 documentation: add license headers to various files
new 4076674 doc: fix typo on contribution workflow
The 17 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
.github/workflows/build.yml | 4 +
.github/workflows/check.yml | 2 +
.github/workflows/doc.yml | 28 +-
Documentation/.gitignore | 4 +-
Documentation/Makefile | 42 +
Documentation/NXGraphicsSubsystem.html | 4819 ---------
Documentation/NfsHowto.html | 385 -
Documentation/NuttShell.html | 6008 -----------
Documentation/NuttX.html | 7576 -------------
Documentation/NuttXBinfmt.html | 585 -
Documentation/NuttXCCodingStandard.html | 3127 ------
Documentation/NuttXDemandPaging.html | 672 --
Documentation/NuttXGettingStarted.html | 25 -
Documentation/NuttXNxFlat.html | 765 --
Documentation/NuttxPortingGuide.html | 7273 -------------
Documentation/NuttxUserGuide.html | 10600 -------------------
Documentation/NxWidgets.html | 76 -
Documentation/Pipfile | 14 +
Documentation/Pipfile.lock | 244 +
Documentation/README.html | 649 --
Documentation/UsbTrace.html | 453 -
Documentation/{ => _static}/NuttX.png | Bin
Documentation/{ => _static}/NuttX320.png | Bin
Documentation/_static/custom.css | 60 +
Documentation/_static/favicon.ico | Bin 0 -> 4286 bytes
Documentation/_templates/layout.html | 49 +
Documentation/acronyms.txt | 121 -
Documentation/applications/index.rst | 10 +
Documentation/backgd.gif | Bin 1097 -> 0 bytes
Documentation/boards/index.rst | 14 +
Documentation/components/binfmt.rst | 372 +
Documentation/components/drivers/index.rst | 941 ++
Documentation/components/filesystem.rst | 43 +
Documentation/components/index.rst | 20 +
Documentation/components/nsh/builtin.rst | 204 +
Documentation/components/nsh/commands.rst | 1692 +++
Documentation/components/nsh/config.rst | 486 +
Documentation/components/nsh/customizing.rst | 213 +
Documentation/components/nsh/index.rst | 19 +
Documentation/components/nsh/installation.rst | 187 +
Documentation/components/nsh/login.rst | 261 +
Documentation/components/nsh/nsh.rst | 361 +
Documentation/components/nxflat.rst | 469 +
.../{ => components/nxgraphics}/NXOrganization.gif | Bin
.../nxgraphics}/NuttXScreenShot.jpg | Bin
Documentation/components/nxgraphics/appendix.rst | 657 ++
Documentation/components/nxgraphics/index.rst | 174 +
Documentation/components/nxgraphics/nx.rst | 740 ++
Documentation/components/nxgraphics/nxcursor.rst | 50 +
Documentation/components/nxgraphics/nxfonts.rst | 127 +
Documentation/components/nxgraphics/nxgl.rst | 259 +
Documentation/components/nxgraphics/nxtk.rst | 653 ++
Documentation/components/nxgraphics/sample.rst | 30 +
Documentation/components/nxwidgets.rst | 59 +
Documentation/components/paging.rst | 423 +
Documentation/{ => components}/pm.png | Bin
Documentation/components/power.rst | 241 +
Documentation/components/socketcan.rst | 66 +
Documentation/components/syslog.rst | 511 +
Documentation/conf.py | 115 +
Documentation/contributing/coding_style.rst | 2656 +++++
Documentation/contributing/documentation.rst | 180 +
Documentation/contributing/index.rst | 13 +
Documentation/contributing/workflow.rst | 42 +
Documentation/favicon.ico | Bin 3126 -> 0 bytes
Documentation/glossary.rst | 368 +
Documentation/guides/index.rst | 9 +
Documentation/guides/nfs.rst | 285 +
Documentation/guides/usbtrace.rst | 214 +
Documentation/index.rst | 34 +
Documentation/introduction/about.rst | 285 +
Documentation/introduction/detailed_support.rst | 3191 ++++++
.../introduction/development_environments.rst | 155 +
Documentation/introduction/index.rst | 17 +
Documentation/introduction/licensing.rst | 11 +
Documentation/introduction/resources.rst | 23 +
Documentation/introduction/supported_platforms.rst | 349 +
Documentation/introduction/trademarks.rst | 32 +
Documentation/make.bat | 35 +
Documentation/quickstart/config_build.rst | 131 +
Documentation/quickstart/index.rst | 16 +
Documentation/quickstart/organization.rst | 501 +
Documentation/redirect.html | 20 -
Documentation/reference/index.rst | 14 +
Documentation/reference/os/addrenv.rst | 305 +
Documentation/reference/os/app_vs_os.rst | 103 +
Documentation/reference/os/arch.rst | 329 +
Documentation/reference/os/board.rst | 74 +
Documentation/reference/os/boardctl.rst | 40 +
Documentation/reference/os/conventions.rst | 101 +
Documentation/reference/os/index.rst | 25 +
Documentation/reference/os/iob.rst | 310 +
Documentation/reference/os/led.rst | 122 +
Documentation/reference/os/nuttx.rst | 50 +
Documentation/reference/os/paging.rst | 13 +
Documentation/reference/os/shm.rst | 38 +
Documentation/reference/os/smp.rst | 99 +
Documentation/reference/os/time_clock.rst | 593 ++
Documentation/reference/os/wqueue.rst | 307 +
Documentation/reference/user/01_task_control.rst | 887 ++
.../reference/user/02_task_scheduling.rst | 180 +
Documentation/reference/user/03_task_control.rst | 458 +
Documentation/reference/user/04_message_queue.rst | 375 +
.../reference/user/05_counting_semaphore.rst | 455 +
Documentation/reference/user/06_clocks_timers.rst | 360 +
Documentation/reference/user/07_signals.rst | 514 +
Documentation/reference/user/08_pthread.rst | 1710 +++
Documentation/reference/user/09_env_vars.rst | 95 +
Documentation/reference/user/10_filesystem.rst | 573 +
Documentation/reference/user/11_network.rst | 417 +
Documentation/reference/user/12_shared_memory.rst | 202 +
Documentation/reference/user/index.rst | 28 +
Documentation/reference/user/structures.rst | 168 +
Documentation/releases/index.rst | 6 +
Documentation/requirements.txt | 3 +
Documentation/style.css | 84 -
Documentation/substitutions.rst | 5 +
117 files changed, 27328 insertions(+), 43260 deletions(-)
create mode 100644 Documentation/Makefile
delete mode 100644 Documentation/NXGraphicsSubsystem.html
delete mode 100644 Documentation/NfsHowto.html
delete mode 100644 Documentation/NuttShell.html
delete mode 100644 Documentation/NuttX.html
delete mode 100644 Documentation/NuttXBinfmt.html
delete mode 100644 Documentation/NuttXCCodingStandard.html
delete mode 100644 Documentation/NuttXDemandPaging.html
delete mode 100644 Documentation/NuttXGettingStarted.html
delete mode 100644 Documentation/NuttXNxFlat.html
delete mode 100644 Documentation/NuttxPortingGuide.html
delete mode 100644 Documentation/NuttxUserGuide.html
delete mode 100644 Documentation/NxWidgets.html
create mode 100644 Documentation/Pipfile
create mode 100644 Documentation/Pipfile.lock
delete mode 100644 Documentation/README.html
delete mode 100644 Documentation/UsbTrace.html
rename Documentation/{ => _static}/NuttX.png (100%)
rename Documentation/{ => _static}/NuttX320.png (100%)
create mode 100644 Documentation/_static/custom.css
create mode 100644 Documentation/_static/favicon.ico
create mode 100644 Documentation/_templates/layout.html
delete mode 100644 Documentation/acronyms.txt
create mode 100644 Documentation/applications/index.rst
delete mode 100644 Documentation/backgd.gif
create mode 100644 Documentation/boards/index.rst
create mode 100644 Documentation/components/binfmt.rst
create mode 100644 Documentation/components/drivers/index.rst
create mode 100644 Documentation/components/filesystem.rst
create mode 100644 Documentation/components/index.rst
create mode 100644 Documentation/components/nsh/builtin.rst
create mode 100644 Documentation/components/nsh/commands.rst
create mode 100644 Documentation/components/nsh/config.rst
create mode 100644 Documentation/components/nsh/customizing.rst
create mode 100644 Documentation/components/nsh/index.rst
create mode 100644 Documentation/components/nsh/installation.rst
create mode 100644 Documentation/components/nsh/login.rst
create mode 100644 Documentation/components/nsh/nsh.rst
create mode 100644 Documentation/components/nxflat.rst
rename Documentation/{ => components/nxgraphics}/NXOrganization.gif (100%)
rename Documentation/{ => components/nxgraphics}/NuttXScreenShot.jpg (100%)
create mode 100644 Documentation/components/nxgraphics/appendix.rst
create mode 100644 Documentation/components/nxgraphics/index.rst
create mode 100644 Documentation/components/nxgraphics/nx.rst
create mode 100644 Documentation/components/nxgraphics/nxcursor.rst
create mode 100644 Documentation/components/nxgraphics/nxfonts.rst
create mode 100644 Documentation/components/nxgraphics/nxgl.rst
create mode 100644 Documentation/components/nxgraphics/nxtk.rst
create mode 100644 Documentation/components/nxgraphics/sample.rst
create mode 100644 Documentation/components/nxwidgets.rst
create mode 100644 Documentation/components/paging.rst
rename Documentation/{ => components}/pm.png (100%)
create mode 100644 Documentation/components/power.rst
create mode 100644 Documentation/components/socketcan.rst
create mode 100644 Documentation/components/syslog.rst
create mode 100644 Documentation/conf.py
create mode 100644 Documentation/contributing/coding_style.rst
create mode 100644 Documentation/contributing/documentation.rst
create mode 100644 Documentation/contributing/index.rst
create mode 100644 Documentation/contributing/workflow.rst
delete mode 100644 Documentation/favicon.ico
create mode 100644 Documentation/glossary.rst
create mode 100644 Documentation/guides/index.rst
create mode 100644 Documentation/guides/nfs.rst
create mode 100644 Documentation/guides/usbtrace.rst
create mode 100644 Documentation/index.rst
create mode 100644 Documentation/introduction/about.rst
create mode 100644 Documentation/introduction/detailed_support.rst
create mode 100644 Documentation/introduction/development_environments.rst
create mode 100644 Documentation/introduction/index.rst
create mode 100644 Documentation/introduction/licensing.rst
create mode 100644 Documentation/introduction/resources.rst
create mode 100644 Documentation/introduction/supported_platforms.rst
create mode 100644 Documentation/introduction/trademarks.rst
create mode 100644 Documentation/make.bat
create mode 100644 Documentation/quickstart/config_build.rst
create mode 100644 Documentation/quickstart/index.rst
create mode 100644 Documentation/quickstart/organization.rst
delete mode 100644 Documentation/redirect.html
create mode 100644 Documentation/reference/index.rst
create mode 100644 Documentation/reference/os/addrenv.rst
create mode 100644 Documentation/reference/os/app_vs_os.rst
create mode 100644 Documentation/reference/os/arch.rst
create mode 100644 Documentation/reference/os/board.rst
create mode 100644 Documentation/reference/os/boardctl.rst
create mode 100644 Documentation/reference/os/conventions.rst
create mode 100644 Documentation/reference/os/index.rst
create mode 100644 Documentation/reference/os/iob.rst
create mode 100644 Documentation/reference/os/led.rst
create mode 100644 Documentation/reference/os/nuttx.rst
create mode 100644 Documentation/reference/os/paging.rst
create mode 100644 Documentation/reference/os/shm.rst
create mode 100644 Documentation/reference/os/smp.rst
create mode 100644 Documentation/reference/os/time_clock.rst
create mode 100644 Documentation/reference/os/wqueue.rst
create mode 100644 Documentation/reference/user/01_task_control.rst
create mode 100644 Documentation/reference/user/02_task_scheduling.rst
create mode 100644 Documentation/reference/user/03_task_control.rst
create mode 100644 Documentation/reference/user/04_message_queue.rst
create mode 100644 Documentation/reference/user/05_counting_semaphore.rst
create mode 100644 Documentation/reference/user/06_clocks_timers.rst
create mode 100644 Documentation/reference/user/07_signals.rst
create mode 100644 Documentation/reference/user/08_pthread.rst
create mode 100644 Documentation/reference/user/09_env_vars.rst
create mode 100644 Documentation/reference/user/10_filesystem.rst
create mode 100644 Documentation/reference/user/11_network.rst
create mode 100644 Documentation/reference/user/12_shared_memory.rst
create mode 100644 Documentation/reference/user/index.rst
create mode 100644 Documentation/reference/user/structures.rst
create mode 100644 Documentation/releases/index.rst
create mode 100644 Documentation/requirements.txt
delete mode 100644 Documentation/style.css
create mode 100644 Documentation/substitutions.rst
[incubator-nuttx] 17/17: doc: fix typo on contribution workflow
Posted by bt...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
btashton pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
commit 407667480a99f40bb9c9158719705a3463e096cd
Author: Matias N <ma...@protobits.dev>
AuthorDate: Thu Aug 20 13:04:44 2020 -0300
doc: fix typo on contribution workflow
---
Documentation/contributing/workflow.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/contributing/workflow.rst b/Documentation/contributing/workflow.rst
index c90d16a..41bd934 100644
--- a/Documentation/contributing/workflow.rst
+++ b/Documentation/contributing/workflow.rst
@@ -9,7 +9,7 @@ will be reviewed and checked using Continuous Integration (CI) practices.
You should be aware of the following:
- All contributions must adhere to the :doc:`Coding Standard <coding_style>`. You can check your files using ``nxstyle``
- or complete patchsets using ``checkpath`` 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.
Note that not all existing files in the repository are already adapted to conform to the standard as this is an ongoing effort. Thus,
[incubator-nuttx] 16/17: documentation: add license headers to
various files
Posted by bt...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
btashton pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
commit 1f53dd0e0ed36700a08fd1315d558a791a920fcd
Author: Matias N <ma...@protobits.dev>
AuthorDate: Wed Aug 19 13:11:17 2020 -0300
documentation: add license headers to various files
---
Documentation/Makefile | 20 ++++++++++++++++++++
Documentation/_static/custom.css | 20 ++++++++++++++++++++
Documentation/_templates/layout.html | 19 +++++++++++++++++++
Documentation/conf.py | 20 ++++++++++++++++++++
4 files changed, 79 insertions(+)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 36feb34..77f9b94 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -1,3 +1,23 @@
+##############################################################################
+# Documentation/Makefile
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership. The
+# ASF licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance with the
+# License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+##############################################################################
+
# Minimal makefile for Sphinx documentation
#
diff --git a/Documentation/_static/custom.css b/Documentation/_static/custom.css
index 6a939f8..c37e164 100644
--- a/Documentation/_static/custom.css
+++ b/Documentation/_static/custom.css
@@ -1,3 +1,23 @@
+/****************************************************************************
+ * Documentation/_static/custom.css
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership. The
+ * ASF licenses this file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the
+ * License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ *
+ ****************************************************************************/
+
/* Make content wider */
.wy-nav-content {
diff --git a/Documentation/_templates/layout.html b/Documentation/_templates/layout.html
index 43342ff..2a3ebcd 100644
--- a/Documentation/_templates/layout.html
+++ b/Documentation/_templates/layout.html
@@ -1,3 +1,22 @@
+<!--
+ Documentation/_templates/layout.html
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership. The
+ ASF licenses this file to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance with the
+ License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ License for the specific language governing permissions and limitations
+ under the License.
+-->
+
{% extends "!layout.html" %}
{% block sidebartitle %}
{% if logo and theme_logo_only %}
diff --git a/Documentation/conf.py b/Documentation/conf.py
index ab828e6..0c05044 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -1,3 +1,23 @@
+##############################################################################
+# Documentation/conf.py
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership. The
+# ASF licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance with the
+# License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+##############################################################################
+
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
[incubator-nuttx] 13/17: added hyperlinks to supported platforms
page
Posted by bt...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
btashton pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
commit 8e56cf8d922ba88d81d3dbc3b6eda57624b941bc
Author: Adam Feuer <ad...@adamfeuer.com>
AuthorDate: Sun Aug 16 19:12:36 2020 -0700
added hyperlinks to supported platforms page
- and fixed formatting in detailed support to
enable hyperlinks to section headers
Squashed commit of the following:
commit 59e31d2ac13255f35f21d49c407494af23f16f6e
Author: Adam Feuer <ad...@adamfeuer.com>
Date: Sun Aug 16 19:01:58 2020 -0700
removed formatting |br|s, will use css
- to line up columns
commit bcee59a14180bad6823e82990be52bc626e85911
Author: Adam Feuer <ad...@adamfeuer.com>
Date: Sun Aug 16 18:55:57 2020 -0700
remove migration not complete message
commit bc23b19ef65bdc13f3df04aae1693c61aa4abe04
Author: Adam Feuer <ad...@adamfeuer.com>
Date: Sun Aug 16 18:16:07 2020 -0700
table formatting adjustments
commit c6fdc907825a31218d2bdcbe1c1079e197779f02
Author: Adam Feuer <ad...@adamfeuer.com>
Date: Sun Aug 16 16:03:07 2020 -0700
fixing table formatting
commit c84d5e41a553e7a108b23d610e71f41ff6f5b751
Author: Adam Feuer <ad...@adamfeuer.com>
Date: Sun Aug 16 15:35:16 2020 -0700
trying to fix table formatting
commit 0d036dd2f309ad93f31a43c7f668befb6032c458
Author: Adam Feuer <ad...@adamfeuer.com>
Date: Sun Aug 16 15:28:02 2020 -0700
hyperlinks for supported boards for TI
commit e30840123f6ec2e7edb8335a165f9527919fefcc
Author: Adam Feuer <ad...@adamfeuer.com>
Date: Sun Aug 16 15:13:40 2020 -0700
links for supported boards by manufacturer - STM32
commit 7b5faf61901fc0fc3b945dbda4697a2d3f266126
Author: Adam Feuer <ad...@adamfeuer.com>
Date: Sun Aug 16 14:13:18 2020 -0700
supported boards by manufacturer hyperlinks nxp
- nxp/freescale
commit 34c5c9b15908ffea7f8467c709fd0a5379e950ae
Author: Adam Feuer <ad...@adamfeuer.com>
Date: Sun Aug 16 13:52:18 2020 -0700
hyperlinks for supported boards by manufacturer
- up to atmel
commit 351718d5edbb7b736067cfcb74270992fcc55102
Author: Adam Feuer <ad...@adamfeuer.com>
Date: Sat Aug 15 20:57:38 2020 -0700
add hyperlinks for supported platforms by cpu core
---
Documentation/introduction/detailed_support.rst | 1230 +++++++-------------
Documentation/introduction/supported_platforms.rst | 534 ++++-----
2 files changed, 669 insertions(+), 1095 deletions(-)
diff --git a/Documentation/introduction/detailed_support.rst b/Documentation/introduction/detailed_support.rst
index a005d2d..65d06ba 100644
--- a/Documentation/introduction/detailed_support.rst
+++ b/Documentation/introduction/detailed_support.rst
@@ -1,7 +1,3 @@
-.. todo::
- Migration is not yet completed from previous documentation. You can find the original list here:
- `here <https://cwiki.apache.org/confluence/display/NUTTX/About>`__
-
=========================
Detailed Platform Support
=========================
@@ -11,89 +7,78 @@ information see the *README* files that can be found
`here <README.html>`__.
-
-Linux User Mode.
-
-|
+Linux User Mode Simulation
+==========================
A user-mode port of NuttX to the x86 Linux/Cygwin platform is available.
The purpose of this port is primarily to support OS feature development.
+ARM7TDMI
+========
+TI TMS320-C5471
+---------------
-ARM7TDMI.
+(also called **C5471** or **TMS320DA180** or **DA180**)
-|
-
-TI TMS320C5471 (also called **C5471** or **TMS320DA180** or **DA180**).
NuttX operates on the ARM7 of this dual core processor. This port uses
the `Spectrum Digital <http://www.spectrumdigital.com/>`__ evaluation
board with a GNU arm-nuttx-elf toolchain\* under Linux or Cygwin.
-|
-
---------------
-
-|
+NXP LPC214x
+-----------
-NXP LPC214x. Support is provided for the NXP LPC214x family of
+Support is provided for the NXP LPC214x family of
processors. In particular, support is provided for (1) the mcu123.com
lpc214x evaluation board (LPC2148) and (1) the The0.net ZPA213X/4XPA
development board (with the The0.net UG-2864AMBAG01 OLED) This port also
used the GNU arm-nuttx-elf toolchain\* under Linux or Cygwin.
-|
-
---------------
-
-|
+NXP LPC2378
+-----------
-NXP LPC2378. Support is provided for the NXP LPC2378 MCU. In particular,
+Support is provided for the NXP LPC2378 MCU. In particular,
support is provided for the Olimex-LPC2378 development board. This port
was contributed by Rommel Marcelo is was first released in NuttX-5.3.
This port also used the GNU arm-nuttx-elf toolchain\* under Linux or
Cygwin.
-|
-
+STMicro STR71x
--------------
-|
-
-STMicro STR71x. Support is provided for the STMicro STR71x family of
+Support is provided for the STMicro STR71x family of
processors. In particular, support is provided for the Olimex STR-P711
evaluation board. This port also used the GNU arm-nuttx-elf toolchain\*
under Linux or Cygwin.
+ARM920T
+=======
+NXP/Freescale i.MX1
+-------------------
-ARM920T.
-
-|
-
-Freescale MC9328MX1 or i.MX1. This port uses the Freescale MX1ADS
+Or MC9328MX1 – This port uses the Freescale MX1ADS
development board with a GNU arm-nuttx-elf toolchain\* under either
Linux or Cygwin.
+ARM926EJS
+=========
+TI TMS320-DM320
+---------------
-ARM926EJS.
-
-|
+(also called **DM320**)
-TI TMS320DM320 (also called **DM320**). NuttX operates on the ARM9 of
+NuttX operates on the ARM9 of
this dual core processor. This port uses the `Neuros
OSD <http://wiki.neurostechnology.com/index.php/Developer_Welcome>`__
with a GNU arm-nuttx-elf toolchain\* under Linux or Cygwin. The port was
performed using the OSD v1.0, development board.
-|
-
---------------
-
-|
+NXP LPC3131
+-----------
-NXP LPC3131. Two boards based on the NXP LPC3131 are supported:
+Two boards based on the NXP LPC3131 are supported:
- First, a port for the NXP
`LPC3131 <http://ics.nxp.com/products/lpc3000/lpc313x.lpc314x.lpc315x/>`__
@@ -108,36 +93,34 @@ NXP LPC3131. Two boards based on the NXP LPC3131 are supported:
LPC-H3131 <https://www.olimex.com/Products/ARM/NXP/LPC-H3131/>`__
development board was added in NuttX-6.32.
-|
+NXP LPC315x
+-----------
---------------
-
-|
-
-NXP LPC315x. Support for the NXP
+Support for the NXP
`LPC315x <http://ics.nxp.com/products/lpc3000/lpc313x.lpc314x.lpc315x/>`__
family has been incorporated into the code base as of NuttX-6.4. Support
was added for the Embedded Artists EA3152 board in NuttX-6.11.
+Other ARMv4
+===========
-Other ARMv4.
+Moxa NP51x0
+-----------
-|
-
-MoxaRT A port to the Moxa NP51x0 series of 2-port advanced
+A port to the Moxa NP51x0 series of 2-port advanced
RS-232/422/485 serial device servers was contributed by Anton D.
Kachalov in NuttX-7.11. This port includes a NuttShell (NSH)
configuration with support for the Faraday FTMAC100 Ethernet MAC Driver.
+ARM1176JZ
+=========
-ARM1176JZ.
-
-|
+Broadcom BCM2708
+----------------
-Broadcom BCM2708. Very basic support for the Broadcom BCM2708 was
-released with NuttX-7.23.
+Very basic support for the Broadcom BCM2708 was released with NuttX-7.23.
Raspberry Pi Zero. This support was provided for the Raspberry Pi Zero
which is based on the BCM2835. Basic logic is in place but the port is
@@ -153,23 +136,20 @@ found in the *Obsoleted* repository.
-ARM Cortex-A5.
-
-|
+ARM Cortex-A5
+=============
-Atmel SAMA5D2.
+Atmel SAMA5D2
+-------------
- **Atmel SAMA5D2 Xplained Ultra development board**. This is the port
of NuttX to the Atmel SAMA5D2 Xplained Ultra development board. This
board features the Atmel SAMA5D27 microprocessor.
-|
+Atmel SAMA5D3
+-------------
---------------
-
-|
-
-Atmel SAMA5D3. There are ports to two Atmel SAMA5D3 boards:
+There are ports to two Atmel SAMA5D3 boards:
- **Atmel SAMA5D3\ x-EK development boards**. This is the port of NuttX
to the Atmel SAMA5D3\ *x*-EK development boards (where *x*\ =1,3,4,
@@ -279,13 +259,10 @@ Refer to the NuttX board
`README <https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/sama5/sama5d3-xplained/README.txt>`__
file for further information.
-|
-
---------------
-
-|
+Atmel SAMA5D4
+-------------
-Atmel SAMA5D4. There is a port in progress on one Atmel SAMA5D4 board:
+There is a port in progress on one Atmel SAMA5D4 board:
- **Atmel SAMA5D4-EK/MB development boards** This is the port of NuttX
to the Atmel SAMA5D4-MB Rev C. development board (which should be
@@ -307,12 +284,6 @@ Atmel SAMA5D4. There is a port in progress on one Atmel SAMA5D4 board:
`README <https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/sama5/sama5d4-ek/README.txt>`__
file for current status.
-|
-
---------------
-
-|
-
**Development Environments:** 1) Linux with native Linux GNU toolchain,
2) Cygwin/MSYS with Cygwin GNU toolchain, 3) Cygwin/MSYS with Windows
native toolchain, or 4) Native Windows. All testing has been performed
@@ -320,12 +291,13 @@ with the CodeSourcery toolchain (GCC version 4.7.3) in the Cygwin
environment under Windows.
+ARM Cortex-A8
+=============
-ARM Cortex-A8.
-
-|
+Allwinner A10
+-------------
-Allwinner A10. These following boards are based on the Allwinner A10
+These following boards are based on the Allwinner A10
have are supported by NuttX:
- **pcDuino v1**. A port of NuttX to the pcDuino v1 board was first
@@ -345,13 +317,10 @@ have are supported by NuttX:
basis for a more extensive development. There is, at present, no work
in progress to extend this port, however.
-|
+TI/Sitara AM335x
+----------------
---------------
-
-|
-
-TI/Sitara AM335x. These following boards are based on the TI/Sitara
+These following boards are based on the TI/Sitara
AM335x are supported by NuttX:
- **Beaglebone Black**. A port of NuttX to the Beaglebone Black board
@@ -372,14 +341,13 @@ AM335x are supported by NuttX:
`README <https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/am335x/beaglebone-black/README.txt>`__
file for further, up-to-date information.
+ARM Cortex-A9
+=============
+NXP/Freescale i.MX6
+-------------------
-ARM Cortex-A9.
-
-|
-
-NXP/Freescale i.MX6. The basic port has been completed for the following
-i.MX6 board
+The basic port has been completed for the following i.MX6 board:
- **Sabre-6Quad**. This is a port to the NXP/Freescale Sabre-6Quad
board. Refer to the NuttX board
@@ -400,27 +368,32 @@ i.MX6 board
-ARM Cortex-R4.
+ARM Cortex-R4
+=============
-|
+TI/Hercules TMS570LS04xx
+------------------------
-TI/Hercules TMS570LS04xx. A port is available for the Texas Instruments
+A port is available for the Texas Instruments
Hercules TMS570LS04x/03x LaunchPad Evaluation Kit (*LAUNCHXL-TMS57004*)
featuring the Hercules TMS570LS0432PZ chip.
-|
+TI/Hercules TMS570LS31xx
+------------------------
-TI/Hercules TMS570LS31xx. Architecture support for the TMS570LS3137ZWT
+Architecture support for the TMS570LS3137ZWT
part was added in NuttX 7.25 by Ivan Ucherdzhiev. Ivan also added
support for the TI Hercules TMS570LS31x USB Kit.
-ARM Cortex-M0/M0+.
+ARM Cortex-M0/M0+
+=================
-|
+nuvoTon NUC120
+--------------
-nuvoTon NUC120. This is a port of NuttX to the nuvoTon NuTiny-SDK-NUC120
+This is a port of NuttX to the nuvoTon NuTiny-SDK-NUC120
that features the NUC120LE3AN MCU.
**STATUS**. Initial support for the NUC120 was released in NuttX-6.26.
@@ -457,13 +430,10 @@ Cygwin is provided by the NuttX
`buildroot <https://bitbucket.org/nuttx/buildroot/downloads/>`__
package.
-|
+NXP/FreeScale KL25Z
+-------------------
---------------
-
-|
-
-FreeScale KL25Z. There are two board ports for the KL25Z parts:
+There are two board ports for the KL25Z parts:
**Freedom KL25Z**. This is a port of NuttX to the Freedom KL25Z board
that features the MKL25Z128 Cortex-M0+ MCU, 128KB of FLASH and 16KB of
@@ -478,35 +448,26 @@ comes with a USB based bootloader. See the
`Freescale <http://www.freescale.com/webapp/sps/site/prod_summary.jsp?code=FRDM-KL25Z&tid=vanFRDM-KL25Z>`__
website for further information about this board.
-|
-
---------------
-
-|
+NXP/FreeScale KL26Z
+-------------------
-FreeScale Freedom KL26Z. This is a port of NuttX to the Freedom KL25Z
+This is a port of NuttX to the Freedom KL25Z
board that features the MK26Z128VLH4 Cortex-M0+ MCU, 128KB of FLASH and
16KB of SRAM. See the
`Freescale <http://www.freescale.com/webapp/sps/site/prod_summary.jsp?code=FRDM-KL26Z&tid=vanFRDM-KL26Z>`__
website for further information about this board.
-|
+Atmel SAMD20
+------------
---------------
-
-|
-
-Atmel SAMD20. The port of NuttX to the Atmel SAMD20-Xplained Pro
+The port of NuttX to the Atmel SAMD20-Xplained Pro
development board. This board features the ATSAMD20J18A MCU (Cortex-M0+
with 256KB of FLASH and 32KB of SRAM).
-|
-
---------------
-
-|
+Atmel SAMD21
+------------
-Atmel SAMD21. There two boards supported for the SAMD21:
+There two boards supported for the SAMD21:
#. The port of NuttX to the Atmel SAMD21-Xplained Pro development board
added in NuttX-7.11, and
@@ -514,52 +475,40 @@ Atmel SAMD21. There two boards supported for the SAMD21:
Assis in NuttX-8.2. The initial release included *nsh* and *usbnsh*
configurations.
-|
+Atmel SAML21
+------------
---------------
-
-|
-
-Atmel SAML21. The port of NuttX to the Atmel SAML21-Xplained Pro
+The port of NuttX to the Atmel SAML21-Xplained Pro
development board. This board features the ATSAML21J18A MCU (Cortex-M0+
with 256KB of FLASH and 32KB of SRAM).
-|
-
---------------
-
-|
+NXP LPC11xx
+-----------
-NXP LPC11xx. Support is provided for the NXP LPC11xx family of
+Support is provided for the NXP LPC11xx family of
processors. In particular, support is provided for LPCXpresso LPC1115
board. This port was contributed by Alan Carvalho de Assis.
-|
+NXP S32K11x
+-----------
---------------
-
-|
-
-NXP S32K11x. Support is provided for the NXP S32K11x family of
+Support is provided for the NXP S32K11x family of
processors and, in particular, the S32K118EVB development board.
+ARM Cortex-M3
+=============
+TI/Stellaris LM3S6432
+---------------------
-ARM Cortex-M3.
-
-|
-
-TI/Stellaris LM3S6432. This is a port of NuttX to the Stellaris RDK-S2E
+This is a port of NuttX to the Stellaris RDK-S2E
Reference Design Kit and the MDL-S2E Ethernet to Serial module
(contributed by Mike Smith).
-|
-
---------------
-
-|
+TI/Stellaris LM3S6432S2E
+------------------------
-TI/Stellaris LM3S6432S2E. This port uses Serial-to-Ethernet Reference
+This port uses Serial-to-Ethernet Reference
Design Kit (`RDK-S2E <http://www.ti.com/tool/rdk-s2e>`__) and has
similar support as for the other Stellaris family members. A
configuration is available for the NuttShell (NSH) (see the `NSH User
@@ -567,13 +516,10 @@ Guide <http://www.nuttx.org/Documentation/NuttShell.html>`__). The NSH
configuration including networking support with a Telnet NSH console.
This port was contributed by Mike Smith.
-|
-
---------------
-
-|
+TI/Stellaris LM3S6918
+---------------------
-TI/Stellaris LM3S6918. This port uses the
+This port uses the
`Micromint <%20http://www.micromint.com/>`__ Eagle-100 development board
with a GNU arm-nuttx-elf toolchain\* under either Linux or Cygwin.
@@ -584,68 +530,50 @@ DIY toolchain for Linux or Cygwin is provided by the NuttX
`buildroot <https://bitbucket.org/nuttx/buildroot/downloads/>`__
package.
-|
+TI/Stellaris LM3S6965
+---------------------
---------------
-
-|
-
-TI/Stellaris LM3S6965. This port uses the Stellaris LM3S6965 Ethernet
+This port uses the Stellaris LM3S6965 Ethernet
Evaluation Kit with a GNU arm-nuttx-elf toolchain\* under either Linux
or Cygwin.
**Development Environments:** See the Eagle-100 LM3S6918 above.
-|
-
---------------
-
-|
+TI/Stellaris LM3S8962
+---------------------
-TI/Stellaris LM3S8962. This port uses the Stellaris EKC-LM3S8962
+This port uses the Stellaris EKC-LM3S8962
Ethernet+CAN Evaluation Kit with a GNU arm-nuttx-elf toolchain\* under
either Linux or Cygwin. Contributed by Larry Arnold.
-|
-
---------------
-
-|
+TI/Stellaris LM3S9B92
+---------------------
-TI/Stellaris LM3S9B92. Architectural support for the LM3S9B92 was
+Architectural support for the LM3S9B92 was
contributed by Lwazi Dube in NuttX 7.28. No board support for boards
using the LM3S9B92 are currently available.
-|
-
---------------
-
-|
+TI/Stellaris LM3S9B96
+---------------------
-TI/Stellaris LM3S9B96. Header file support was contributed by Tiago
+Header file support was contributed by Tiago
Maluta for this part. Jose Pablo Rojas V. is used those header file
changes to port NuttX to the TI/Stellaris EKK-LM3S9B96. That port was
available in the NuttX-6.20 release. Refer to the NuttX board
`README <https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/tiva/ekk-lm3s9b96/README.txt>`__
file for further information.
-|
+TI/SimpleLink CC13x0
+--------------------
---------------
-
-|
-
-TI/SimpleLink CC13x0. Basic, unverified architectural support for the
+Basic, unverified architectural support for the
CC13x0 was added in NuttX-7.28. This is a work in progress and, with any
luck, a fully verified port will be available in NuttX-7.29.
-|
-
---------------
-
-|
+SiLabs EFM32 Gecko
+------------------
-SiLabs EFM32 Gecko. This is a port for the Silicon Laboratories' EFM32
+This is a port for the Silicon Laboratories' EFM32
*Gecko* family. Board support is available for the following:
#. **SiLabs EFM32 Gecko Starter Kit (EFM32-G8XX-STK)**. The Gecko
@@ -693,13 +621,10 @@ SiLabs EFM32 Gecko. This is a port for the Silicon Laboratories' EFM32
`README.txt <https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/efm32/olimex-efm32g880f129-stk/README.txt>`__
for further information.
-|
+SiLabs EFM32 Giant Gecko
+------------------------
---------------
-
-|
-
-SiLabs EFM32 Giant Gecko. This is a port for the Silicon Laboratories'
+This is a port for the Silicon Laboratories'
EFM32 *Giant Gecko* family. This board features the EFM32GG990F1024 MCU
with 1 MB flash and 128 kB RAM.
@@ -735,13 +660,10 @@ Board support is available for the following:
- Reset Management Unit (RMU) was added Pierre-noel Bouteville in
NuttX-7.7.
-|
-
---------------
-
-|
+STMicro STM32 L152
+------------------
-STMicro STM32L152 (STM32L "EnergyLite" Line). Two boards are supported:
+(STM32L "EnergyLite" Line). Two boards are supported:
- STM32L-Discovery. This is a port of NuttX to the STMicro
STM32L-Discovery development board. The STM32L-Discovery board is
@@ -798,26 +720,20 @@ SRAM usage at run-time can be shown with the NSH ``free`` command:
You can see that 9.9KB (62%) of SRAM heap is still available for further
application development while NSH is running.
-|
+STMicro STM32 L15x/16x
+----------------------
---------------
-
-|
-
-STMicro STM32L152x/162x (STM32 L1 "EnergyLite" Medium+ Density Family).
+(STM32 L1 "EnergyLite" Medium+ Density Family).
Support for the STM32L152 and STM32L162 Medium+ density parts from Jussi
Kivilinna and Sami Pelkonen was included in NuttX-7.3, extending the
basic STM32L152x support. This is *architecture-only* support, meaning
that support for the boards with these chips is available, but no
support for any publicly available boards is included.
-|
-
---------------
-
-|
+STMicro STM32 F0xx
+------------------
-STMicro STM32F0xx (STM32 F0, ARM Cortex-M0). Support for the STM32 F0
+(STM32 F0, ARM Cortex-M0). Support for the STM32 F0
family was contributed by Alan Carvalho de Assis in NuttX-7.21. There
are ports to three different boards in this repository:
@@ -830,18 +746,20 @@ are ports to three different boards in this repository:
- **Nucleo-F091RC** With 32KB of SRAM the STM32 F091RC this board is a
great match for NuttX. Contributed by Juha Niskanen in NuttX-7.21.
-|
+STMicro STM32 L0xx
+------------------
-STMicro STM32L0xx (STM32 L0, ARM Cortex-M0). Support for the STM32 FL
+(STM32 L0, ARM Cortex-M0). Support for the STM32 FL
family was contributed by Mateusz Sfafoni in NuttX-7.28. There are ports
to two different STM32 L0 boards in the repository:
-- **B-L072Z-LRWAN1** Contributed byMateusz Sfafoni in NuttX-7.28.
-- **Nucleo-L073RZ** Contributed byMateusz Sfafoni in NuttX-7.28.
+ **B-L072Z-LRWAN1** Contributed byMateusz Sfafoni in NuttX-7.28.
+ **Nucleo-L073RZ** Contributed byMateusz Sfafoni in NuttX-7.28.
-|
+STMicro STM32 G0xx
+------------------
-STMicro STM32G0xx (STM32 G0, ARM Cortex-M0+). Support for the STM32 FL
+(STM32 G0, ARM Cortex-M0+). Support for the STM32 FL
family was contributed by Mateusz Sfafoni in NuttX-7.28. There are ports
to two different STM32 L0 boards in the repository:
@@ -854,7 +772,6 @@ to two different STM32 L0 boards in the repository:
`README <https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32f0l0g0/nucleo-g070rb/README.txt>`__
file for further information.
-|
**STATUS:** Status for the STM32F0xx, STM32L0xx, and STM32G0xx is shown
together since these parts share many drivers in common.
@@ -877,13 +794,10 @@ Volpato.
**NuttX-9.0** Added I2C support for F0, L0 and G0.
-|
+STMicro STM32 F100x
+-------------------
---------------
-
-|
-
-STMicro STM32F100x (STM32 F1 "Value Line"Family).
+(STM32 F1 "Value Line"Family).
- **Proprietary Boards** Chip support for these STM32 "Value Line"
family was contributed by Mike Smith and users have reported that
@@ -897,22 +811,16 @@ STMicro STM32F100x (STM32 F1 "Value Line"Family).
`README <https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/stm32vldiscovery/README.txt>`__
file for further information.
-|
-
---------------
-
-|
+STMicro STM32 F102x
+-------------------
-STMicro STM32F102. Architecture support (only) for the STM32 F102 family
+Architecture support (only) for the STM32 F102 family
was contributed by the PX4 team in NuttX-7.7.
-|
+STMicro STM32 F103C4/C8
+-----------------------
---------------
-
-|
-
-STMicro STM32F103C4/8 (STM32 F1 Low- and Medium-Density Family). There
+(STM32 F1 Low- and Medium-Density Family). There
are two ports available for this family:
- One port is for "STM32 Tiny" development board. This board is
@@ -927,13 +835,10 @@ are two ports available for this family:
**STATUS:**
-|
-
---------------
-
-|
+STMicro STM32 F103x
+-------------------
-STMicro STM32F103x (STM32 F1 Family). Support for five board
+(STM32 F1 Family). Support for five board
configurations are available. MCU support includes all of the high
density and connectivity line families. Board supported is available
specifically for: STM32F103ZET6, STM32F103RET6, STM32F103VCT,
@@ -1018,23 +923,17 @@ Windows. A DIY toolchain or Linux or Cygwin is provided by the NuttX
`buildroot <https://bitbucket.org/nuttx/buildroot/downloads/>`__
package.
-|
+STMicro STM32 F105x
+-------------------
---------------
-
-|
-
-STMicro STM32F105x. Architecture support (only) for the STM32 F105R was
+Architecture support (only) for the STM32 F105R was
contribed in NuttX-7.17 by Konstantin Berezenko. There is currently no
support for boards using any STM32F105x parts in the source tree.
-|
-
---------------
-
-|
+STMicro STM32 F107x
+-------------------
-STMicro STM32F107x (STM32 F1 "Connectivity Line" family). Chip support
+(STM32 F1 "Connectivity Line" family). Chip support
for the STM32 F1 "Connectivity Line" family has been present in NuttX
for some time and users have reported that they have successful brought
up NuttX on their proprietary boards using this logic.
@@ -1087,13 +986,10 @@ STMicro STM32F107VC MCU.
**STATUS:** A configuration for the NuttShell (NSH), NSH with
networking, and NSH with USB host are available and verified.
-|
+STMicro STM32 F205x
+-------------------
---------------
-
-|
-
-STMicro STM32F205 (STM32 F2 family). Architecture only support for the
+(STM32 F2 family). Architecture only support for the
STM32F205RG was contributed as an anonymous contribution in NuttX-7.10.
**Particle.io Phone**. Support for the Particle.io Photon board was
@@ -1110,13 +1006,10 @@ configurations. See the Photon
`README <https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/photon/README.txt>`__
file for additional information.
-|
-
---------------
-
-|
+STMicro STM32 F207x
+-------------------
-STMicro STM32F207 (STM32 F2 family).
+(STM32 F2 family)
- Support for the STMicro STM3220G-EVAL development board was
contributed by Gary Teravskis and first released in NuttX-6.16. This
@@ -1127,13 +1020,10 @@ STMicro STM32F207 (STM32 F2 family).
Szafoni in NuttX-7.28. Available configurations include NSH, ADC, and
PWM.
-|
+Atmel SAM3U
+-----------
---------------
-
-|
-
-Atmel SAM3U. This port uses the `Atmel <http://www.atmel.com/>`__
+This port uses the `Atmel <http://www.atmel.com/>`__
SAM3U-EK development board that features the SAM3U4E MCU. This port uses
a GNU arm-nuttx-elf or arm-nuttx-eabi toolchain\* under either Linux or
Cygwin (with native Windows GNU tools or Cygwin-based GNU tools).
@@ -1145,13 +1035,10 @@ DIY toolchain for inux or Cygwin is provided by the NuttX
`buildroot <https://bitbucket.org/nuttx/buildroot/downloads/>`__
package.
-|
-
---------------
-
-|
+Atmel SAM3X
+-----------
-Atmel SAM3X. There are two SAM3X boards supported:
+There are two SAM3X boards supported:
#. The `Arduino <http://arduino.cc//>`__ Due development board that
features the ATSAM3X8E MCU running at 84MHz. See the `Arduino
@@ -1165,11 +1052,8 @@ Atmel SAM3X. There are two SAM3X boards supported:
**Development Environments:** See the Atmel SAM3U discussion
`above. <#at91sam3u>`__
-|
-
---------------
-
-|
+NXP LPC176x
+-----------
NXP LPC1766, LPC1768, and LPC1769. Drivers are available for CAN, DAC,
Ethernet, GPIO, GPIO interrupts, I2C, UARTs, SPI, SSP, USB host, and USB
@@ -1328,25 +1212,19 @@ Windows. A DIY toolchain for Linux or Cygwin is provided by the NuttX
`buildroot <https://bitbucket.org/nuttx/buildroot/downloads/>`__
package.
-|
-
---------------
-
-|
+NXP LPC178x
+-----------
-NXP LPC1788. The port of NuttX to the WaveShare Open1788 is a
+The port of NuttX to the WaveShare Open1788 is a
collaborative effort between Rommel Marcelo and myself (with Rommel
being the leading contributor and I claiming only a support role). You
can get more information at the Open1788 board from the WaveShare
`website <http://www.wvshare.com/product/Open1788-Standard.htm>`__.
-|
+ON Semiconductor LC823450
+-------------------------
---------------
-
-|
-
-ON Semiconductor LC823450 (Dual core ARM Cortex-M3). In NuttX-7.22,
+(Dual core ARM Cortex-M3). In NuttX-7.22,
Masayuki Ishikawa contributed support for both the LC823450 architecture
and for ON Semiconductor's **LC823450XGEVK board**:
@@ -1383,15 +1261,11 @@ Masayuki Ishikawa in NuttX-7.23. Bluetooth, SPI, and *PROTECTED* build
support were added by Masayuki Ishikawa in NuttX-7.26. Support for for
SPI flash boot was added in NuttX-7.28.
-|
-
---------------
+Maxim Integrated MAX32660
+-------------------------
-|
-
-Maxim Integrated MAX36600. Architectural upport for the MAX32660 was
-added (along with partial support for other members of the MAX326xx
-family) in NuttX 7.28.
+Architectural upport for the MAX32660 was added (along with partial
+support for other members of the MAX326xx family) in NuttX 7.28.
**MAX32660-EVSYS**. Basic support for the Maxim Integrated MAC3X660
EVSYS was included in the NuttX-7.28 release. A basic NSH configuration
@@ -1404,15 +1278,16 @@ SPI0-based SD card.
-ARM Cortex-M4.
+ARM Cortex-M4
+=============
-|
+Infineon XMC45xx
+----------------
-Infineon XMC45xx. An initial but still incomplete port to the XMC4500
-Relax board was released with NuttX-7.21 (although it was not really
-ready for prime time). Basic NSH functionality was a serial console was
-added by Alan Carvahlo de Assis in NuttX-7.23. Alan also added an SPI
-driver in NuttX-7.25.
+An initial but still incomplete port to the XMC4500 Relax board was released
+with NuttX-7.21 (although it was not really ready for prime time). Basic NSH
+functionality was a serial console was added by Alan Carvahlo de Assis in
+NuttX-7.23. Alan also added an SPI driver in NuttX-7.25.
This initial porting effort uses the Infineon XMC4500 Relax v1 board as
described on the manufacturer's
@@ -1421,13 +1296,10 @@ The current status of the board is available in the board
`README <https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/xmc4/xmc4500-relax/README.txt>`__
file
-|
-
---------------
-
-|
+Nordic Semiconductor NRF52xxx
+-----------------------------
-Nordic Semiconductor/NRF52xxx. Initial architecture support of the NRF52
+Initial architecture support of the NRF52
including UART, Timer, and GPIOs was contributed by Janne Rosberg in
NuttX-7.25. Janne also contributed board support for the NRF52-PCA10040
development board at that time.
@@ -1445,24 +1317,18 @@ Available drivers include:
- **NuttX-7.29**. Support for the 52804 family and an RNG drivers was
added by Levin Li.
-|
-
---------------
-
-|
+NXP/FreeScale Kinetis K20
+-------------------------
-NXP/FreeScale Kinetis K20/Teensy-3.x. Architecture support (only) was
+Used by Teensy-3.x. Architecture support (only) was
added in NuttX-7.10. This support was taken from PX4 and is the work of
Jakob Odersky. Support was added for the PJRC Teensy-3.1 board in
NuttX-7.11. Backward compatible support for the Teensy-3.0 is included.
-|
-
---------------
-
-|
+NXP/FreeScale Kinetis K28F
+--------------------------
-NXP/FreeScale Kinetis K28F/Freedom-K28F. Architecture support for the
+Use by Freedom-K28F. Architecture support for the
Kinetis K28F along with board support for the Freedom-K28F was added in
NuttX-7.15. The Freedom-K28F board is based on the Kinetis
MK28FN2M0VMI15 MCU (ARM Cortex-M4 at150 MHz, 1 MB SRAM, 2 MB flash, HS
@@ -1470,25 +1336,19 @@ and FS USB, 169 MAPBGA package). More information is available from the
`NXP
website <https://www.nxp.com/support/developer-resources/hardware-development-tools/freedom-development-boards/mcu-boards/nxp-freedom-development-board-for-kinetis-k27-and-k28-mcus:FRDM-K28F>`__.
-|
-
---------------
+NXP/FreeScale Kinetis K40
+-------------------------
-|
-
-NXP/FreeScale Kinetis K40. This port uses the Freescale Kinetis KwikStik
+This port uses the Freescale Kinetis KwikStik
K40. Refer to the `Freescale web
site <http://www.freescale.com/webapp/sps/site/prod_summary.jsp?code=KWIKSTIK-K40>`__
for further information about this board. The Kwikstik is used with the
FreeScale Tower System (mostly just to provide a simple UART connection)
-|
-
---------------
-
-|
+NXP/FreeScale Kinetis K60
+-------------------------
-NXP/FreeScale Kinetis K60. This port uses the **Freescale Kinetis
+This port uses the **Freescale Kinetis
TWR-K60N512** tower system. Refer to the `Freescale web
site <http://www.freescale.com/webapp/sps/site/prod_summary.jsp?code=TWR-K60N512-KIT>`__
for further information about this board. The TWR-K60N51 includes with
@@ -1498,13 +1358,10 @@ UART connection.
**MK60N512VLL100**. Architecture support for the MK60N512VLL100 was
contributed by Andrew Webster in NuttX-7.14.
-|
-
---------------
+NXP/FreeScale Kinetis K64
+-------------------------
-|
-
-NXP/FreeScale Kinetis K64. Support for the Kinetis K64 family and
+Support for the Kinetis K64 family and
specifically for the **NXP/Freescale Freedom K64F** board was added in
NuttX 7.17. Initial release includes two NSH configurations with support
for on-board LEDs, buttons, and Ethernet with the on-board KSZ8081 PHY.
@@ -1528,7 +1385,6 @@ Refer to the NuttX board
`README <https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/kinetis/twr-k64f120m/README.txt>`__
file for further information.
-|
**Driver Status**.
@@ -1544,19 +1400,15 @@ file for further information.
Freedom K64F. A Kinetis USB device controller driver and PWM support
was contributed by kfazz.
-|
-
---------------
+NXP/FreeScale Kinetis K66
+-------------------------
-|
-
-NXP/FreeScale Kinetis K66. Support for the Kinetis K64 family and
+Support for the Kinetis K64 family and
specifically for the **NXP/Freescale Freedom K66F** board was
contributed by David Sidrane in NuttX 7.20. Refer to the NuttX board
`README <https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/kinetis/freedom-k66f/README.txt>`__
file for further information.
-|
**Driver Status**.
@@ -1568,13 +1420,12 @@ file for further information.
- **NuttX-7.26**. David Sidrane contributed DMA support to the Kinetis
K6x family.
-|
-
---------------
+Sony CXD56xx
+------------
-|
+(6 x ARM Cortex-M4)
-Sony CXD56\ xx (6 x ARM Cortex-M4). Support for the CXD56\ *xx* was
+Support for the CXD56\ *xx* was
introduced by Nobuto Kobayashi in NuttX-7.30.
**Sony Spresence**. Spresense is a compact development board based on
@@ -1617,13 +1468,10 @@ added an audio_tone_generator, added optional initialization of GNSS and
GEOFENCE at boot if the drivers are enabled, added an lcd examples
configuration.
-|
-
---------------
-
-|
+STMicro STM32 F302x
+-------------------
-STMicro STM32 F302 (STM32 F3 family). Architecture (only) support for
+(STM32 F3 family). Architecture (only) support for
the STM32 F302 was contributed in NuttX-7.10 by Ben Dyer (via the PX4
team and David Sidrane).
@@ -1632,13 +1480,10 @@ NuttX-7.27. Refer to the NuttX board
`README <https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/nucleo-f302r8/README.txt>`__
file for further information.
-|
-
---------------
-
-|
+STMicro STM32 F303x
+-------------------
-STMicro STM32 F303 (STM32 F3 family).
+(STM32 F3 family)
- **STM32F3-Discovery**. This port uses the STMicro STM32F3-Discovery
board featuring the STM32F303VCT6 MCU (STM32 F3 family). Refer to the
@@ -1658,37 +1503,28 @@ STMicro STM32 F303 (STM32 F3 family).
`README <https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/nucleo-f303ze/README.txt>`__
file for further information.
-|
-
---------------
-
-|
+STMicro STM32 F334
+------------------
-STMicro STM32 F334 (STM32 F3 family, ARM Cortex-M4).
+(STM32 F3 family, ARM Cortex-M4)
Support for the STMicro **STM32F334-Disco** board was contributed by
Mateusz Szafoni in NuttX-7.22 and for the **Nucleo-STM32F334R8** was
contributed in an earlier release.
-|
-
---------------
+STMicro STM32 F372/F373
+-----------------------
-|
-
-STMicro STM32 F372/F373 (ARM Cortex-M4).
+(ARM Cortex-M4)
Basic architecture support for the STM32F372/F373 was contributed by
Marten Svanfeldt in NuttX 7.9. There are no STM32F*72 boards currently
supported, however.
-|
-
---------------
-
-|
+STMicro STM32 F4x1
+------------------
-STMicro STM324x1 (STM32 F4 family).
+(STM32 F4 family).
**Nucleo F401RE**. This port uses the STMicro Nucleo F401RE board
featuring the STM32F401RE MCU. Refer to the `STMicro web
@@ -1712,24 +1548,18 @@ further information about this board.
`README <https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/nucleo-f4x1re/README.txt>`__
file for further information.
-|
-
---------------
+STMicro STM32410
+----------------
-|
-
-STMicro STM32410 (STM32 F4 family).
+(STM32 F4 family)
Architecture-only support was contributed to NuttX-7.21 by Gwenhael
Goavec-Merou.
-|
-
---------------
+STMicro STM32 F405x/407x
+------------------------
-|
-
-STMicro STM32405x/407x (STM32 F4 family).
+(STM32 F4 family).
**STMicro STM3240G-EVAL**. This port uses the STMicro STM3240G-EVAL
board featuring the STM32F407IGH6 MCU. Refer to the `STMicro web
@@ -1865,13 +1695,10 @@ is included in this port. The OmnibusF4 specification mandates the
InvenSense MPU6000 which is included in NuttX-7.29 along with a driver
for the MAX7546 OSD.
-|
-
---------------
-
-|
+STMicro STM32 F427/F437
+-----------------------
-STMicro STM32 F427/437. General architectural support was provided for
+General architectural support was provided for
the F427/437 family in NuttX 6.27. Specific support includes the
STM32F427I, STM32F427Z, and STM32F427V chips. This is
*architecture-only* support, meaning that support for the boards with
@@ -1904,13 +1731,10 @@ board features:
Refer to `Axloti <http://www.axoloti.com/>`__ website for further
information about this board.
-|
-
---------------
-
-|
+STMicro STM32 F429
+------------------
-STMicro STM32 F429. Support for STMicro STM32F429I-Discovery development
+Support for STMicro STM32F429I-Discovery development
board featuring the STM32F429ZIT6 MCU was contributed in NuttX-6.32 by
Ken Pettit. The STM32F429ZIT6 is a 180MHz Cortex-M4 operation with 2Mbit
Flash memory and 256kbytes.
@@ -1935,47 +1759,35 @@ Refer to the STM32F429I-Discovery board
`README <https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/stm32f429i-disco/README.txt>`__
file for further information.
-|
-
---------------
-
-|
+STMicro STM32 F433
+------------------
-STMicro STM32 F433. Architecture-only support for the STM32 F433 family
+Architecture-only support for the STM32 F433 family
was contributed by Alan Carvalho de Assis in NuttX-7.22 (meaning that
the parts are supported, but there is no example board supported in the
system). This support was contributed by David Sidrane and made
available in NuttX-7.11.
-|
-
---------------
-
-|
+STMicro STM32 F446
+------------------
-STMicro STM32 F446. Architecture-only support is available for the STM32
+Architecture-only support is available for the STM32
F446 family (meaning that the parts are supported, but there is no
example board supported in the system). This support was contributed by
David Sidrane and made available in NuttX-7.11.
-|
-
---------------
-
-|
+STMicro STM32 F46xx
+-------------------
-STMicro STM32 F46xx. Architecture-only support is available for the
+Architecture-only support is available for the
STM32 F46xx family (meaning that the parts are supported, but there is
no example board supported in the system). This support was contributed
by Paul Alexander Patienc and made available in NuttX-7.15.
-|
-
---------------
-
-|
+STMicro STM32 G474x
+-------------------
-STMicro STM32 G474. One board is supported in this family:
+One board is supported in this family:
- **B-G474E-DPOW1 Discovery Kit**. Initial board support for the
STMicro B-G474E-DPOW1 board from ST Micro was added in NuttX-9.1. See
@@ -1990,13 +1802,10 @@ STMicro STM32 G474. One board is supported in this family:
**NuttX-9.1**. Initial support for booting NuttX to a functional NSH
prompt on this board.
-|
-
---------------
-
-|
+STMicro STM32 L475
+------------------
-STMicro STM32 L475. One board in supported in this family:
+One board in supported in this family:
- **B-L475E-IOT01A Discovery Kit**. Board support for the STMicro
B-L475E-IOT01A board from ST Micro was contributed by Simon Piriou in
@@ -2026,13 +1835,10 @@ topologies.
Simon Pirou also contributed support for the on-board Macronix QuadSPI
FLASH in NuttX 7.22.
-|
-
---------------
-
-|
+STMicro STM32 L476
+------------------
-STMicro STM32 L476. Three boards are supported in this family:
+Three boards are supported in this family:
- **Nucleo-L476RG**. Board support for the STMicro NucleoL476RG board
from ST Micro was contributed by Sebastien Lorquet in NuttX-7.15. See
@@ -2109,13 +1915,10 @@ N.
Enable OTGFS for STM32L4+ series. The OTGFS peripheral on stm32l4x6 and
stm32l4rxxx reference manual is exactly the same. From Jussi Kivilinna.
-|
+STMicro STM32 L4x2
+------------------
---------------
-
-|
-
-STMicro STM32 L4x2. Architecture support for STM32 L4x2 family was
+Architecture support for STM32 L4x2 family was
contributed by Juha Niskanen in NuttX-7.21. Support was extended for the
STM32L412 and STM32L422 chips in NuttX-7.27. Two boards are currently
supported.
@@ -2139,13 +1942,10 @@ supported.
See also the status above for the STM32 L476 most of which also applies
to these parts.
-|
-
---------------
-
-|
+STMicro STM32 L496
+------------------
-STMicro STM32 L496. Architecture support for STM32 L496 was contributed
+Architecture support for STM32 L496 was contributed
by Juha Niskanen along with board support for the Nucleo-L496ZG in
NuttX-7.21:
@@ -2158,13 +1958,10 @@ NuttX-7.21:
file for further information. See also the status above for the STM32
L476 most of which also applies to this part.
-|
-
---------------
-
-|
+STMicro STM32 L4Rx
+------------------
-STMicro STM32 L4Rx. Architecture support for STM32 L4+ family was
+Architecture support for STM32 L4+ family was
contributed by Juha Niskanen along with board support for the
STM32L4R9I-Discovery in NuttX-7.26. Additional support for the
STM32L4R5ZI part was added by Jussi in NuttX-8.2.
@@ -2179,13 +1976,10 @@ STM32L4R5ZI part was added by Jussi in NuttX-8.2.
file for further information. See also the status above for the
opther STM32 L4 parts, most of which also applies to this part.
-|
-
---------------
-
-|
+NXP LPC40xx
+-----------
-NCP LPC40xx. The LPC40xx family is very similar to the LPC17xx family
+The LPC40xx family is very similar to the LPC17xx family
except that it features a Cortex-M4F versus the LPC17xx's Cortex-M3.
Architectural support for the LPC40xx family was built on top of the
existing LPC17xx by jjlange in NuttX-7.31. With that architectural
@@ -2196,13 +1990,10 @@ board may be configured to use either the LPC4088 or the LPC1788.
**Driver Status.**
-|
+NXP LPC43xx
+-----------
---------------
-
-|
-
-NCP LPC43xx. Several board ports are available for this higher end, NXP
+Several board ports are available for this higher end, NXP
Cortex-M4F part:
**NXG Technologies LPC4330-Xplorer**. This NuttX port is for the
@@ -2262,12 +2053,10 @@ LPC4337-WS development board featuring the NXP LPC4337JBD144 MCU.
Alexander Vasiljev. Alexander also contributed an LPC43xx AES driver
available in NuttX-7.16.
-|
**Driver Status**.
- **NuttX-6.20** Several drivers have been copied from the related
- LPC17xx port but require integration into the LPC43xx: ADC, DAC,
GPDMA, I2C, SPI, and SSP. The registers for these blocks are the same
in both the LPC43xx and the LPC17xx and they should integrate into
the LPC43xx very easily by simply adapting the clocking and pin
@@ -2308,13 +2097,10 @@ LPC4337-WS development board featuring the NXP LPC4337JBD144 MCU.
Leveraged the LPC54xx SD/MMC to the LPC43xx. There are still
remaining issues with the SD/MMC driver and it is not yet functional.
-|
-
---------------
-
-|
+NXP LPC54xx
+-----------
-NCP LPC54xx. A port to the
+A port to the
`LPCXpresso-LPC54628 <https://www.nxp.com/support/developer-resources/hardware-development-tools/lpcxpresso-boards/lpcxpresso54628-development-board:OM13098>`__
was added in NuttX-7.24. Initial configurations include: A basic NSH
configuration (nsh), a networking configuration (netnsh), and three
@@ -2323,7 +2109,6 @@ graphics configurations (nxwm, fb, and lvgl).
**LPC4508**. The port was verified on an LPC5408 by a NuttX user with
relevant changes incorporated in NuttX-7.26.
-|
**Driver Status**.
@@ -2340,13 +2125,10 @@ Refer to the LPCXpresso-LPC54628 board
`README <https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/lpc54xx/lpcxpresso-lpc54628/README.txt>`__
file for more detailed information about this port.
-|
+NXP S32K14x
+-----------
---------------
-
-|
-
-NXP S32K14x. Support for the S32K14x family was added in NuttX-8.1. Two
+Support for the S32K14x family was added in NuttX-8.1. Two
boards are supported
- **S32K146EVB**. A port to the S32K146EVB was included in NuttX-8.1.
@@ -2364,8 +2146,6 @@ Both boards featured two NSH configurations: One for execution out of
FLASH and a *safe* version that executes out of SRAM and, hence, cannot
lock up the system because of a bad FLASH image.
-|
-
**Driver Status**.
- **NuttX-8.1** The initial release for the S32K14x boards in NuttX
@@ -2374,22 +2154,16 @@ lock up the system because of a bad FLASH image.
Additional complete-but-unverified drivers were also included: GPIO
interrupts, eDMA, LPSPI, LPI2C, and Ethernet (S32K148 only).
-|
-
---------------
-
-|
+TI/Stellaris LM4F120x
+---------------------
-TI Stellaris LM4F120. This port uses the TI Stellaris LM4F120 LaunchPad.
+This port uses the TI Stellaris LM4F120 LaunchPad.
Jose Pablo Carballo and I are doing this port.
-|
-
---------------
-
-|
+TI/Tiva TM4C123G
+----------------
-TI Tiva TM4C123G. This port uses the Tiva C Series TM4C123G LaunchPad
+This port uses the Tiva C Series TM4C123G LaunchPad
Evaluation Kit
`(EK-TM4C123GXL) <http://www.ti.com/tool/ek-tm4c123gxl>`__.
@@ -2410,13 +2184,10 @@ was contributed in NuttX-8.1 by Nathan Hartman.
- **NuttX-8.1**. Along with TM4C123AH6PM support, Nathan Hartman also
reinstated and extended the Tiva Quadrature Encoder driver.
-|
-
---------------
-
-|
+TI/Tiva TM4C1294
+----------------
-TI Tiva TM4C1294. This port uses the TI Tiva C Series TM4C1294 Connected
+This port uses the TI Tiva C Series TM4C1294 Connected
LaunchPad `(EK-TM4C1294XL) <http://www.ti.com/tool/ek-tm4c1294xl>`__.
**STATUS:**
@@ -2434,13 +2205,10 @@ Refer to the EK-TM4C1294XL board
`README <https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/tiva/tm4c1294-launchpad/README.txt>`__
file for more detailed information about this port.
-|
-
---------------
-
-|
+TI/Tiva TM4C129X
+----------------
-TI Tiva TM4C129X. This port uses the TI Tiva C Series TM4C129X Connected
+This port uses the TI Tiva C Series TM4C129X Connected
Development Kit `(DK-TM4C129X) <http://www.ti.com/tool/dk-tm4c129x>`__.
**STATUS:**
@@ -2464,13 +2232,10 @@ Refer to the DK-TM4C129X board
`README <https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/tiva/dk-tm4c129x/README.txt>`__
file for more detailed information about this port.
-|
-
---------------
-
-|
+TI/SimpleLink CC13x2
+--------------------
-TI/SimpleLink CC13x2. Basic, unverified architectural support for the
+Basic, unverified architectural support for the
CC13x2 was added in NuttX-7.28. Fragmentary support for very similar
CC26x2 family is included. This is a work in progress and, with any
luck, a fully verified port will be available in NuttX-7.29. It is
@@ -2481,13 +2246,10 @@ LaunchXL-CC1312R1 board is in place. Board bring-up, however, cannot be
done until the the basic CC13x2 architecture support is complete,
hopefully in NuttX-7.29.
-|
-
---------------
-
-|
+Atmel SAM4L
+-----------
-Atmel SAM4L. This port uses the Atmel SAM4L Xplained Pro development
+This port uses the Atmel SAM4L Xplained Pro development
board. This board features the ATSAM4LC4C MCU running at 48MHz with
256KB of FLASH and 32KB of internal SRAM.
@@ -2525,13 +2287,10 @@ memory allocation for things like stacks and I/O buffers:
You can see that 22.8KB (71.1%) of the SRAM heap is still available for
further application development while NSH is running.
-|
-
---------------
-
-|
+Atmel SAM4CM
+------------
-Atmel SAM4CM. General architectural support was provided for SAM4CM
+General architectural support was provided for SAM4CM
family in NuttX 7.3 This was *architecture-only* support, meaning that
support for the boards with these chips is available, but no support for
any publicly available boards was included. The SAM4CM port should be
@@ -2539,8 +2298,6 @@ compatible with most of the SAM3/4 drivers (like HSMCI, DMAC, etc.) but
those have not be verified on hardware as of this writing. This support
was contributed in part by Max Neklyudov.
-|
-
**Atmel SAM4CMP-DB**. Support for the SAM4CMP-DB board was contributed
to NuttX by Masayuki Ishikawa in NuttX-7.19. The SAM4CM is a dual-CPU
part and SMP was included for the ARMv7-M and SAM3/4 families. The
@@ -2549,13 +2306,10 @@ an SMP configuration. Refer to the NuttX board
`README <https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/sam34/sam4cmp-db/README.txt>`__
file for further information.
-|
-
---------------
-
-|
+Atmel SAM4E
+-----------
-Atmel SAM4E. General architectural support was provided for the SAM4E
+General architectural support was provided for the SAM4E
family in NuttX 6.32. This was *architecture-only* support, meaning that
support for the boards with these chips is available, but no support for
any publicly available boards was included. This support was contributed
@@ -2568,13 +2322,10 @@ Guide <http://www.nuttx.org/Documentation/NuttShell.html>`__). That NSH
configuration includes networking support and support for an AT25 Serial
FLASH file system.
-|
+Atmel SAM4S
+-----------
---------------
-
-|
-
-Atmel SAM4S. There are ports to two Atmel SAM4S board:
+There are ports to two Atmel SAM4S board:
- There is a port the Atmel SAM4S Xplained development board. This
board features the ATSAM4S16 MCU running at 120MHz with 1MB of FLASH
@@ -2584,12 +2335,6 @@ Atmel SAM4S. There are ports to two Atmel SAM4S board:
board. This board features the ATSAM4S32C MCU running at 120MHz with
2MB of FLASH and 160KB of internal SRAM.
-|
-
---------------
-
-|
-
Atmel SAM4E. General architectural support was provided for the SAM4E
family in NuttX 6.32. This was *architecture-only* support, meaning that
support for the boards with these chips is available, but no support for
@@ -2603,12 +2348,6 @@ Guide <http://www.nuttx.org/Documentation/NuttShell.html>`__). That NSH
configuration includes networking support and support for an AT25 Serial
FLASH file system.
-|
-
---------------
-
-|
-
**Development Environments:** 1) Linux with native Linux GNU toolchain,
2) Cygwin/MSYS with Cygwin GNU Cortex-M3 or 4 toolchain, 3) Cygwin/MSYS
with Windows native GNU Cortex-M3 or M4 toolchain (CodeSourcery or
@@ -2619,11 +2358,13 @@ package.
-ARM Cortex-M7.
+ARM Cortex-M7
+=============
-|
+Atmel SAMV71
+------------
-Atmel SAMV71. This port uses Atmel SAM V71 Xplained Ultra Evaluation Kit
+This port uses Atmel SAM V71 Xplained Ultra Evaluation Kit
(SAMV71-XULT). This board features the ATSAMV71Q21 Cortex-M7
microcontroller. Refer to the `Atmel web
site <http://www.atmel.com/tools/atsamv71-xult.aspx>`__ for further
@@ -2679,13 +2420,10 @@ Refer to the NuttX board
`README <https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/samv7/samv71-xult/README.txt>`__
file for further information.
-|
+Atmel SAME70
+------------
---------------
-
-|
-
-Atmel SAME70. This port uses Atmel SAM E70 Xplained Evaluation Kit
+This port uses Atmel SAM E70 Xplained Evaluation Kit
(ATSAME70-XPLD). This board is essentially a lower cost version of the
SAMV71-XULT board featuring the ATSAME70Q21 Cortex-M7 microcontroller.
See the `Atmel SAMV71 <#at91samv71>`__ for supported features. Also
@@ -2693,13 +2431,10 @@ refer to the NuttX board
`README <https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/samv7/same70-xplained/README.txt>`__
file for further information.
-|
-
---------------
-
-|
+Atmel SAMD5x/E5x
+----------------
-Atmel SAMD5x/E5x. The port of NuttX to Adafruit Metro M4 development
+The port of NuttX to Adafruit Metro M4 development
board was released with NuttX-7/26. This board is essentially a advanced
version of the Adafruit Metro board based on the SAMD21, but upgraded to
the SAMD51, specifically the SAMD51J19. See the
@@ -2723,26 +2458,20 @@ file for further information about the current state of the port.
Nuttx-9.0 added basic support for Microchip SAME54 Xplained Pro board.
An ethernet driver was also added to the SAME5x familly.
-|
+STMicro STM32 F72x/F73x
+-----------------------
---------------
-
-|
-
-STMicro STM32 F72x/F73x. Support for the F72x/F73x family was provided
+Support for the F72x/F73x family was provided
by Bob Feretich in NuttX-7.23. A single board is supported in this
family:
**STATUS**: See `below <#stm32f7drivers>`__ for STM32 F7 driver
availability.
-|
-
---------------
-
-|
+STMicro STM32 F745/F746
+-----------------------
-STMicro STM32 F745/F746. Three boards are supported for this MCU:
+Three boards are supported for this MCU:
#. **STM32F746G Discovery**. One port uses the STMicro STM32F746G-DISCO
development board featuring the STM32F746NGH6 MCU. The STM32F746NGH6
@@ -2783,25 +2512,19 @@ STM32 F7 Driver Status:
- **NuttX-9.0**. Added serial DMA support.
-|
+STMicro STM32 F756
+------------------
---------------
-
-|
-
-STMicro STM32 F756. Architecture-only support is available for the STM32
+Architecture-only support is available for the STM32
F756 family (meaning that the parts are supported, but there is no
example board supported in the system). This support was made available
in NuttX-7.11. See `above <#stm32f7drivers>`__ for STM32 F7 driver
availability.
-|
-
---------------
-
-|
+STMicro STM32 F76xx/F77xx
+-------------------------
-STMicro STM32 F76xx/F77xx. Architecture support for the STM32 F76xx and
+Architecture support for the STM32 F76xx and
F77xx families was contributed by David Sidrane in NuttX 7.17. Support
is available for two boards from this family:
@@ -2840,13 +2563,10 @@ is available for two boards from this family:
**STATUS**: See `above <#stm32f7drivers>`__ for STM32 F7 driver
availability.
-|
+STMicro STM32 H7x3
+------------------
---------------
-
-|
-
-STMicro STM32 H7x3 Architecture support for the STM32 H7x3 was added
+Architecture support for the STM32 H7x3 was added
through efforts of several people in NuttX-7.26. Support is available
for one board from this family:
@@ -2866,12 +2586,6 @@ for one board from this family:
This port is still a work in progress.
-|
-
-**Driver Availability**:
-
-**NuttX-7.27**. Add I2C and SPI support for the STM32H7. From Mateusz
-Szafoni.
**NuttX-7.30**. Added support for Ethernet, SDMMC, and Timer drivers.
All from Jukka Laitinen.
@@ -2884,13 +2598,10 @@ Sidrane.
**NuttX-9.0**. Added QSPI support for the STM32H7.
-|
-
---------------
-
-|
+NXP/Freescale i.MX RT
+---------------------
-NXP/Freescale i.MX RT. The initial port to the IMXRT1050-EVKB featuring
+The initial port to the IMXRT1050-EVKB featuring
the MIMXRT1052DVL6A *Crossover* MCU was included initially in
NuttX-7.25. The initial port was the joint effort of Janne Rosberg, Ivan
Ucherdzhiev, and myself. Ivan gets credit for the bulk of the bring-up
@@ -2949,12 +2660,6 @@ NuttX-7.27.
**NuttX-9.0**. Added USB Device support.
-|
-
---------------
-
-|
-
**Development Environments:** The same basic development environment is
recommended for the Cortex-M7 as for the Cortex-M4. It would be wise to
use the latest GNU toolchains for this part because as of this writing
@@ -2962,16 +2667,22 @@ use the latest GNU toolchains for this part because as of this writing
-Atmel AVR.
+Atmel AVR
+=========
-|
+AVR ATMega
+----------
-**AVR ATMega**.
+AVR ATMega128
+-------------
-SoC Robotics ATMega128. This port of NuttX to the Amber Web Server from
+This port of NuttX to the Amber Web Server from
`SoC Robotics <http://www.soc-robotics.com/index.htm>`__ is partially
completed. The Amber Web Server is based on an Atmel ATMega128.
+AVR ATMega1284P
+---------------
+
LowPowerLab MoteinoMEGA. This port of NuttX to the MoteinoMEGA from
`LowPowerLab <http://www.lowpowerlab.com>`__. The MoteinoMEGA is based
on an Atmel ATMega1284P. See the LowPowerlab
@@ -2980,17 +2691,15 @@ and the board
`README <https://bitbucket.org/nuttx/nuttx/src/master/boards/avr/atmega/moteino-mega/README.txt>`__
file for further information.
-Arduino MEGA2560. Extension of the AVR architecture to support the
-ATMega2560 and specifi support for the Arduion MEGA2560 board were
-contributed by Dimitry Kloper and first released in NuttX-7.14.
-
-|
-
+AVR ATMega2560
--------------
-|
+Extension of the AVR architecture to support the
+ATMega2560 and specifi support for the Arduion MEGA2560 board were
+contributed by Dimitry Kloper and first released in NuttX-7.14.
-AVR AT90USB64x and AT90USB6128x.
+AVR AT90USB64x and AT90USB6128x
+-------------------------------
**Micropendous 3 AT90USB64x** and **AT90USB6128x**. This port of NuttX
to the Opendous Micropendous 3 board. The Micropendous3 is may be
@@ -3003,12 +2712,6 @@ Teensy++ 2.0 board. This board was developed by
`PJRC <http://pjrc.com/teensy/>`__. The Teensy++ 2.0 is based on an
Atmel AT90USB1286 MCU.
-|
-
---------------
-
-|
-
**AVR-Specific Issues**. The basic AVR port is solid. The biggest issue
for using AVR is its tiny SRAM memory and its Harvard architecture.
Because of the Harvard architecture, constant data that resides to flash
@@ -3030,12 +2733,6 @@ done:
#. Create a special version of printf that knows how to access strings
that reside in FLASH (or EEPROM).
-|
-
---------------
-
-|
-
**Development Environments:** 1) Linux with native Linux GNU toolchain,
2) Cygwin/MSYS with Cygwin GNU toolchain, 3) Cygwin/MSYS with Windows
native toolchain, or 4) Native Windows. All testing, however, has been
@@ -3044,15 +2741,8 @@ by the NuttX
`buildroot <https://bitbucket.org/nuttx/buildroot/downloads/>`__
package. As a result, that toolchain is recommended.
-|
-
-|
-
-
-
-Atmel AVR32.
-
-|
+Atmel AVR32
+===========
AV32DEV1. This port uses the www.mcuzone.com AVRDEV1 board based on the
Atmel AT32UC3B0256 MCU. This port requires a special GNU avr32 toolchain
@@ -3085,10 +2775,8 @@ NuttX board
file for further information.
-
-**Misoc**.
-
-|
+Misoc
+=====
Misoc LM32 Architectural Support. Architectural support for the Misoc
LM32 was contributed by Ramtin Amin in NuttX 7.19
@@ -3102,20 +2790,16 @@ Misoc LM32 under Qemu or on your custom FPGA.
-OpenRISC mor1kx.
-
-|
+OpenRISC mor1kx
+===============
**OpenRISC mor1kx Architectural Support**. Architectural support for the
OpenRISC mor1kx was developed by Matt Thompson Amin and released in
NuttX 7.25. Currently only an mor1kx Qemu simulation is available for
testing.
-
-
-Freescale M68HCS12.
-
-|
+Freescale M68HCS12
+==================
**MC9S12NE64**. Support for the MC9S12NE64 MCU and two boards are
included:
@@ -3130,9 +2814,8 @@ for the m9s12x family.
-Intel 80x86.
-
-|
+Intel 80x86
+===========
**QEMU/Bifferboard i486**. This port uses the
`QEMU <http://wiki.qemu.org/Main_Page>`__ i486 and the native Linux,
@@ -3164,23 +2847,22 @@ This kernel with ostest have been tested with
-Microchip PIC32MX (MIPS M4K).
+Microchip PIC32MX
+=================
-|
+(MIPS M4K architecture)
-PIC32MX250F128D. A port is in progress from the DTX1-4000L "Mirtoo"
+Microchip PIC32MX2xx
+--------------------
+
+A port is in progress from the DTX1-4000L "Mirtoo"
module from `Dimitech <http://www.dimitech.com/>`__. This module uses
Microchip PIC32MX250F128D and the Dimitech DTX1-4000L EV-kit1 V2. See
the `Dimitech <http://www.dimitech.com/>`__ website for further
information.
-|
-
---------------
-
-|
-
-PIC32MX4xx Family.
+Microchip PIC32MX4xx
+--------------------
**PIC32MX440F512H**. This port uses the "Advanced USB Storage Demo
Board," Model DB-DP11215, from `Sure
@@ -3207,11 +2889,8 @@ port configuration.)
board <http://www.sparkfun.com/products/9713>`__. See also the
`UBW32 <http://www.schmalzhaus.com/UBW32/>`__ web site.
-|
-
---------------
-
-|
+Microchip PIC32MX7xx
+--------------------
PIC32MX795F512L. There one two board ports using this chip:
@@ -3223,12 +2902,6 @@ PIC32MX795F512L. There one two board ports using this chip:
completed for the Mikroelektronika PIC32MX7 Multimedia Board (MMB).
See http://www.mikroe.com/ for further information about this board.
-|
-
---------------
-
-|
-
**Development Environment:** These ports uses either:
#. The *LITE* version of the PIC32MX toolchain available for download
@@ -3239,10 +2912,8 @@ PIC32MX795F512L. There one two board ports using this chip:
Graphics <http://www.mentor.com>`__ website.
-
-Microchip PIC32MZ.
-
-|
+Microchip PIC32MZEC
+-------------------
PIC32MZEC Family (MIPS microAptiv). A port is in available for the
PIC32MZ Embedded Connectivity (EC) Starter Kit. There are two
@@ -3260,8 +2931,12 @@ This was a collaborative effort between Kristopher Tate, David Sidrane
and myself. The basic port is functional and a NuttShell (NSH)
configuration is available.
-PIC32MZEF Family (MIPS M5150). A port is in available for the
-MikroElectronika `Flip&Click
+Microchip PIC32MZEF
+===================
+
+(MIPS M5150 architecture).
+
+A port is in available for the MikroElectronika `Flip&Click
PIC32MZ <https://www.mikroe.com/flipclick-pic32mz>`__ development board
based on the PIC32MZ2048EFH100 MCU. This board configuration was added
in NuttX-7.24 and is, for the most part, compatible with the PIC32MZEC
@@ -3293,33 +2968,18 @@ Refer to the NuttX board
`README <https://bitbucket.org/nuttx/nuttx/src/master/boards/mips/pic32mz/pic32mz-starterkit/README.txt>`__
file for further information.
-|
-
---------------
-
-|
-
**Development Environment:** Same as for the PIC32MZ.
-|
-
---------------
-
-
-
-Renesas/Hitachi SuperH.
-
-|
+Renesas/Hitachi SuperH
+======================
**SH-1 SH7032**. This port uses the Hitachi SH-1 Low-Cost Evaluation
Board (SH1_LCEVB1), US7032EVB, with a GNU ELF toolchain\* under Linux or
Cygwin.
-
-Renesas M16C/26.
-
-|
+Renesas M16C/26
+---------------
**Renesas M16C/26 Microcontroller**. This port uses the Renesas SKP16C26
Starter kit and the GNU M32C toolchain. The development environment is
@@ -3336,11 +2996,8 @@ Refer to the NuttX board
`README <https://bitbucket.org/nuttx/nuttx/src/master/boards/renesas/m16c/skp16c26/README.txt>`__
file for further information.
-
-
-Renesas RX65N.
-
-|
+Renesas RX65N
+-------------
Support for the Renesas RX65N family was released in NuttX with a
contribution from Anjana. Two boards are supported in this initial
@@ -3356,17 +3013,25 @@ release:
-RISC-V.
-
-|
+RISC-V
+======
RISC-V Architectural Support. Basic support for the RISC-V architecture
-was contributed by Ken Pettit in NuttX-7.19. This support is for a
-custom NEXT RISC-V NR5Mxx (RV32IM). The initial release is *thin* but a
-great starting point for anyone interested in RISC-V development with
+was contributed by Ken Pettit in NuttX-7.19.
+
+NEXT RISC-V NR5Mxx
+------------------
+
+This support is for a custom NEXT RISC-V NR5Mxx (RV32IM). The initial release
+is *thin* but a great starting point for anyone interested in RISC-V development with
NuttX.
-GreenWaves GAP8 (RV32IM). Basic support GreenWaves GAP8 *gapuino* board
+GreenWaves GAP8
+---------------
+
+(RV32IM architecture)
+
+Basic support GreenWaves GAP8 *gapuino* board
was added by hhuysqt in NuttX-7.27. The GAP8 is a 1+8-core DSP-like
RISC-V MCU. The GAP8 features a RI5CY core called Fabric Controller(FC),
and a cluster of 8 RI5CY cores that runs at a bit slower speed. The GAP8
@@ -3377,19 +3042,22 @@ Parallel-Ultra-Low-Power design.
Initial support for the Sipeed Maix bit board was added in Nuttx-9.0.
-Litex ARTY_A7. Support for the Digilent ARTY_A7 board along with CPU
-VexRiscV SOC were added in NuttX-9.0.
+LiteX on ARTY A7
+----------------
+Support for the Digilent ARTY_A7 board along with CPU VexRiscV SOC were
+added in NuttX-9.0.
-ESP32 (Dual Xtensa LX6).
+ESP32 (Dual Xtensa LX6)
+=======================
-|
+Xtensa LX6 ESP32
+----------------
-**Xtensa LX6 ESP32 Architectural Support**. Basic architectural support
-for Xtensa LX6 processors and the port for the Espressif ESP32 were
-added in NuttX-7.19. The basic ESP32 port is function in both single CPU
-and dual CPU SMP configurations.
+Basic architectural support for Xtensa LX6 processors and the port for
+the Espressif ESP32 were added in NuttX-7.19. The basic ESP32 port is
+function in both single CPU and dual CPU SMP configurations.
**Espressif ESP32 Core v2 Board** The NuttX release includes support for
Espressif ESP32 Core v2 board. There is an NSH configuration for each
@@ -3407,28 +3075,25 @@ file for further information.
-Zilog ZNEO Z16F.
-
-|
-
-- **Zilog z16f2800100zcog development kit**. This port use the Zilog
- z16f2800100zcog development kit and the Zilog ZDS-II Windows command
- line tools. The development environment is either Windows native or
- Cygwin under Windows.
-
- **STATUS:** The initial release of support for the z16f was made
- available in NuttX version 0.3.7. A working NuttShell (NSH)
- configuration as added in NuttX-6.33 (although a patch is required to
- work around an issue with a ZDS-II 5.0.1 tool problem). An ESPI
- driver was added in NuttX-7.2. Refer to the NuttX board
- `README <https://bitbucket.org/nuttx/nuttx/src/master/boards/z16/z16f/z16f2800100zcog/README.txt>`__
- file for further information.
+Zilog ZNEO Z16F
+===============
+**Zilog z16f2800100zcog development kit**. This port use the Zilog
+z16f2800100zcog development kit and the Zilog ZDS-II Windows command
+line tools. The development environment is either Windows native or
+Cygwin under Windows.
+**STATUS:** The initial release of support for the z16f was made
+available in NuttX version 0.3.7. A working NuttShell (NSH)
+configuration as added in NuttX-6.33 (although a patch is required to
+work around an issue with a ZDS-II 5.0.1 tool problem). An ESPI
+driver was added in NuttX-7.2. Refer to the NuttX board
+`README <https://bitbucket.org/nuttx/nuttx/src/master/boards/z16/z16f/z16f2800100zcog/README.txt>`__
+file for further information.
-Zilog eZ80 Acclaim!.
-|
+Zilog eZ80 Acclaim!
+===================
**Zilog eZ80Acclaim! Microcontroller**. There are four eZ80Acclaim!
ports:
@@ -3444,9 +3109,8 @@ Windows native or Cygwin or MSYS2 under Windows.
-Zilog Z8Encore!.
-
-|
+Zilog Z8Encore!
+===============
**Zilog Z8Encore! Microcontroller**. This port uses the either:
@@ -3466,9 +3130,8 @@ for further information.
-Zilog Z180.
-
-|
+Zilog Z180
+==========
**P112**. The P112 is a hobbyist single board computer based on a 16MHz
Z80182 with up to 1MB of memory, serial, parallel and diskette IO, and
@@ -3489,9 +3152,8 @@ file for further information.
-Zilog Z80.
-
-|
+Zilog Z80
+=========
**Z80 Instruction Set Simulator**. This port uses the
`SDCC <http://sdcc.sourceforge.net/>`__ toolchain under Linux or Cygwin
@@ -3503,12 +3165,6 @@ be tested using an instruction set simulator. Refer to the NuttX board
`README <https://bitbucket.org/nuttx/nuttx/src/master/boards/z80/z80/z80sim/README.txt>`__
file for further information.
-|
-
---------------
-
-|
-
**XTRS: TRS-80 Model I/III/4/4P Emulator for Unix**. A very similar Z80
port is available for `XTRS <http://www.tim-mann.org/xtrs.html>`__, the
TRS-80 Model I/III/4/4P Emulator for Unix. That port also uses the
diff --git a/Documentation/introduction/supported_platforms.rst b/Documentation/introduction/supported_platforms.rst
index ac2dd0e..fe287de 100644
--- a/Documentation/introduction/supported_platforms.rst
+++ b/Documentation/introduction/supported_platforms.rst
@@ -1,5 +1,6 @@
.. include:: /substitutions.rst
+
===================
Supported Platforms
===================
@@ -13,76 +14,74 @@ from board-to-board. Follow the links for the details:
* -
- - `Linux/Cygwin user mode simulation <#linuxusermode>`__ (1)
+ - :ref:`introduction/detailed_support:Linux User Mode Simulation` (1)
- ARM
- - `ARM7TDMI <#arm7tdmi>`__ (4)
- - `ARM920T <#arm920t>`__ (1)
- - `ARM926EJS <#arm926ejs>`__ (4)
- - `Other ARMv4 <#armv4>`__ (1)
- - `ARM1176JZ <#arm1176jz>`__ (1)
- - `ARM Cortex-A5 <#armcortexa5>`__ (3)
- - `ARM Cortex-A8 <#armcortexa8>`__ (2)
- - `ARM Cortex-A9 <#armcortexa9>`__ (1)
- - `ARM Cortex-R4 <#armcortexr4>`__ (2)
- - `ARM Cortex-M0/M0+ <#armcortexm0>`__ (13)
- - `ARM Cortex-M3 <#armcortexm3>`__ (39)
- - `ARM Cortex-M4 <#armcortexm4>`__ (59)
- - `ARM Cortex-M7 <#armcortexm7>`__ (15)
+ - :ref:`introduction/detailed_support:ARM7TDMI` (4)
+ - :ref:`introduction/detailed_support:ARM920T` (1)
+ - :ref:`introduction/detailed_support:ARM926EJS` (4)
+ - :ref:`introduction/detailed_support:Other ARMv4` (1)
+ - :ref:`introduction/detailed_support:ARM1176JZ` (1)
+ - :ref:`introduction/detailed_support:ARM Cortex-A5` (3)
+ - :ref:`introduction/detailed_support:ARM Cortex-A8` (2)
+ - :ref:`introduction/detailed_support:ARM Cortex-A9` (1)
+ - :ref:`introduction/detailed_support:ARM Cortex-R4` (2)
+ - :ref:`introduction/detailed_support:ARM Cortex-M0/M0+` (13)
+ - :ref:`introduction/detailed_support:ARM Cortex-M3` (39)
+ - :ref:`introduction/detailed_support:ARM Cortex-M4` (59)
+ - :ref:`introduction/detailed_support:ARM Cortex-M7` (15)
- Atmel AVR
- - `Atmel 8-bit AVR <#atmelavr>`__ (5)
- - `Atmel AVR32 <#atmelavr32>`__ (1)
+ - :ref:`introduction/detailed_support:Atmel AVR` (8-bit) (5)
+ - :ref:`introduction/detailed_support:Atmel AVR32` (1)
- Freescale
- - `M68HCS12 <#m68hcs12>`__ (2)
+ - :ref:`introduction/detailed_support:Freescale M68HCS12` (2)
-
- Intel
- - `Intel 80x86 <#80x86>`__ (2)
+ - :ref:`introduction/detailed_support:Intel 80x86` (2)
- Microchip
- - `PIC32MX <#pic32mxmips>`__ (MIPS M4K) (4)
- - `PIC32MZEC <#pic32mzmips>`__ (MIPS microAptive) (1)
- - `PIC32MZEF <#pic32mzmips>`__ (MIPS M5150) (1)
+ - :ref:`introduction/detailed_support:Microchip PIC32MX` (MIPS M4K) (4)
+ - :ref:`introduction/detailed_support:Microchip PIC32MZEF` (MIPS M5150) (1)
- Misoc
- - `LM32 <#misoclm32>`__ (1)
- - `Minerva <#minerva>`__ (1)
+ - :ref:`introduction/detailed_support:Misoc` (1)
- OpenRISC
- - `mor1kx <#mor1kx>`__ (1)
+ - :ref:`introduction/detailed_support:OpenRISC mor1kx` (1)
- Renesas/Hitachi:
- - `Renesas/Hitachi SuperH <#superh>`__ (1/2)
- - `Renesas M16C/26 <#m16c>`__ (1/2)
- - `Renesas RX65N <#rx65n>`__ (2)
+ - :ref:`introduction/detailed_support:Renesas/Hitachi SuperH` (1/2)
+ - :ref:`introduction/detailed_support:Renesas M16C/26` (1/2)
+ - :ref:`introduction/detailed_support:Renesas RX65N` (2)
+
-
- - `RISC-V <#riscv>`__ (2)
+ - :ref:`introduction/detailed_support:RISC-V` (2)
- - `NEXT RISC-V NR5Mxx <#nr5mxx>`__ (1)
- - `GreenWaves GAP8 (1) <#gwgap8>`__
- - `Kendryte K210 (1) <#k210>`__
- - `Litex (1) <#artya7>`__
+ - :ref:`introduction/detailed_support:NEXT RISC-V NR5Mxx` (1)
+ - :ref:`introduction/detailed_support:GreenWaves GAP8` (1)
+ - :ref:`introduction/detailed_support:LiteX on Arty A7` (1)
- Xtensa LX6:
- - `ESP32 <#esp32>`__ (1)
+ - :ref:`introduction/detailed_support:ESP32 (Dual Xtensa LX6)` (1)
- ZiLOG
- - `ZiLOG ZNEO Z16F <#zilogz16f>`__ (2)
- - `ZiLOG eZ80 Acclaim! <#zilogez80acclaim>`__ (4)
- - `ZiLOG Z8Encore! <#zilogz8encore>`__ (2)
- - `ZiLOG Z180 <#zilogz180>`__ (1)
- - `ZiLOG Z80 <#zilogz80>`__ (2)
+ - :ref:`introduction/detailed_support:ZiLOG ZNEO Z16F` (2)
+ - :ref:`introduction/detailed_support:ZiLOG eZ80 Acclaim!` (4)
+ - :ref:`introduction/detailed_support:ZiLOG Z8Encore!` (2)
+ - :ref:`introduction/detailed_support:ZiLOG Z180` (1)
+ - :ref:`introduction/detailed_support:ZiLOG Z80` (2)
**Supported Platforms by Manufacturer/MCU Family**. CPU core type
follows in parentheses. The state of the various ports vary from MCU to
@@ -92,339 +91,258 @@ MCU. Follow the links for the details:
* -
- - `Linux/Cygwin user mode simulation <#linuxusermode>`__ (1) ARM
+ - :ref:`introduction/detailed_support:Linux User Mode Simulation` (1) ARM
- Allwinner
- - `A10 <#allwinnera10>`__ (Cortex-A8)
+ - :ref:`introduction/detailed_support:Allwinner A10` (Cortex-A8)
- Broadcom
- - `BCM2708 <#bcm2708>`__ (ARM1176JZ)
+ - :ref:`introduction/detailed_support:Broadcom BCM2708` (ARM1176JZ)
- Espressif
- - `ESP32 <#esp32>`__ (Dual Xtensa LX6)
+ - :ref:`introduction/detailed_support:Xtensa LX6 ESP32` (Dual Xtensa LX6)
- GreenWaves
- - `GAP8 <#gwgap8>`__ (RISC-V RV32IM)
+ - :ref:`introduction/detailed_support:Greenwaves GAP8` (RISC-V RV32IM)
- Host PC based simulations
- - `Linux/Cygwin user mode simulation <#linuxusermode>`__
+ - :ref:`introduction/detailed_support:Linux User Mode Simulation`
- Infineon
- - `Infineon XMC45xx <#xmd45xx>`__
+ - :ref:`introduction/detailed_support:Infineon XMC45xx`
- Intel
- - `Intel 80x86 <#80x86>`__
+ - :ref:`introduction/detailed_support:Intel 80x86`
- Maxim Integrated
- - `MAX32660 <#max3660>`__ (ARM Cortex-M3)
+ - :ref:`introduction/detailed_support:Maxim Integrated MAX32660` (ARM Cortex-M3)
- Microchip
- - `PIC32MX2xx Family <#pic32mx2xx>`__ (MIPS32 M4K)
- - `PIC32MX4xx Family <#pic32mx4xx>`__ (MIPS32 M4K)
- - `PIC32MX7xx Family <#pic32mx7xx>`__ (MIPS32 M4K)
- - `PIC32MZEC Family <#pic32mzec>`__ (MIPS32
- microAptiv)
- - `PIC32MZEF Family <#pic32mzef>`__ (MIPS32 M5150)
+ - :ref:`introduction/detailed_support:Microchip PIC32MX2xx` (MIPS32 M4K)
+ - :ref:`introduction/detailed_support:Microchip PIC32MX4xx` (MIPS32 M4K)
+ - :ref:`introduction/detailed_support:Microchip PIC32MX7xx` (MIPS32 M4K)
+ - :ref:`introduction/detailed_support:Microchip PIC32MZEC` (MIPS32 microAptiv)
+ - :ref:`introduction/detailed_support:Microchip PIC32MZEF` (MIPS32 M5150)
- Microchip (Formerly Atmel)
- - `AVR ATMega128 <#avratmega128>`__ (8-bit AVR)
- - `AVR ATMega1284p <#avratmega1284p>`__ (8-bit AVR)
- - `AVR ATMega2560 <#avratmega2560>`__ (8-bit AVR)
- - `AVR AT90USB64x and AT90USB6128x <#avrat90usbxxx>`__
- (8-bit AVR)
- - `AVR32 AT32UC3BXXX <#at32uc3bxxx>`__ (32-bit AVR32)
- - `Atmel SAMD20 <#at91samd20>`__ (ARM Cortex-M0+)
- - `Atmel SAMD21 <#at91samd21>`__ (ARM Cortex-M0+)
- - `Atmel SAML21 <#at91saml21>`__ (ARM Cortex-M0+)
- - `Atmel SAM3U <#at91sam3u>`__ (ARM Cortex-M3)
- - `Atmel SAM3X <#at91sam3x>`__ (ARM Cortex-M3)
- - `Atmel SAM4C <#at91sam4c>`__ (ARM Cortex-M4)
- - `Atmel SAM4E <#at91sam4e>`__ (ARM Cortex-M4)
- - `Atmel SAM4L <#at91sam4l>`__ (ARM Cortex-M4)
- - `Atmel SAM4S <#at91sam4s>`__ (ARM Cortex-M4)
- - `Atmel SAMD5x/E5x <#at91samd5e5>`__ (ARM Cortex-M4)
- - `Atmel SAME70 <#at91same70>`__ (ARM Cortex-M7)
- - `Atmel SAMV71 <#at91samv71>`__ (ARM Cortex-M7)
- - `Atmel SAMA5D2 <#at91sama5d2>`__ (ARM Cortex-A5)
- - `Atmel SAMA5D3 <#at91sama5d3>`__ (ARM Cortex-A5)
- - `Atmel SAMA5D4 <#at91sama5d4>`__ (ARM Cortex-A5)
+ - :ref:`introduction/detailed_support:AVR ATMega128` (8-bit AVR)
+ - :ref:`introduction/detailed_support:AVR ATMega1284p` (8-bit AVR)
+ - :ref:`introduction/detailed_support:AVR ATMega2560` (8-bit AVR)
+ - :ref:`introduction/detailed_support:AVR AT90USB64x and AT90USB6128x`
+ (8-bit AVR)
+ - :ref:`introduction/detailed_support:Atmel AVR32` (AT32UC3BXXX, 32-bit AVR32)
+ - :ref:`introduction/detailed_support:Atmel SAMD20` (ARM Cortex-M0+)
+ - :ref:`introduction/detailed_support:Atmel SAMD21` (ARM Cortex-M0+)
+ - :ref:`introduction/detailed_support:Atmel SAML21` (ARM Cortex-M0+)
+ - :ref:`introduction/detailed_support:Atmel SAM3U` (ARM Cortex-M3)
+ - :ref:`introduction/detailed_support:Atmel SAM3X` (ARM Cortex-M3)
+ - :ref:`introduction/detailed_support:Atmel SAM4CM` (ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:Atmel SAM4E` (ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:Atmel SAM4L` (ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:Atmel SAM4S` (ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:Atmel SAMD5x/E5x` (ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:Atmel SAME70` (ARM Cortex-M7)
+ - :ref:`introduction/detailed_support:Atmel SAMV71` (ARM Cortex-M7)
+ - :ref:`introduction/detailed_support:Atmel SAMA5D2` (ARM Cortex-A5)
+ - :ref:`introduction/detailed_support:Atmel SAMA5D3` (ARM Cortex-A5)
+ - :ref:`introduction/detailed_support:Atmel SAMA5D4` (ARM Cortex-A5)
- Moxa
- - `Moxa NP51x0 <#moxart>`__ (ARMv4)
+ - :ref:`introduction/detailed_support:Moxa NP51x0` (ARMv4)
- nuvoTon
- - `nuvoTon NUC120 <#nuvotonnu120>`__ (ARM Cortex-M0)
+ - :ref:`introduction/detailed_support:nuvoTon NUC120` (ARM Cortex-M0)
- Nordic Semiconductor
- - `NRF52xxx <#nrf52>`__ (ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:Nordic Semiconductor NRF52xxx` (ARM Cortex-M4)
- NXP/Freescale
- - `M68HCS12 <#m68hcs12>`__
- - `NXP/Freescale i.MX1 <#freescaleimx1>`__
- (ARM920-T)
- - `NXP/Freescale i.MX6 <#freescaleimx6>`__
- (ARM Cortex-A9)
- - `NXP/Freescale i.MX RT <#freescaleimxrt>`__
- (ARM Cortex-M7)
- - `NXP/FreeScale KL25Z <#freescalekl25z>`__
- (ARM Cortex-M0+)
- - `NXP/FreeScale KL26Z <#freescalekl26z>`__
- (ARM Cortex-M0+)
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- -
+ - :ref:`introduction/detailed_support:Freescale M68HCS12`
+ - :ref:`introduction/detailed_support:NXP/Freescale i.MX1` (ARM920-T)
+ - :ref:`introduction/detailed_support:NXP/Freescale i.MX6` (ARM Cortex-A9)
+ - :ref:`introduction/detailed_support:NXP/Freescale i.MX RT` (ARM Cortex-M7)
+ - :ref:`introduction/detailed_support:NXP/FreeScale KL25Z` (ARM Cortex-M0+)
+ - :ref:`introduction/detailed_support:NXP/FreeScale KL26Z` (ARM Cortex-M0+)
+ - :ref:`introduction/detailed_support:NXP/FreeScale Kinetis K20` (ARM
+ Cortex-M4)
+ - :ref:`introduction/detailed_support:NXP/FreeScale Kinetis K28F` (ARM
+ Cortex-M4)
+ - :ref:`introduction/detailed_support:NXP/FreeScale Kinetis K40` (ARM
+ Cortex-M4)
+ - :ref:`introduction/detailed_support:NXP/FreeScale Kinetis K60` (ARM
+ Cortex-M4)
+ - :ref:`introduction/detailed_support:NXP/FreeScale Kinetis K64` (ARM
+ Cortex-M4)
+ - :ref:`introduction/detailed_support:NXP/FreeScale Kinetis K66` (ARM
+ Cortex-M4)
+
+ - :ref:`introduction/detailed_support:NXP LPC11xx` (Cortex-M0)
+ - :ref:`introduction/detailed_support:NXP LPC214x` (ARM7TDMI)
+ - :ref:`introduction/detailed_support:NXP LPC2378` (ARM7TDMI)
+ - :ref:`introduction/detailed_support:NXP LPC3131` (ARM9E6JS)
+ - :ref:`introduction/detailed_support:NXP LPC315x` (ARM9E6JS)
+ - :ref:`introduction/detailed_support:NXP LPC176x` (ARM Cortex-M3)
+ - :ref:`introduction/detailed_support:NXP LPC178x` (ARM Cortex-M3)
+ - :ref:`introduction/detailed_support:NXP LPC40xx` (ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:NXP LPC43xx` (ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:NXP LPC54xx` (ARM Cortex-M4)
+
+ - :ref:`introduction/detailed_support:NXP S32K11x` (Cortex-M0+)
+ - :ref:`introduction/detailed_support:NXP S32K14x` (Cortex-M4F)
- - NXP/Freescale (Continued)
-
- - `NXP/FreeScale Kinetis K20 <#kinetisk20>`__ (ARM
- Cortex-M4)
- - `NXP/FreeScale Kinetis K28 <#kinetisk28>`__ (ARM
- Cortex-M4)
- - `NXP/FreeScale Kinetis K40 <#kinetisk40>`__ (ARM
- Cortex-M4)
- - `NXP/FreeScale Kinetis K60 <#kinetisk60>`__ (ARM
- Cortex-M4)
- - `NXP/FreeScale Kinetis K64 <#kinetisk64>`__ (ARM
- Cortex-M4)
- - `NXP/FreeScale Kinetis K66 <#kinetisk66>`__ (ARM
- Cortex-M4)
-
- - `NXP LPC11xx <#nxplpc11xx>`__ (Cortex-M0)
- - `NXP LPC214x <#nxplpc214x>`__ (ARM7TDMI)
- - `NXP LPC2378 <#nxplpc2378>`__ (ARM7TDMI)
- - `NXP LPC3131 <#nxplpc3131>`__ (ARM9E6JS)
- - `NXP LPC315x <#nxplpc315x>`__ (ARM9E6JS)
- - `NXP LPC176x <#nxplpc176x>`__ (ARM Cortex-M3)
- - `NXP LPC178x <#nxplpc178x>`__ (ARM Cortex-M3)
- - `NXP LPC40xx <#nxplpc40xx>`__ (ARM Cortex-M4)
- - `NXP LPC43xx <#nxplpc43xx>`__ (ARM Cortex-M4)
- - `NXP LPC54xx <#nxplpc54xx>`__ (ARM Cortex-M4)
-
- - `NXP S32K11x <#nxps32k11x>`__ (Cortex-M0+)
- - `NXP S32K14x <#nxps32k14x>`__ (Cortex-M4F)
+ -
- ON Semiconductor:
- - `LC823450 <#lc823450>`__ (Dual core ARM Cortex-M3)
+ - :ref:`introduction/detailed_support:On Semiconductor LC823450` (Dual core ARM Cortex-M3)
- Renesas/Hitachi:
- - `Renesas/Hitachi SuperH <#superh>`__
- - `Renesas M16C/26 <#m16c>`__
- - `Renesas RX65N <#rx65n>`__
+ - :ref:`introduction/detailed_support:Renesas/Hitachi SuperH`
+ - :ref:`introduction/detailed_support:Renesas M16C/26`
+ - :ref:`introduction/detailed_support:Renesas RX65N`
- Silicon Laboratories, Inc.
- - `EFM32 Gecko <#efm32g>`__ (ARM Cortex-M3)
- - `EFM32 Giant Gecko <#efm32gg>`__ (ARM Cortex-M3)
+ - :ref:`introduction/detailed_support:SiLabs EFM32 Gecko` (ARM Cortex-M3)
+ - :ref:`introduction/detailed_support:SiLabs EFM32 Giant Gecko` (ARM Cortex-M3)
- Sony.
- - `CXD56\ xx <#cxd56xx>`__ (6 x ARM Cortex-M4)
-
+ - :ref:`introduction/detailed_support:Sony CXD56xx` (6 x ARM Cortex-M4)
- STMicroelectronics
- - `STMicro STR71x <#str71x>`__ (ARM7TDMI)
- - `STMicro STM32F0xx <#stm32f0xx>`__ (STM32 F0,
- ARM Cortex-M0)
- - `STMicro STM32L0xx <#stm32l0xx>`__ (STM32 L0,
- ARM Cortex-M0)
- - `STMicro STM32G0xx <#stm32g0xx>`__ (STM32 G0
- ARM Cortex-M0+)
- - `STMicro STM32L152 <#stm32l152>`__ (STM32 L1
- "EnergyLite" Line, ARM Cortex-M3)
- - `STMicro STM32L162 <#stm32l162>`__ (STM32 L1
- "EnergyLite" Medium+ Density,
- ARM Cortex-M3)
- - `STMicro STM32F100x <#stm32f100x>`__ (STM32 F1
- "Value Line" Family, ARM Cortex-M3)
- - `STMicro STM32F102x <#stm32f102x>`__ (STM32 F1
- family, ARM Cortex-M3)
- - `STMicro STM32F103C4/C8 <#stm32f103cx>`__ (STM32 F1
- "Low- and Medium-Density Line"
- Family, ARM Cortex-M3)
- - `STMicro STM32F103x <#stm32f103x>`__ (STM32 F1
- family, ARM Cortex-M3)
- - `STMicro STM32F105x <#stm32f105x>`__ (ARM Cortex-M3)
- - `STMicro STM32F107x <#stm32f107x>`__ (STM32 F1
- family, "Connectivity Line"
- ARM Cortex-M3)
- - `STMicro STM32F205x <#stm32f205x>`__ (STM32 F2
- family, ARM Cortex-M3)
- - `STMicro STM32F207x <#stm32f207x>`__ (STM32 F2
- family, ARM Cortex-M3)
- - `STMicro STM32F302x <#stm32f302x>`__ (STM32 F3
- family, ARM Cortex-M4)
- - `STMicro STM32F303x <#stm32f303x>`__ (STM32 F3
- family, ARM Cortex-M4)
- - `STMicro STM32F334 <#stm32f334x>`__ (STM32 F3
- family, ARM Cortex-M4)
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+ - :ref:`introduction/detailed_support:STMicro STR71x` (ARM7TDMI)
+ - :ref:`introduction/detailed_support:STMicro STM32 F0xx` (STM32 F0,
+ ARM Cortex-M0)
+ - :ref:`introduction/detailed_support:STMicro STM32 L0xx` (STM32 L0,
+ ARM Cortex-M0)
+ - :ref:`introduction/detailed_support:STMicro STM32 G0xx` (STM32 G0
+ ARM Cortex-M0+)
+ - :ref:`introduction/detailed_support:STMicro STM32 L152` (STM32 L1
+ "EnergyLite" Line, ARM Cortex-M3)
+ - :ref:`introduction/detailed_support:STMicro STM32 L15x/16x` (STM32 L1
+ "EnergyLite" Medium+ Density, ARM Cortex-M3)
+ - :ref:`introduction/detailed_support:STMicro STM32 F100x` (STM32 F1
+ "Value Line" Family, ARM Cortex-M3)
+ - :ref:`introduction/detailed_support:STMicro STM32 F102x` (STM32 F1
+ family, ARM Cortex-M3)
+ - :ref:`introduction/detailed_support:STMicro STM32 F103C4/C8` (STM32 F1
+ "Low- and Medium-Density Line" Family, ARM Cortex-M3)
+ - :ref:`introduction/detailed_support:STMicro STM32 F103x` (STM32 F1
+ family, ARM Cortex-M3)
+ - :ref:`introduction/detailed_support:STMicro STM32 F105x` (ARM Cortex-M3)
+ - :ref:`introduction/detailed_support:STMicro STM32 F107x` (STM32 F1
+ family, "Connectivity Line" ARM Cortex-M3)
+ - :ref:`introduction/detailed_support:STMicro STM32 F205x` (STM32 F2
+ family, ARM Cortex-M3)
+ - :ref:`introduction/detailed_support:STMicro STM32 F207x` (STM32 F2
+ family, ARM Cortex-M3)
+ - :ref:`introduction/detailed_support:STMicro STM32 F302x` (STM32 F3
+ family, ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:STMicro STM32 F303x` (STM32 F3
+ family, ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:STMicro STM32 F334` (STM32 F3
+ family, ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:STMicro STM32 F372/F373`
+ (ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:STMicro STM32 F4x1`
+ (STM32 F4 family, ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:STMicro STM32 F405x/407x`
+ (STM32 F4 family, ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:STMicro STM32 F427/F437`
+ (STM32 F4 family, ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:STMicro STM32 F429`
+ (STM32 FB family, ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:STMicro STM32 F433`
+ (STM32 F4 family, ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:STMicro STM32 F446`
+ (STM32 F4 family, ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:STMicro STM32 F46xx`
+ (STM32 F4 family, ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:STMicro STM32 G474x`
+ (STM32 G4 family, ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:STMicro STM32 L4x2`
+ (STM32 L4 family, ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:STMicro STM32 L475`
+ (STM32 L4 family, ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:STMicro STM32 L476`
+ (STM32 L4 family, ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:STMicro STM32 L496`
+ (STM32 L4 family, ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:STMicro STM32 L4Rx`
+ (STM32 LB family, ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:STMicro STM32 F72x/F73x`
+ (STM32 F7 family, ARM Cortex-M7)
+ - :ref:`introduction/detailed_support:STMicro STM32 F745/F746`
+ (STM32 F7 family, ARM Cortex-M7)
+ - :ref:`introduction/detailed_support:STMicro STM32 F756`
+ (STM32 F7 family, ARM Cortex-M7)
+ - :ref:`introduction/detailed_support:STMicro STM32 F76xx/F77xx`
+ (STM32 F7 family, ARM Cortex-M7)
+ - :ref:`introduction/detailed_support:STMicro STM32 H7x3`
+ (STM32 H7 family, ARM Cortex-M7)
-
- - STMicroelectronics (Continued)
-
- - `STMicro STM32 F372/F373 <#stm32f372x>`__
- (ARM Cortex-M4)
- - `STMicro STM32F4x1 <#stm32f4x1>`__
- (STM32 F4 family, ARM
- Cortex-M4)
- - `STMicro STM32F410 <#stm32f410>`__
- (STM32 F4 family, ARM
- Cortex-M4)
- - `STMicro STM32F405x/407x <#stm32f407x>`__
- (STM32 F4 family, ARM
- Cortex-M4)
- - `STMicro STM32 F427/F437 <#stm32f427x>`__
- (STM32 F4 family, ARM
- Cortex-M4)
- - `STMicro STM32 F429 <#stm32f429x>`__
- (STM32 FB family, ARM
- Cortex-M4)
- - `STMicro STM32 F433 <#stm32f433x>`__
- (STM32 F4 family, ARM
- Cortex-M4)
- - `STMicro STM32 F446 <#stm32f446x>`__
- (STM32 F4 family, ARM
- Cortex-M4)
- - `STMicro STM32 F46xx <#stm32f46xxx>`__
- (STM32 F4 family, ARM
- Cortex-M4)
- - `STMicro STM32 G474x <#stm32g474x>`__
- (STM32 G4 family, ARM
- Cortex-M4)
- - `STMicro STM32 L4x2 <#stm32l4x2>`__
- (STM32 L4 family, ARM
- Cortex-M4)
- - `STMicro STM32 L475 <#stm32l475>`__
- (STM32 L4 family, ARM
- Cortex-M4)
- - `STMicro STM32 L476 <#stm32l476>`__
- (STM32 L4 family, ARM
- Cortex-M4)
- - `STMicro STM32 L496 <#stm32l496>`__
- (STM32 L4 family, ARM
- Cortex-M4)
- - `STMicro STM32 L4Rx <#stm32l4rx>`__
- (STM32 LB family, ARM
- Cortex-M4)
- - `STMicro STM32 F72x/F73x <#stm32f72x3x>`__
- (STM32 F7 family, ARM
- Cortex-M7)
- - `STMicro STM32 F745/F746 <#stm32f74x>`__
- (STM32 F7 family, ARM
- Cortex-M7)
- - `STMicro STM32 F756 <#stm32f75x>`__
- (STM32 F7 family, ARM
- Cortex-M7)
- - `STMicro STM32 F76xx/F77xx <#stm32f76xx77xx>`__
- (STM32 F7 family, ARM
- Cortex-M7)
- - `STMicro STM32 H7x3 <#stm32h7x3>`__
- (STM32 H7 family, ARM
- Cortex-M7)
-
- Texas Instruments
- (some formerly Luminary)
- - `TI TMS320-C5471 <#tms320c5471>`__
- (ARM7TDMI)
- - `TI TMS320-DM320 <#titms320dm320>`__
- (ARM9E6JS)
- - `TI/Stellaris LM3S6432 <#tilms6432>`__
- (ARM Cortex-M3)
- - `TI/Stellaris LM3S6432S2E <#tilm3s6432s2e>`__
- (ARM Cortex-M3)
- - `TI/Stellaris LM3S6918 <#tilms6918>`__
- (ARM Cortex-M3)
- - `TI/Stellaris LM3S6965 <#tilms6965>`__
- (ARM Cortex-M3)
- - `TI/Stellaris LM3S8962 <#tilms8962>`__
- (ARM Cortex-M3)
- - `TI/Stellaris LM3S9B92 <#tilms9b92>`__
- (ARM Cortex-M3)
- - `TI/Stellaris LM3S9B96 <#tilms9b96>`__
- (ARM Cortex-M3)
- - `TI/SimpleLink CC13x0 <#tilcc13x0>`__
- (ARM Cortex-M3)
- - `TI/Stellaris LM4F120x <#tilm4f120x>`__
- (ARM Cortex-M4)
- - `TI/Tiva TM4C123G <#titm4c123g>`__
- (ARM Cortex-M4)
- - `TI/Tiva TM4C1294 <#titm4c1294>`__
- (ARM Cortex-M4)
- - `TI/Tiva TM4C129X <#titm4c129x>`__
- (ARM Cortex-M4)
- - `TI/SimpleLink CC13x2 <#tilcc13x2>`__
- (ARM Cortex-M4)
- - `TI/Hercules TMS570LS04xx <#tms570ls04x>`__
- (ARM Cortex-R4)
- - `TI/Hercules TMS570LS31xx <#tms570ls31x>`__
- (ARM Cortex-R4)
- - `TI/Sitara AM335x <#tiam355x>`__
- (Cortex-A8)
+ - :ref:`introduction/detailed_support:TI TMS320-C5471`
+ (ARM7TDMI)
+ - :ref:`introduction/detailed_support:TI TMS320-DM320`
+ (ARM9E6JS)
+ - :ref:`introduction/detailed_support:TI/Stellaris LM3S6432`
+ (ARM Cortex-M3)
+ - :ref:`introduction/detailed_support:TI/Stellaris LM3S6432S2E`
+ (ARM Cortex-M3)
+ - :ref:`introduction/detailed_support:TI/Stellaris LM3S6918`
+ (ARM Cortex-M3)
+ - :ref:`introduction/detailed_support:TI/Stellaris LM3S6965`
+ (ARM Cortex-M3)
+ - :ref:`introduction/detailed_support:TI/Stellaris LM3S8962`
+ (ARM Cortex-M3)
+ - :ref:`introduction/detailed_support:TI/Stellaris LM3S9B92`
+ (ARM Cortex-M3)
+ - :ref:`introduction/detailed_support:TI/Stellaris LM3S9B96`
+ (ARM Cortex-M3)
+ - :ref:`introduction/detailed_support:TI/SimpleLink CC13x0`
+ (ARM Cortex-M3)
+ - :ref:`introduction/detailed_support:TI/Stellaris LM4F120x`
+ (ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:TI/Tiva TM4C123G`
+ (ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:TI/Tiva TM4C1294`
+ (ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:TI/Tiva TM4C129X`
+ (ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:TI/SimpleLink CC13x2`
+ (ARM Cortex-M4)
+ - :ref:`introduction/detailed_support:TI/Hercules TMS570LS04xx`
+ (ARM Cortex-R4)
+ - :ref:`introduction/detailed_support:TI/Hercules TMS570LS31xx`
+ (ARM Cortex-R4)
+ - :ref:`introduction/detailed_support:TI/Sitara AM335x`
+ (Cortex-A8)
- ZiLOG
- - `ZiLOG ZNEO Z16F <#zilogz16f>`__
- - `ZiLOG eZ80 Acclaim! <#zilogez80acclaim>`__
- - `ZiLOG Z8Encore! <#zilogz8encore>`__
- - `ZiLOG Z180 <#zilogz180>`__
- - `ZiLOG Z80 <#zilogz80>`__
+ - :ref:`introduction/detailed_support:ZiLOG ZNEO Z16F`
+ - :ref:`introduction/detailed_support:ZiLOG eZ80 Acclaim!`
+ - :ref:`introduction/detailed_support:ZiLOG Z8Encore!`
+ - :ref:`introduction/detailed_support:ZiLOG Z180`
+ - :ref:`introduction/detailed_support:ZiLOG Z80`
[incubator-nuttx] 15/17: support specifying top alignment for tables
Posted by bt...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
btashton pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
commit 896ba15f01e025b77a8b05ef1689b13c48769a39
Author: Matias N <ma...@protobits.dev>
AuthorDate: Mon Aug 17 12:29:31 2020 -0300
support specifying top alignment for tables
---
Documentation/_static/custom.css | 8 ++++++++
Documentation/introduction/supported_platforms.rst | 3 ++-
2 files changed, 10 insertions(+), 1 deletion(-)
diff --git a/Documentation/_static/custom.css b/Documentation/_static/custom.css
index 6f470e3..6a939f8 100644
--- a/Documentation/_static/custom.css
+++ b/Documentation/_static/custom.css
@@ -11,6 +11,7 @@
}
/* override table width restrictions */
+
@media screen and (min-width: 767px) {
.wy-table-responsive table td {
@@ -24,9 +25,16 @@
}
}
+/* remove useless padding on the sidebar */
.wy-nav-side
{
padding-bottom: 0em !important;
}
+/* define some classes to be used */
+
+table.valign-top td {
+ vertical-align: top !important;
+}
+
diff --git a/Documentation/introduction/supported_platforms.rst b/Documentation/introduction/supported_platforms.rst
index fe287de..e96444d 100644
--- a/Documentation/introduction/supported_platforms.rst
+++ b/Documentation/introduction/supported_platforms.rst
@@ -10,7 +10,7 @@ CPU follow in parentheses. The state of the various ports vary
from board-to-board. Follow the links for the details:
.. list-table::
- :widths: auto
+ :class: valign-top
* -
@@ -88,6 +88,7 @@ follows in parentheses. The state of the various ports vary from MCU to
MCU. Follow the links for the details:
.. list-table::
+ :class: valign-top
* -
[incubator-nuttx] 02/17: finished NX document migration
Posted by bt...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
btashton pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
commit 04d31a17248417736a2d925b67eae4cd1e159679
Author: Matias N <ma...@protobits.dev>
AuthorDate: Fri Aug 14 15:25:50 2020 -0300
finished NX document migration
---
doc/components/nxgraphics/nx.rst | 8 +-
doc/components/nxgraphics/nxtk.rst | 1175 +++++++++++++++++-------------------
2 files changed, 551 insertions(+), 632 deletions(-)
diff --git a/doc/components/nxgraphics/nx.rst b/doc/components/nxgraphics/nx.rst
index c21ed18..49f33c7 100644
--- a/doc/components/nxgraphics/nx.rst
+++ b/doc/components/nxgraphics/nx.rst
@@ -402,10 +402,8 @@ NX Server Callbacks
:param handle: The handle returned by ```nx_connect()`` <#nxconnectinstance>`__.
:param flags: Optional flags. These include:
- - ``NXBE_WINDOW_RAMBACKED``: Creates a RAM backed window. This
- option is only valid if ``CONFIG_NX_RAMBACKED`` is enabled.
- - ``NXBE_WINDOW_HIDDEN``: The window is create in the HIDDEN state
- and can be made visible later with ``nx_setvisibility()``.
+ - ``NXBE_WINDOW_RAMBACKED``: Creates a RAM backed window. This option is only valid if ``CONFIG_NX_RAMBACKED`` is enabled.
+ - ``NXBE_WINDOW_HIDDEN``: The window is create in the HIDDEN state and can be made visible later with ``nx_setvisibility()``.
:param cb: Callbacks used to process window events
:param arg: User provided value that will be returned with NX callbacks.
@@ -510,7 +508,7 @@ NX Server Callbacks
Bring the specified window to the top of the display.
:param hwnd: The handle returned by :c:func:`nx_openwindow`. This
- handle must not have been created by :c:func:`nx_requestbkgd`_.
+ handle must not have been created by :c:func:`nx_requestbkgd`.
:return: ``OK`` on success; ``ERROR`` on failure with ``errno`` set appropriately
diff --git a/doc/components/nxgraphics/nxtk.rst b/doc/components/nxgraphics/nxtk.rst
index 89642a4..52a80cc 100644
--- a/doc/components/nxgraphics/nxtk.rst
+++ b/doc/components/nxgraphics/nxtk.rst
@@ -58,674 +58,595 @@ these sub-windows to be managed more-or-less independently:
:return: OK on success; ERROR on failure with errno set
appropriately.
-2.4.3 ``nxtk_synch()``
-~~~~~~~~~~~~~~~~~~~~~~
+.. c:function:: int nxtk_synch(NXWINDOW hwnd, FAR void *arg);
-**Function Prototype:**
+ This interface can be used to synchronize the window
+ client with the NX server. It really just implements an *echo*: A synch
+ message is sent from the window client to the server which then responds
+ immediately by sending the ``NXEVENT_SYNCHED`` back to the windows
+ client.
-**Description:** This interface can be used to synchronize the window
-client with the NX server. It really just implements an *echo*: A synch
-message is sent from the window client to the server which then responds
-immediately by sending the ``NXEVENT_SYNCHED`` back to the windows
-client.
+ Due to the highly asynchronous nature of client-server communications,
+ ``nx_synch()`` is sometimes necessary to assure that the client and
+ server are fully synchronized in time.
-Due to the highly asynchronous nature of client-server communications,
-``nx_synch()`` is sometimes necessary to assure that the client and
-server are fully synchronized in time.
-
-Usage by the window client might be something like this:
-
-When the window listener thread receives the ``NXEVENT_SYNCHED`` event,
-it would set ``g_synched`` to ``true`` and post ``g_synch_sem``, waking
-up the above loop.
-
-**Input Parameters:**
-
-``wnd``
- The window to be synched
-``arg``
- An argument that will accompany the synch messages (This is ``arg2``
- in the event callback).
-
-**Returned Value:** OK on success; ERROR on failure with errno set
-appropriately
-
-2.4.4 ``nxtk_openwindow()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Function Prototype:**
-
-**Description:** Create a new, framed window.
-
-**Input Parameters:**
-
-``handle``
- The handle returned by ```nx_connect()`` <#nxconnectinstance>`__.
-``flags``
- Optional flags. These include:
-
- - ``NXBE_WINDOW_RAMBACKED``: Creates a RAM backed window. This
- option is only valid if ``CONFIG_NX_RAMBACKED`` is enabled.
- - ``NXBE_WINDOW_HIDDEN``: The window is create in the HIDDEN state
- and can be made visible later with ``nxtk_setvisibility()``.
-
-``cb``
- Callbacks used to process window events
-``arg``
- User provided argument (see ```nx_openwindow()`` <#nxopenwindow>`__)
-
-**Returned Value:**
-
-2.4.5 ``nxtk_closewindow()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Function Prototype:**
-
-**Description:** Close the window opened by
-```nxtk_openwindow()`` <#nxtkopenwindow>`__.
-
-**Input Parameters:**
-
-``hfwnd``
- A handle previously returned by
- ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
-
-**Returned Value:** ``OK`` on success; ``ERROR`` on failure with
-``errno`` set appropriately
-
-2.4.6 ``nxtk_getposition()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Function Prototype:**
-
-**Description:** Request the position and size information for the
-selected framed window. The size/position for the client window and
-toolbar will be return asynchronously through the client callback
-function pointer.
-
-**Input Parameters:**
-
-``hfwnd``
- A handle previously returned by
- ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
-
-**Returned Value:** ``OK`` on success; ``ERROR`` on failure with
-``errno`` set appropriately
-
-2.4.7 ``nxtk_setposition()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Function Prototype:**
-
-**Description:** Set the position for the selected client window. This
-position does not include the offsets for the borders nor for any
-toolbar. Those offsets will be added in to set the full window position.
-
-**Input Parameters:**
-
-``hfwnd``
- A handle previously returned by
- ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
-``pos``
- The new position of the client sub-window
-
-**Returned Value:** ``OK`` on success; ``ERROR`` on failure with
-``errno`` set appropriately
-
-2.4.8 ``nxtk_setsize()``
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Function Prototype:**
-
-**Description:** Set the size for the selected client window. This size
-does not include the sizes of the borders nor for any toolbar. Those
-sizes will be added in to set the full window size.
-
-**Input Parameters:**
-
-``hfwnd``
- A handle previously returned by
- ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
-``size``
- The new size of the client sub-window.
-
-**Returned Value:** ``OK`` on success; ``ERROR`` on failure with
-``errno`` set appropriately
-
-2.4.9 ``nxtk_raise()``
-~~~~~~~~~~~~~~~~~~~~~~
-
-**Function Prototype:**
-
-**Description:** Bring the window containing the specified client
-sub-window to the top of the display.
-
-**Input Parameters:**
-
-``hfwnd``
- A handle previously returned by
- ```nxtk_openwindow()`` <#nxtkopenwindow>`__ specifying the window to
- be raised.
-````
-
-**Returned Value:** ``OK`` on success; ``ERROR`` on failure with
-``errno`` set appropriately
-
-2.4.10 ``nxtk_lower()``
-~~~~~~~~~~~~~~~~~~~~~~~
-
-**Function Prototype:**
-
-**Description:** Lower the window containing the specified client
-sub-window to the bottom of the display.
-
-**Input Parameters:**
-
-``hfwnd``
- A handle previously returned by
- ```nxtk_openwindow()`` <#nxtkopenwindow>`__ specifying the window to
- be lowered.
-````
-
-**Returned Value:** ``OK`` on success; ``ERROR`` on failure with
-``errno`` set appropriately
-
-2.4.11 ``nxtk_modal()``
-~~~~~~~~~~~~~~~~~~~~~~~
-
-**Function Prototype:**
-
-**Description:** May be used to either (1) raise a window to the top of
-the display and select modal behavior, or (2) disable modal behavior.
-
-**Input Parameters:**
-
-``hwnd``
- The handle returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__
- specifying the window to be modified.
-``modal``
- True: enter modal state; False: leave modal state
-
-**Returned Value:** ``OK`` on success; ``ERROR`` on failure with
-``errno`` set appropriately
-
-2.4.12 ``nxtk_setvisibility()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Function Prototype:**
-
-**Description:** Select if the window is visible or hidden. A hidden
-window is still present and will update normally, but will not be
-visible on the display until it is unhidden.
-
-**Input Parameters:**
-
-``hwnd``
- The handle returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__
- specifying the window to be modified.
-``hide``
- True: Window will be hidden; false: Window will be visible
-
-**Returned Value:** ``OK`` on success; ``ERROR`` on failure with
-``errno`` set appropriately
-
-2.4.13 ``nxtk_ishidden()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Function Prototype:**
-
-**Description:** Return true if the window is hidden.
-
-**NOTE**: There will be a delay between the time that the visibility of
-the window is changed via
-```nxtk_setvisibily()`` <#nxtksetvisibility>`__ before that new setting
-is reported by ``nxtk_ishidden()``. ``nxtk_synch()`` may be used if
-temporal synchronization is required.
-
-**Input Parameters:**
-
-``hfwnd``
- The handle returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__
- that identifies the window to be queried.
-
-**Returned Value:** *True*: the window is hidden, *false*: the window is
-visible
-
-2.4.14 ``nxtk_fillwindow()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Function Prototype:**
-
-**Description:** Fill the specified rectangle in the client window with
-the specified color.
-
-**Input Parameters:**
-
-``hfwnd``
- A handle previously returned by
- ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
-``rect``
- The location within the client window to be filled
-``color``
- The color to use in the fill
-
-**Returned Value:** ``OK`` on success; ``ERROR`` on failure with
-``errno`` set appropriately
-
-2.4.15 ``nxtk_getwindow()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Function Prototype:**
-
-**Description:** Get the raw contents of graphic memory within a
-rectangular region. NOTE: Since raw graphic memory is returned, the
-returned memory content may be the memory of windows above this one and
-may not necessarily belong to this window unless you assure that this is
-the top window.
-
-**Input Parameters:**
-
-``hfwnd``
- A handle previously returned by
- ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
-``rect``
- The location within the client window to be retrieved.
-``plane``
- Specifies the color plane to get from.
-``dest``
- The location to copy the memory region
-``deststride``
- The width, in bytes, of the dest memory
-
-**Returned Value:** ``OK`` on success; ``ERROR`` on failure with
-``errno`` set appropriately
-
-2.4.16 ``nxtk_filltrapwindow()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Function Prototype:**
-
-**Description:** Fill the specified trapezoid in the client window with
-the specified color
-
-**Input Parameters:**
-
-``hfwnd``
- A handle previously returned by
- ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
-``trap``
- The trapezoidal region to be filled.
-``color``
- The color to use in the fill.
-
-**Returned Value:** ``OK`` on success; ``ERROR`` on failure with
-``errno`` set appropriately
-
-2.4.17 ``nxtk_drawlinewindow()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Function Prototype:**
-
-**Description:** Fill the specified trapezoidal region in the window
-with the specified color. Fill the specified line in the window with the
-specified color. This is simply a wrapper that uses ``nxgl_splitline()``
-to break the line into trapezoids and then calls
-``nxtk_filltrapwindow()`` to render the line.
-
-**Input Parameters:**
-
-``hfwnd``
- A handle previously returned by
- ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
-``vector``
- Describes the line to be drawn.
-``width``
- The width of the line
-``color``
- The color to use to fill the line
-``caps``
- Draw a circular cap on the ends of the line to support better line
- joins. One of:
-
-**Returned Value:** ``OK`` on success; ``ERROR`` on failure with
-``errno`` set appropriately
-
-2.4.18 ``nxtk_drawcirclewindow()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Function Prototype:**
-
-**Description:** Draw a circular outline using the specified line
-thickness and color.
-
-**Input Parameters:**
-
-``hfwnd``
- A handle previously returned by
- ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
-``center``
- A pointer to the point that is the center of the circle.
-``radius``
- The radius of the circle in pixels.
-``width``
- The width of the line
-``color``
- The color to use to fill the line
-
-**Returned Value:** ``OK`` on success; ``ERROR`` on failure with
-``errno`` set appropriately
-
-2.4.19 ``nxtk_fillcirclewindow()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Function Prototype:**
-
-**Description:** Fill a circular region using the specified color.
-
-**Input Parameters:**
-
-``hfwnd``
- A handle previously returned by
- ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
-``center``
- A pointer to the point that is the center of the circle.
-``radius``
- The width of the line
-``color``
- The color to use to fill the circle
-
-**Returned Value:** ``OK`` on success; ``ERROR`` on failure with
-``errno`` set appropriately
-
-2.4.20 ``nxtk_movewindow()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Function Prototype:**
-
-**Description:** Move a rectangular region within the client sub-window
-of a framed window.
-
-**Input Parameters:**
-
-``hfwnd``
- A handle previously returned by
- ```nxtk_openwindow()`` <#nxtkopenwindow>`__ specifying the client
- sub-window within which the move is to be done.
-``rect``
- Describes the rectangular region relative to the client sub-window to
- move.
-``offset``
- The offset to move the region
-
-**Returned Value:** ``OK`` on success; ``ERROR`` on failure with
-``errno`` set appropriately
-
-2.4.21 ``nxtk_bitmapwindow()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Usage by the window client might be something like this:
+
+ .. code-block:: c
+
+ extern bool g_synched;
+ extern sem_t g_synch_sem;
+
+ g_synched = false;
+ ret = nxtk_synch(hfwnd, handle);
+ if (ret < 0)
+ {
+ -- Handle the error --
+ }
+
+ while (!g_synched)
+ {
+ ret = sem_wait(&g_sync_sem);
+ if (ret < 0)
+ {
+ -- Handle the error --
+ }
+ }
+
+ When the window listener thread receives the ``NXEVENT_SYNCHED`` event,
+ it would set ``g_synched`` to ``true`` and post ``g_synch_sem``, waking
+ up the above loop.
+
+ :param wnd:
+ The window to be synched
+ :param arg:
+ An argument that will accompany the synch messages (This is ``arg2``
+ in the event callback).
-**Function Prototype:**
+ :return: OK on success; ERROR on failure with errno set
+ appropriately
-**Description:** Copy a rectangular region of a larger image into the
-rectangle in the specified client sub-window.
+.. c:function:: NXTKWINDOW nxtk_openwindow(NXHANDLE handle, uint8_t flags, \
+ FAR const struct nx_callback_s *cb, \
+ FAR void *arg);
-**Input Parameters:**
+ Create a new, framed window.
-``hfwnd``
- A handle previously returned by
- ```nxtk_openwindow()`` <#nxtkopenwindow>`__ specifying the client
- sub-window that will receive the bitmap.
-``dest``
- Describes the rectangular region on in the client sub-window will
- receive the bit map.
-``src``
- The start of the source image(s). This is an array source images of
- size ``CONFIG_NX_NPLANES`` (probably 1).
-``origin``
- The origin of the upper, left-most corner of the full bitmap. Both
- dest and origin are in sub-window coordinates, however, the origin
- may lie outside of the sub-window display.
-``stride``
- The width of the full source image in pixels.
+ :param handle:
+ The handle returned by ```nx_connect()`` <#nxconnectinstance>`__.
+ :param flags:
+ Optional flags. These include:
-**Returned Value:** ``OK`` on success; ``ERROR`` on failure with
-``errno`` set appropriately
+ - ``NXBE_WINDOW_RAMBACKED``: Creates a RAM backed window. This
+ option is only valid if ``CONFIG_NX_RAMBACKED`` is enabled.
+ - ``NXBE_WINDOW_HIDDEN``: The window is create in the HIDDEN state
+ and can be made visible later with ``nxtk_setvisibility()``.
-2.4.22 ``nxtk_opentoolbar()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ :param cb:
+ Callbacks used to process window events
+ :param arg:
+ User provided argument (see ```nx_openwindow()`` <#nxopenwindow>`__)
-**Function Prototype:**
+ :return: Success: A non-NULL handle used with subsequent NXTK window accesses
+ Failure: NULL is returned and errno is set appropriately.
-**Description:** Create a tool bar at the top of the specified framed
-window.
+.. c:function:: int nxtk_closewindow(NXTKWINDOW hfwnd);
-**Input Parameters:**
+ Close the window opened by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
-``hfwnd``
- A handle previously returned by
- ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
-``height``
- The requested height of the toolbar in pixels.
-``cb``
- Callbacks used to process toolbar events.
-``arg``
- User provided value that will be returned with toolbar callbacks.
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
-**Returned Value:** ``OK`` on success; ``ERROR`` on failure with
-``errno`` set appropriately
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
-2.4.23 ``nxtk_closetoolbar()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. c:function:: int nxtk_getposition(NXTKWINDOW hfwnd);
-**Function Prototype:**
+ Request the position and size information for the
+ selected framed window. The size/position for the client window and
+ toolbar will be return asynchronously through the client callback
+ function pointer.
-**Description:** Remove the tool bar at the top of the specified framed
-window.
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
-**Input Parameters:**
-
-``hfwnd``
- A handle previously returned by
- ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
-````
-
-**Returned Value:** ``OK`` on success; ``ERROR`` on failure with
-``errno`` set appropriately
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
-2.4.24 ``nxtk_filltoolbar()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. c:function:: int nxtk_setposition(NXTKWINDOW hfwnd, FAR struct nxgl_point_s *pos);
-**Function Prototype:**
+ Set the position for the selected client window. This
+ position does not include the offsets for the borders nor for any
+ toolbar. Those offsets will be added in to set the full window position.
-**Description:** Fill the specified rectangle in the toolbar sub-window
-with the specified color.
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
+ :param pos:
+ The new position of the client sub-window
-**Input Parameters:**
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
-``hfwnd``
- A handle previously returned by
- ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
-``rect``
- The location within the toolbar window to be filled.
-``color``
- The color to use in the fill.
-
-**Returned Value:** ``OK`` on success; ``ERROR`` on failure with
-``errno`` set appropriately
-
-2.4.25 ``nxtk_gettoolbar()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. c:function:: int nxtk_setsize(NXTKWINDOW hfwnd, FAR struct nxgl_size_s *size);
-**Function Prototype:**
+ Set the size for the selected client window. This size
+ does not include the sizes of the borders nor for any toolbar. Those
+ sizes will be added in to set the full window size.
-**Description:** Get the raw contents of graphic memory within a
-rectangular region. NOTE: Since raw graphic memory is returned, the
-returned memory content may be the memory of windows above this one and
-may not necessarily belong to this window unless you assure that this is
-the top window.
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
+ :param size:
+ The new size of the client sub-window.
-**Input Parameters:**
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
-``hfwnd``
- A handle previously returned by
- ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
-``rect``
- The location within the toolbar window to be retrieved.
-``plane``
- TSpecifies the color plane to get from.
-``dest``
- TThe location to copy the memory region.
-``deststride``
- The width, in bytes, of the dest memory.
+.. c:function:: int nxtk_raise(NXTKWINDOW hfwnd);
-**Returned Value:** ``OK`` on success; ``ERROR`` on failure with
-``errno`` set appropriately
+ Bring the window containing the specified client
+ sub-window to the top of the display.
-2.4.26 ``nxtk_filltraptoolbar()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__ specifying the window to
+ be raised.
-**Function Prototype:**
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
-**Description:** Fill the specified trapezoid in the toolbar sub-window
-with the specified color.
+.. c:function:: int nxtk_lower(NXTKWINDOW hfwnd);
-**Input Parameters:**
+ Lower the window containing the specified client
+ sub-window to the bottom of the display.
-``hfwnd``
- A handle previously returned by
- ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
-``trap``
- The trapezoidal region to be filled
-``color``
- The color to use in the fill
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__ specifying the window to
+ be lowered.
-**Returned Value:** ``OK`` on success; ``ERROR`` on failure with
-``errno`` set appropriately
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
-2.4.27 ``nxtk_drawlinetoolbar()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. c:function:: int nxtk_modal(NXWINDOW hwnd, bool modal);
-**Function Prototype:**
+ May be used to either (1) raise a window to the top of
+ the display and select modal behavior, or (2) disable modal behavior.
-**Description:** Fill the specified line in the toolbar sub-window with
-the specified color. This is simply a wrapper that uses
-``nxgl_splitline()`` to break the line into trapezoids and then calls
-``nxtk_filltraptoolbar()`` to render the line.
+ :param hwnd:
+ The handle returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__
+ specifying the window to be modified.
+ :param modal:
+ True: enter modal state; False: leave modal state
-**Input Parameters:**
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
-``hfwnd``
- A handle previously returned by
- ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
-``vector``
- Describes the line to be drawn.
-``width``
- The width of the line
-``color``
- The color to use to fill the line
-``caps``
- Draw a circular cap on the ends of the line to support better line
- joins. One of:
-
-**Returned Value:** ``OK`` on success; ``ERROR`` on failure with
-``errno`` set appropriately
-
-2.4.28 ``nxtk_drawcircletoolbar()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Function Prototype:**
-
-**Description:** Draw a circular outline using the specified line
-thickness and color.
-
-**Input Parameters:**
-
-``hfwnd``
- A handle previously returned by
- ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
-``center``
- A pointer to the point that is the center of the circle.
-``radius``
- The radius of the circle in pixels.
-``width``
- The width of the line
-``color``
- The color to use to fill the line
-
-**Returned Value:** ``OK`` on success; ``ERROR`` on failure with
-``errno`` set appropriately
-
-2.4.29 ``nxtk_fillcircletoolbar()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Function Prototype:**
-
-**Description:** Fill a circular region using the specified color.
-
-**Input Parameters:**
-
-``hfwnd``
- A handle previously returned by
- ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
-``center``
- A pointer to the point that is the center of the circle.
-``radius``
- The width of the line
-``color``
- The color to use to fill the circle
-
-**Returned Value:** ``OK`` on success; ``ERROR`` on failure with
-``errno`` set appropriately
+.. c:function:: int nxtk_setvisibility(NXWINDOW hwnd, bool hide);
-2.4.30 ``nxtk_movetoolbar()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Function Prototype:**
-
-**Description:** Move a rectangular region within the toolbar sub-window
-of a framed window.
-
-**Input Parameters:**
-
-``hfwnd``
- A handle identifying sub-window containing the toolbar within which
- the move is to be done. This handle must have previously been
- returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
-``rect``
- Describes the rectangular region relative to the toolbar sub-window
- to move.
-``offset``
- The offset to move the region
-
-**Returned Value:** ``OK`` on success; ``ERROR`` on failure with
-``errno`` set appropriately
-
-2.4.31 ``nxtk_bitmaptoolbar()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Function Prototype:**
-
-**Description:** Copy a rectangular region of a larger image into the
-rectangle in the specified toolbar sub-window.
-
-**Input Parameters:**
-
-``hfwnd``
- A handle previously returned by
- ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
-``dest``
- Describes the rectangular region on in the toolbar sub-window will
- receive the bit map.
-``src``
- The start of the source image.
-``origin``
- The origin of the upper, left-most corner of the full bitmap. Both
- dest and origin are in sub-window coordinates, however, the origin
- may lie outside of the sub-window display.
-``stride``
- The width of the full source image in bytes.
+ Select if the window is visible or hidden. A hidden
+ window is still present and will update normally, but will not be
+ visible on the display until it is unhidden.
-**Returned Value:** ``OK`` on success; ``ERROR`` on failure with
-``errno`` set appropriately
+ :param hwnd:
+ The handle returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__
+ specifying the window to be modified.
+ :param hide:
+ True: Window will be hidden; false: Window will be visible
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: bool nxtk_ishidden(NXTKWINDOW hfwnd);
+
+ Return true if the window is hidden.
+
+ **NOTE**: There will be a delay between the time that the visibility of
+ the window is changed via
+ ```nxtk_setvisibily()`` <#nxtksetvisibility>`__ before that new setting
+ is reported by ``nxtk_ishidden()``. ``nxtk_synch()`` may be used if
+ temporal synchronization is required.
+
+ :param hfwnd:
+ The handle returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__
+ that identifies the window to be queried.
+
+ :return: *True*: the window is hidden, *false*: the window is
+ visible
+
+.. c:function:: int nxtk_fillwindow(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect, \
+ nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
+
+ Fill the specified rectangle in the client window with
+ the specified color.
+
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
+ :param rect:
+ The location within the client window to be filled
+ :param color:
+ The color to use in the fill
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: void nxtk_getwindow(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect, \
+ unsigned int plane, FAR uint8_t *dest, \
+ unsigned int deststride);
+
+ Get the raw contents of graphic memory within a
+ rectangular region. NOTE: Since raw graphic memory is returned, the
+ returned memory content may be the memory of windows above this one and
+ may not necessarily belong to this window unless you assure that this is
+ the top window.
+
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
+ :param rect:
+ The location within the client window to be retrieved.
+ :param plane:
+ Specifies the color plane to get from.
+ :param dest:
+ The location to copy the memory region
+ :param deststride:
+ The width, in bytes, of the dest memory
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nxtk_filltrapwindow(NXTKWINDOW hfwnd, \
+ FAR const struct nxgl_trapezoid_s *trap, \
+ nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
+
+ Fill the specified trapezoid in the client window with
+ the specified color
+
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
+ :param trap:
+ The trapezoidal region to be filled.
+ :param color:
+ The color to use in the fill.
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nxtk_drawlinewindow(NXTKWINDOW hfwnd, FAR struct nxgl_vector_s *vector, \
+ nxgl_coord_t width, nxgl_mxpixel_t color[CONFIG_NX_NPLANES], \
+ uint8_t caps);
+
+ Fill the specified trapezoidal region in the window
+ with the specified color. Fill the specified line in the window with the
+ specified color. This is simply a wrapper that uses ``nxgl_splitline()``
+ to break the line into trapezoids and then calls
+ ``nxtk_filltrapwindow()`` to render the line.
+
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
+ :param vector:
+ Describes the line to be drawn.
+ :param width:
+ The width of 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
+ joins. One of:
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nxtk_drawcirclewindow(NXTKWINDOW hfwnd, FAR const struct nxgl_point_s *center, \
+ nxgl_coord_t radius, nxgl_coord_t width, \
+ nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
+
+ Draw a circular outline using the specified line
+ thickness and color.
+
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
+ :param center:
+ A pointer to the point that is the center of the circle.
+ :param radius:
+ The radius of the circle in pixels.
+ :param width:
+ The width of the line
+ :param color:
+ The color to use to fill the line
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nxtk_fillcirclewindow(NXWINDOW hfwnd, FAR const struct nxgl_point_s *center, \
+ nxgl_coord_t radius, nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
+
+ Fill a circular region using the specified color.
+
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
+ :param center:
+ A pointer to the point that is the center of the circle.
+ :param radius:
+ The width of the line
+ :param color:
+ The color to use to fill the circle
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nxtk_movewindow(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect, \
+ FAR const struct nxgl_point_s *offset);
+
+ Move a rectangular region within the client sub-window
+ of a framed window.
+
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__ specifying the client
+ sub-window within which the move is to be done.
+ :param rect:
+ Describes the rectangular region relative to the client sub-window to
+ move.
+ :param offset:
+ The offset to move the region
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nxtk_bitmapwindow(NXTKWINDOW hfwnd, \
+ FAR const struct nxgl_rect_s *dest, \
+ FAR const void *src[CONFIG_NX_NPLANES], \
+ FAR const struct nxgl_point_s *origin, \
+ unsigned int stride);
+
+ Copy a rectangular region of a larger image into the
+ rectangle in the specified client sub-window.
+
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__ specifying the client
+ sub-window that will receive the bitmap.
+ :param dest:
+ Describes the rectangular region on in the client sub-window will
+ receive the bit map.
+ :param src:
+ The start of the source image(s). This is an array source images of
+ size ``CONFIG_NX_NPLANES`` (probably 1).
+ :param origin:
+ The origin of the upper, left-most corner of the full bitmap. Both
+ dest and origin are in sub-window coordinates, however, the origin
+ may lie outside of the sub-window display.
+ :param stride:
+ The width of the full source image in pixels.
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nxtk_opentoolbar(NXTKWINDOW hfwnd, nxgl_coord_t height, \
+ FAR const struct nx_callback_s *cb, \
+ FAR void *arg);
+
+
+ Create a tool bar at the top of the specified framed
+ window.
+
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
+ :param height:
+ The requested height of the toolbar in pixels.
+ :param cb:
+ Callbacks used to process toolbar events.
+ :param arg:
+ User provided value that will be returned with toolbar callbacks.
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nxtk_closetoolbar(NXTKWINDOW hfwnd);
+
+ Remove the tool bar at the top of the specified framed
+ window.
+
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nxtk_filltoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect, \
+ nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
+
+
+ Fill the specified rectangle in the toolbar sub-window
+ with the specified color.
+
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
+ :param rect:
+ The location within the toolbar window to be filled.
+ :param color:
+ The color to use in the fill.
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nxtk_gettoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect, \
+ unsigned int plane, FAR uint8_t *dest, \
+ unsigned int deststride);
+
+
+ Get the raw contents of graphic memory within a
+ rectangular region. NOTE: Since raw graphic memory is returned, the
+ returned memory content may be the memory of windows above this one and
+ may not necessarily belong to this window unless you assure that this is
+ the top window.
+
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
+ :param rect:
+ The location within the toolbar window to be retrieved.
+ :param plane:
+ TSpecifies the color plane to get from.
+ :param dest:
+ TThe location to copy the memory region.
+ :param deststride:
+ The width, in bytes, of the dest memory.
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nxtk_filltraptoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_trapezoid_s *trap, \
+ nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
+
+ Fill the specified trapezoid in the toolbar sub-window
+ with the specified color.
+
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
+ :param trap:
+ The trapezoidal region to be filled
+ :param color:
+ The color to use in the fill
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nxtk_drawlinetoolbar(NXTKWINDOW hfwnd, FAR struct nxgl_vector_s *vector, \
+ nxgl_coord_t width, nxgl_mxpixel_t color[CONFIG_NX_NPLANES], \
+ uint8_t caps);
+
+
+ Fill the specified line in the toolbar sub-window with
+ the specified color. This is simply a wrapper that uses
+ ``nxgl_splitline()`` to break the line into trapezoids and then calls
+ ``nxtk_filltraptoolbar()`` to render the line.
+
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
+ :param vector:
+ Describes the line to be drawn.
+ :param width:
+ The width of 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
+ joins. One of:
+
+ .. code-block:: c
+
+ /* Line caps */
+
+ #define NX_LINECAP_NONE 0x00, /* No line caps */
+ #define NX_LINECAP_PT1 0x01 /* Line cap on pt1 on of the vector only */
+ #define NX_LINECAP_PT2 0x02 /* Line cap on pt2 on of the vector only */
+ #define NX_LINECAP_BOTH 0x03 /* Line cap on both ends of the vector only */
+
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nxtk_drawcircletoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_point_s *center, \
+ nxgl_coord_t radius, nxgl_coord_t width, \
+ nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
+
+ Draw a circular outline using the specified line
+ thickness and color.
+
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
+ :param center:
+ A pointer to the point that is the center of the circle.
+ :param radius:
+ The radius of the circle in pixels.
+ :param width:
+ The width of the line
+ :param color:
+ The color to use to fill the line
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nxtk_fillcircletoolbar(NXWINDOW hfwnd, FAR const struct nxgl_point_s *center, \
+ nxgl_coord_t radius, nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
+
+ Fill a circular region using the specified color.
+
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
+ :param center:
+ A pointer to the point that is the center of the circle.
+ :param radius:
+ The width of the line
+ :param color:
+ The color to use to fill the circle
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nxtk_movetoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect, \
+ FAR const struct nxgl_point_s *offset);
+
+ Move a rectangular region within the toolbar sub-window
+ of a framed window.
+
+ :param hfwnd:
+ A handle identifying sub-window containing the toolbar within which
+ the move is to be done. This handle must have previously been
+ returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
+ :param rect:
+ Describes the rectangular region relative to the toolbar sub-window
+ to move.
+ :param offset:
+ The offset to move the region
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nxtk_bitmaptoolbar(NXTKWINDOW hfwnd, \
+ FAR const struct nxgl_rect_s *dest, \
+ FAR const void *src[CONFIG_NX_NPLANES], \
+ FAR const struct nxgl_point_s *origin, \
+ unsigned int stride);
+
+ Copy a rectangular region of a larger image into the
+ rectangle in the specified toolbar sub-window.
+
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
+ :param dest:
+ Describes the rectangular region on in the toolbar sub-window will
+ receive the bit map.
+ :param src:
+ The start of the source image.
+ :param origin:
+ The origin of the upper, left-most corner of the full bitmap. Both
+ dest and origin are in sub-window coordinates, however, the origin
+ may lie outside of the sub-window display.
+ :param stride:
+ The width of the full source image in bytes.
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
.. _nx-fonts-support-nxfonts-1:
[incubator-nuttx] 14/17: fix wrong "todo" placement
Posted by bt...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
btashton pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
commit 911cc3f0ea66b52cca7e7463120cadb88bde0662
Author: Matias N <ma...@protobits.dev>
AuthorDate: Mon Aug 17 12:29:21 2020 -0300
fix wrong "todo" placement
---
Documentation/contributing/documentation.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/contributing/documentation.rst b/Documentation/contributing/documentation.rst
index de92c16..10063ea 100644
--- a/Documentation/contributing/documentation.rst
+++ b/Documentation/contributing/documentation.rst
@@ -39,7 +39,7 @@ go into ``Documentation`` directory. Then,
$ # activate the virtual environent
$ pipenv shell
- .. todo:: check that Pipfile.lock is up to date w.r.t. requirements.txt
+ .. todo:: check that Pipfile.lock is up to date w.r.t. requirements.txt
2. Build documentation:
[incubator-nuttx] 10/17: complete improving presentation of sections
Posted by bt...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
btashton pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
commit 76637cbf320db5ab5d2bc39fc76589b0f5314422
Author: Matias N <ma...@protobits.dev>
AuthorDate: Sat Aug 15 18:19:19 2020 -0300
complete improving presentation of sections
---
Documentation/contributing/index.rst | 8 +++-----
Documentation/releases/index.rst | 2 +-
2 files changed, 4 insertions(+), 6 deletions(-)
diff --git a/Documentation/contributing/index.rst b/Documentation/contributing/index.rst
index 11c7e6e..a69411b 100644
--- a/Documentation/contributing/index.rst
+++ b/Documentation/contributing/index.rst
@@ -1,15 +1,13 @@
Contributing
============
+In the following sections you will find important information on how to contribute to NuttX codebase (from small bugfixes to large new features)
+and documentation (the one you are reading now):
+
.. toctree::
:maxdepth: 2
- :hidden:
- :caption: Contents:
workflow.rst
coding_style.rst
documentation.rst
-.. note::
- Brief description on how contributing to NuttX works (GitHub, PRs), which documents should be read
- before the first contribution (coding style, etc). Brief description on how to participate more closely in NuttX project (commiter, PMC member).
diff --git a/Documentation/releases/index.rst b/Documentation/releases/index.rst
index 250fdbe..e83e335 100644
--- a/Documentation/releases/index.rst
+++ b/Documentation/releases/index.rst
@@ -1,6 +1,6 @@
Releases
========
-.. note::
+.. todo::
This should link (or include?) release notes. Maybe only show some recent ones and link
older ones
[incubator-nuttx] 01/17: sphinx doc
Posted by bt...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
btashton pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
commit 5e1dab36c685f81969b6d482bf36c0c34295762c
Author: Matias N <ma...@protobits.dev>
AuthorDate: Mon Jul 20 19:18:26 2020 -0300
sphinx doc
---
.github/workflows/build.yml | 4 +
.github/workflows/check.yml | 2 +
.github/workflows/doc.yml | 2 +
.github/workflows/sphinx-docs.yml | 56 +
Documentation/NuttXCCodingStandard.html | 3127 -----------------
Documentation/NuttXGettingStarted.html | 25 -
Documentation/README.html | 649 ----
Documentation/backgd.gif | Bin 1097 -> 0 bytes
Documentation/redirect.html | 20 -
doc/.gitignore | 1 +
doc/Makefile | 22 +
doc/Pipfile | 14 +
doc/Pipfile.lock | 244 ++
doc/_static/custom.css | 25 +
doc/_static/favicon.ico | Bin 0 -> 4286 bytes
doc/applications/index.rst | 6 +
doc/boards/index.rst | 8 +
doc/components/binfmt.rst | 372 ++
doc/components/drivers/index.rst | 941 ++++++
doc/components/filesystem.rst | 43 +
doc/components/index.rst | 20 +
doc/components/nsh/builtin.rst | 204 ++
doc/components/nsh/commands.rst | 1692 ++++++++++
doc/components/nsh/config.rst | 486 +++
doc/components/nsh/customizing.rst | 213 ++
doc/components/nsh/index.rst | 18 +
doc/components/nsh/installation.rst | 187 ++
doc/components/nsh/login.rst | 261 ++
doc/components/nsh/nsh.rst | 361 ++
doc/components/nxflat.rst | 469 +++
.../components/nxgraphics}/NXOrganization.gif | Bin
.../components/nxgraphics}/NuttXScreenShot.jpg | Bin
doc/components/nxgraphics/appendix.rst | 657 ++++
doc/components/nxgraphics/index.rst | 174 +
doc/components/nxgraphics/nx.rst | 742 ++++
doc/components/nxgraphics/nxcursor.rst | 50 +
doc/components/nxgraphics/nxfonts.rst | 127 +
doc/components/nxgraphics/nxgl.rst | 259 ++
doc/components/nxgraphics/nxtk.rst | 732 ++++
doc/components/nxgraphics/sample.rst | 30 +
doc/components/nxwidgets.rst | 59 +
doc/components/paging.rst | 423 +++
{Documentation => doc/components}/pm.png | Bin
doc/components/power.rst | 241 ++
doc/components/syslog.rst | 511 +++
doc/conf.py | 85 +
doc/contributing/coding_style.rst | 2656 +++++++++++++++
doc/contributing/documentation.rst | 170 +
doc/contributing/index.rst | 15 +
doc/contributing/workflow.rst | 7 +
doc/guides/index.rst | 8 +
doc/guides/nfs.rst | 285 ++
doc/guides/usbtrace.rst | 214 ++
doc/index.rst | 30 +
doc/introduction/about.rst | 277 ++
doc/introduction/detailed_support.rst | 3536 ++++++++++++++++++++
doc/introduction/development_environments.rst | 153 +
doc/introduction/index.rst | 17 +
doc/introduction/licensing.rst | 9 +
doc/introduction/resources.rst | 23 +
doc/introduction/supported_platforms.rst | 430 +++
doc/introduction/trademarks.rst | 30 +
doc/make.bat | 35 +
doc/quickstart/config_build.rst | 131 +
doc/quickstart/index.rst | 15 +
doc/quickstart/organization.rst | 501 +++
doc/reference/index.rst | 14 +
doc/reference/os/addrenv.rst | 305 ++
doc/reference/os/app_vs_os.rst | 103 +
doc/reference/os/arch.rst | 329 ++
doc/reference/os/board.rst | 74 +
doc/reference/os/boardctl.rst | 40 +
doc/reference/os/conventions.rst | 101 +
doc/reference/os/index.rst | 25 +
doc/reference/os/iob.rst | 310 ++
doc/reference/os/led.rst | 122 +
doc/reference/os/nuttx.rst | 50 +
doc/reference/os/paging.rst | 13 +
doc/reference/os/shm.rst | 38 +
doc/reference/os/smp.rst | 99 +
doc/reference/os/time_clock.rst | 660 ++++
doc/reference/os/wqueue.rst | 307 ++
doc/reference/user/01_task_control.rst | 887 +++++
doc/reference/user/02_task_scheduling.rst | 180 +
doc/reference/user/03_task_control.rst | 458 +++
doc/reference/user/04_message_queue.rst | 375 +++
doc/reference/user/05_counting_semaphore.rst | 455 +++
doc/reference/user/06_clocks_timers.rst | 360 ++
doc/reference/user/07_signals.rst | 514 +++
doc/reference/user/08_pthread.rst | 1710 ++++++++++
doc/reference/user/09_env_vars.rst | 95 +
doc/reference/user/10_filesystem.rst | 573 ++++
doc/reference/user/11_network.rst | 417 +++
doc/reference/user/12_shared_memory.rst | 202 ++
doc/reference/user/index.rst | 28 +
doc/reference/user/structures.rst | 169 +
doc/releases/index.rst | 6 +
doc/requirements.txt | 3 +
doc/substitutions.rst | 5 +
99 files changed, 27310 insertions(+), 3821 deletions(-)
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index a20e7db..cf00065 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -14,7 +14,11 @@ name: Build
on:
pull_request:
+ paths-ignore:
+ - 'doc/**'
push:
+ paths-ignore:
+ - 'doc/**'
branches:
- master
- 'releases/*'
diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml
index 9f031bf..9241135 100644
--- a/.github/workflows/check.yml
+++ b/.github/workflows/check.yml
@@ -14,6 +14,8 @@ name: Check
on:
pull_request:
+ paths-ignore:
+ - 'doc/**'
jobs:
check:
diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index ead2d42..c32f707 100644
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -14,6 +14,8 @@ name: Doc
on:
pull_request:
+ paths:
+ - 'docs/**'
jobs:
docs:
diff --git a/.github/workflows/sphinx-docs.yml b/.github/workflows/sphinx-docs.yml
new file mode 100644
index 0000000..b324527
--- /dev/null
+++ b/.github/workflows/sphinx-docs.yml
@@ -0,0 +1,56 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+name: "Build Sphinx Docs"
+on:
+ pull_request:
+ push:
+ branches:
+ - master
+ - docs
+ - 'releases/*'
+ tags:
+
+jobs:
+ docs:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v1
+ - uses: ammaraskar/sphinx-action@master
+ with:
+ docs-folder: "doc/"
+ - uses: actions/upload-artifact@v2
+ with:
+ name: sphinx-docs
+ path: doc/_build/html/
+ - name: Commit documentation changes
+ if: github.event_name != 'pull_request'
+ run: |
+ git clone https://github.com/v01d/incubator-nuttx.git --branch gh-pages --single-branch gh-pages
+ cd gh-pages
+ rm -rf ${GITHUB_REF##*/}
+ mkdir -p ${GITHUB_REF##*/}
+ cd ${GITHUB_REF##*/}
+ cp -r ../../doc/_build/html/* .
+ git config --local user.email "action@github.com"
+ git config --local user.name "GitHub Action"
+ git add .
+ git commit -m "Update documentation" -a || true
+ # The above command will fail if no changes were present, so we ignore
+ # the return code.
+ - name: Push changes
+ if: github.event_name != 'pull_request'
+ uses: ad-m/github-push-action@master
+ with:
+ branch: gh-pages
+ directory: gh-pages
+ github_token: ${{ secrets.GITHUB_TOKEN }}
diff --git a/Documentation/NuttXCCodingStandard.html b/Documentation/NuttXCCodingStandard.html
deleted file mode 100644
index 02c835b..0000000
--- a/Documentation/NuttXCCodingStandard.html
+++ /dev/null
@@ -1,3127 +0,0 @@
-<html>
-<head>
-<title>NuttX C Coding Standard</title>
-<meta name="author" content="Gregory Nutt">
-<link rel="stylesheet" href="style.css">
-</head>
-
-<body>
-<div class="container">
-<div class="toc">
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <h1>Table of Contents</h1>
- </td>
- </tr>
-</table>
-
-<ul>
- <p>
- <b>1.0 <a href="#general">General Conventions</a></b>
- </p>
- <ul>
- 1.1 <a href="#fileorganization">File Organization</a></br>
- 1.2 <a href="#lines">Lines</a><br>
- 1.3 <a href="#comments">Comments</a><br>
- 1.4 <a href="#braces">Braces</a><br>
- 1.5 <a href="#indentation">Indentation</a><br>
- 1.6 <a href="#parentheses">Parentheses</a><br>
- </ul>
- <p>
- <b>2.0 <a href="#datatypes">Data and Type Definitions</a></b>
- </p>
- <ul>
- 2.1 <a href="#onedatperline">One Definition/Declaration Per Line</a><br>
- 2.2 <a href="#globalvariable">Global Variables</a><br>
- 2.3 <a href="#localvariable">Parameters and Local Variables</a><br>
- 2.4 <a href="#typedefinitions">Type Definitions</a><br>
- 2.5 <a href="#structures">Structures</a><br>
- 2.6 <a href="#unions">Unions</a><br>
- 2.7 <a href="#enumerations">Enumerations</a><br>
- 2.8 <a href="#macros">C Pre-processor Macros</a><br>
- 2.9 <a href="#pointers">Pointer Variables</a><br>
- 2.10 <a href="#initializers">Initializers</a>
- </ul>
- <p>
- <b>3.0 <a href="#functions">Functions</a></b>
- </p>
- <ul>
- 3.1 <a href="#funcheaders">Function Headers</a><br>
- 3.2 <a href="#funcname">Function Names</a><br>
- 3.3 <a href="#parmlists">Parameter Lists</a><br>
- 3.4 <a href="#funcbody">Function Body</a><br>
- 3.5 <a href="#retvalues">Returned Values</a>
- </ul>
- <p>
- <b>4.0 <a href="#statements">Statements</a></b>
- </p>
- <ul>
- 4.1 <a href="#onestatement">One Statement Per Line</a><br>
- 4.2 <a href="#casts">Casts</a><br>
- 4.3 <a href="#operators">Operators</a><br>
- 4.4 <a href="#ifthenelse"><code>if then else</code> Statement</a><br>
- 4.5 <a href="#switch"><code>switch</code> Statement</a><br>
- 4.6 <a href="#while"><code>while</code> Statement</a><br>
- 4.7 <a href="#dowhile"><code>do while</code> Statement</a><br>
- 4.8 <a href="#goto">Use of <code>goto</code></a>
- </ul>
- <p>
- <b>5.0 <a href="#cplusplus">C++</a></b>
- </p>
- <p>
- <b><a href="#appndxa">Appendix A</a></b>
- </p>
- <ul>
- <a href="#cfilestructure">A.1 C Source File Structure</a><br>
- <a href="#hfilestructure">A.2 C Header File Structure</a>
- </ul>
-</ul>
-</div>
-
-<div class="main">
-<hr><hr>
-<table width ="100%">
- <tr align="center" bgcolor="#e4e4e4">
- <td>
- <h1><big><font color="#3c34ec">
- <i>NuttX C Coding Standard</i>
- </font></big></h1>
- <p>Last Updated: May 19, 2020</p>
- </td>
- </tr>
-</table>
-<hr><hr>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <h1>1.0 <a name="general">General Conventions</a></h1>
- </td>
- </tr>
-</table>
-
-<h2>1.1 <a name="fileorganization">File Organization</a></h2>
-
-<p>
- <b>File Extensions</b>
- Use the <code>.h</code> extension for C header files and <code>.c </code> for C source files.
-</p>
-<p>
- <b>File header</b>.
- Every C, C++, make file, or script begins with a file header.
- That file header is enclosed with a <i>block comment</i> (see below).
- Within the block comment, the following must appear:
-</p>
-<ul>
- <li>
- The relative path to the file from the top-level directory.
- </li>
- <li>
- An optional, one-line description of the file contents.
- </li>
- <li>
- A blank line
- </li>
- <li>
- A copyright notice indented two additional spaces
- </li>
- <li>
- A line identifying the author and contact information with the same indentation as the copyright notice.
- </li>
- <li>
- A blank line</li>
- <li>
- NuttX standard Apache 2.0 licensing information as provided in the <a href="#appndxa">appendix</a>.
- </li>
-</ul>
-<p>
- <b>Sample File Headers</b>.
- Sample file headers are provided in an <a href="#appndxa">Appendix</a> to this document.
- No new software may be included in the NuttX source tree that does not have licensing information included in the file.
- No new software may be included in the NuttX source tree that does not have a Apache 2.0 license or license (or, in the case of 3rd party file, a compatible license such as the BSD or MIT licenses).
- If the file does not follow Apache 2.0 licensing, then the appropriate license information should be provided in the header rather than the Apache 2.0 licensing information and a NOTE should be included in the top-level <code>COPYING</code> file to indicate any variations from Apache 2.0 licensing.
-</p>
-<p>
- <b>Grouping</b>.
- All like components in a C source or header file are grouped together.
- Definitions do not appear arbitrarily through the file, rather, like definitions are grouped together and preceded by a <i>block comment</i> identifying the grouping.
-</p>
-<p>
- <b>Block Comments</b>.
- Each grouping in the file is separated with a <i>block comment</i>.
- The block comment consists of:
-</p>
-<ul>
- <li>
- A line that consists of the opening C comment (<code>/*</code>) followed by a series of asterisks extending to the length of the line (usually to column 78).
- </li>
- <li>
- The name of the grouping, starting at column 4.
- An asterisk preceives the name of the grouping in column 1.
- </li>
- <li>
- A line that consists of the closing C comment (<code>*/</code>) at the end of the line (usually column 78) preceded by a series of asterisks extending to column 1.
- </li>
-</ul>
-<p>
- <b>Examples of Block Comments</b>.
- See <a href="#appndxa">Appendix A</a> for examples of block comments.
-</p>
-<p>
- <b>Order of Groupings</b>.
- The following groupings should appear in all C source files in the following order:
-</p>
-<ol>
- <li>
- Included Files
- </li>
- <li>
- Pre-processor Definitions
- </li>
- <li>
- Private Types (definitions)
- </li>
- <li>
- Private Function Prototypes (declarations)
- </li>
- <li>
- Private Data (definitions)
- </li>
- <li>
- Public Data (definitions)
- </li>
- <li>
- Private Functions (definitions)
- </li>
- <li>
- Public Functions (definitions)
- </li>
-</ol>
-<p>
- The following groupings should appear in all C header files in the following order:
-</p>
-<ol>
- <li>
- Included Files
- </li>
- <li>
- Pre-processor Definitions
- </li>
- <li>
- Public Types (definitions)
- </li>
- <li>
- Public Data (declarations)
- </li>
- <li>
- Inline Functions (definitions)
- </li>
- <li>
- Public Function Prototypes (declarations)
- </li>
-</ol>
-<p>
- <b>Large vs. Small Files</b>.
- In larger files, block comments should be included for all groupings, even if they are empty;
- the empty grouping provides important information in itself.
- Smaller files may omit some of the block comments;
- it is awkard if the block comments are larger than the file content!
-</p>
-<p>
- <a name="idempotence"><b>Header File Idempotence</b></a>.
- C header file must protect against multiple inclusion through the use of macros that "guard" against multiple definitions if the header file is included multiple times.
-</p>
-<ul>
- <li>
- <p>
- Each header file must contain the following pre-processor conditional logic near the beginning of the header file: Between the file header and the "Included Files" block comment.
- For example,
- </p>
- <ul><pre>
-#ifndef __INCLUDE_NUTTX_ARCH_H
-#define __INCLUDE_NUTTX_ARCH_H
-</pre></ul>
- <p>
- Notice that the definitions within of the header do not follow the usually rules:
- The presence of the conditional test at the top of the file does not cause the
- remaining definitions within the file to be indented.
- </p>
- </li>
- <li>
- <p>
- Then conditional compilation is closed at the fine line of the header file with:
- </p>
- <ul><pre>
-#endif /* __INCLUDE_NUTTX_ARCH_H */
-</pre></ul>
- </li>
-</ul>
-<p>
- <b>Forming Guard Names</b>.
- Then pre-processor macro name used in the guard is formed from the full, relative path to the header for from the top-level, controlled directory.
- That path is preceded by <code>__</code> and <code>_</code> replaces each character that would otherwise be invalid in a macro name.
- So, for example, __INCLUDE_NUTTX_ARCH_H corresponds to the header file <code>include/nuttx/arch.h</code>
-</p>
-
-<p>
- <b>Deoxygen Information</b>.
- NuttX does not use Deoxygen for documentation and no file should contain Doxygen tags or Doxygen style comments.
-</p>
-
-<p>
- <b>Sample File Formats</b>.
- C source and header file templates are provided in an <a href="#appndxa">Appendix</a> to this document.
-</p>
-
-<h2>1.2 <a name="lines">Lines</a></h2>
-<p>
- <b>Line Endings</b>.
- Files should be formatted with the newline character (<code>\n</code>) as the line ending (Unix-style line endings) and specifically <i>not</i> the carriage return, newline sequence (<code>\r\n</code>) used with Windows-style line endings.
- There should be no extra whitespace at the end of the line.
- In addition, all text files should end in a single newline (<code>\n</code>). This avoids the <i>"No newline at end of file"</i> warning generated by certain tools.
-</p>
-
-<p>
- <b>Line Width</b>.
- Text should not extend past column 78 in the typical C source or header file.
- Sometimes the nature of the content of a file may require that the lines exceed this limit.
- This often occurs in header files with naturally long definitions.
- If the line width must extend 78 lines, then some wider line width may be used in the file provided that it is used consistently.
-</p>
-
-<p>
- <b>Line Wrapping</b>.
-</p>
-<center><table width="100%" border=1>
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
- struct some_long_struct_name_s
- {
- struct some_long_struct_name_s *flink; /* The forward link to the next instance of struct some_long_struct_name_s in a singly linked list */
- int short_name1; /* Short comment 1 */
- int short_name2; /* This is a very long comment describing subtle aspects of the short_name2 field */
- };
-
- struct some_medium_name_s *ptr = (struct some_medium_name_s *)malloc(sizeof(some_medium_name_s);
-
- struct some_long_struct_name_s *ptr = (struct some_long_struct_name_s *)malloc(sizeof(some_long_struct_name_s);
-
- ret = some_function_with_many parameters(long_parameter_name_1, long_parameter_name_2, long_parameter_name_3, long_parameter_name_4, long_parameter_name_5, long_parameter_name_6, long_parameter_name_7, long_parameter_name_8);
-
- ret = some_function_with_many parameters(long_parameter_name_1,
- long_parameter_name_2,
- long_parameter_name_3
- long_parameter_name_4,
- long_parameter_name_5,
- long_parameter_name_6,
- long_parameter_name_7,
- long_parameter_name_8);
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Correct</b></p>
-<ul><pre>
- struct some_long_struct_name_s
- {
- /* The forward link to the next instance of struct
- * some_long_struct_name_s in a singly linked list.
- */
-
- struct some_long_struct_name_s *flink;
- int short_name1; /* Short comment 1. */
- int short_name2; /* This is a very long comment describing subtle
- * aspects of the short_name2 field. */
- };
-
- FAR struct some_medium_name_s *ptr = (FAR struct some_medium_name_s *)
- malloc(sizeof(some_medium_name_s);
-
- FAR struct some_medium_name_s *ptr =
- (FAR struct some_medium_name_s *)malloc(sizeof(some_medium_name_s);
-
- FAR struct some_long_struct_name_s *ptr =
- (FAR struct some_long_struct_name_s *)
- malloc(sizeof(some_long_struct_name_s);
-
- ret = some_function_with_many parameters(long_parameter_name_1,
- long_parameter_name_2,
- long_parameter_name_3,
- long_parameter_name_4,
- long_parameter_name_5,
- long_parameter_name_6,
- long_parameter_name_7,
- long_parameter_name_8);
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<p>
- <b>NOTE</b>:
- See the discussion of <a href="#farnear">pointers</a> for information about the <code>FAR</code> qualifier used above.
-</p>
-
-<p>
- <b>Double Spacing</b>.
- A single blank line may be use to separate logical groupings as the designer feels fit.
- Single blank lines are also required in certain contexts as defined in this standard.
- Additional blanks lines (two or more) are prohibited.
-</p>
-
-<p>
- <b>Columnar Organization</b>.
- Similar things should be aligned on the same column unless doing so would cause the line width to be exceeded.
-</p>
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="blue"><b>Acceptable</b></p>
-<ul><pre>
- dog = cat;
- monkey = oxen;
- aardvark = macaque;
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Preferred</b></p>
-<ul><pre>
- dog = cat;
- monkey = oxen;
- aardvark = macaque;
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<p>
- <b>Block Comments</b>
- The final asterisk (<code>*</code>) should occur at column 78 (or the line width of files with longer lines).
- Note that the final comment delimiter of the block comment is an exception an lies at column 79.
-</p>
-
-<h2><a name="comments">1.3 Comments</a></h2>
-
-<p>
- <b>General</b>.
- Within a comment, the text must be standard English conforming to standard English rules of grammar and spelling (US English spelling).
- Of course, this is not the place to summarize all English grammar, but as examples of common grammatic issues in comments:
-</p>
-<ul>
- <li>
- All sentences should begin with an upper-case character and end with either '.', '?', or '!'.
- </li>
- <li>
- Sentence fragments and phrases are generally treated the same as sentences.
- </li>
- <li>
- The punctuation '.' and ':' is followed by two spaces; the punctuation ',' and ';' is followed by a single space.
- </li>
- <li>
- Text following '.' or ':' begins with an upper-case character;
- text following ',' or ';' begins with a lower-case character.
- </li>
-</ul>
-<p>
- <b>Line Spacing</b>
- A single blank line should precede and follow each comment.
- The only exceptions are:
-</p>
-<ol>
- <li>
- For the file header block comment that begins on line one;
- there is no preceding blank line in that case.
- <li>
- For conditional compilation.
- Conditional compilation should include the conditional logic <i>and</i> all comments associated with the conditional logic.
- In this case, the blank line appears <i>before</i> the conditional, not after it.
- No blank lines precede any comments following the conditional.
- </li>
- <li>
- With braces.
- No blank line separates the line containing the opening left brace from a comment.
- No blank line follows a comment that may be the final line preceding a closing right brace.
- </li>
- <li>
- With Labels.
- No blank line separates the line containing the label from a comment.
- </li>
-</p>
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
- /* set a equal to b */
- a = b;
- /* set b equal to c */
- b = c;
-
- /* Do the impossible */
-
-#ifdef CONFIG_THE_IMPOSSIBLE
- the_impossible();
-#endif
-
- if (a == b)
- {
-
- /* Only a comment */
-
- }
-
- here:
-
- /* This is the place */
-
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Correct</b></p>
-<ul><pre>
-
- /* Set a equal to b. */
-
- a = b;
-
- /* Set b equal to c. */
-
- b = c;
-
-#ifdef CONFIG_THE_IMPOSSIBLE
- /* Do the impossible */
-
- the_impossible();
-#endif
-
- if (a == b)
- {
- /* Only a comment */
- }
-
- here:
- /* This is the place */
-
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<p>
- <b>Indentation</b>
- Comments should, typically, be placed before the code section to which they apply.
- The comment indentation should be the same as the follow indentation rules as the following code (if applicable).
-</p>
-
-<p>
- <b>Short, Single line comments</b>.
- Short comments must lie on a single line.
- The comment delimiters must lie on the same line.
-</p>
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
- /*
- * This is a single line comment
- */
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Correct</b></p>
-<ul><pre>
- /* This is a single line comment. */
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<p>
- <b>Multi-line comments</b>.
- If the comment is too long to fit on a single, it must be broken into a multi-line comment.
- The comment must be begin on the first line of the multi-line comment with the opening comment delimiter (<code>/*</code>).
- The following lines of the multi-line comment must be with an asterisk (<code>*</code>) aligned in the same column as the asterisk in the preceding line.
- The closing comment delimiter must lie on a separate line with the asterisk (<code>*</code>) aligned in the same column as the asterisk in the preceding line.
-</p>
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
- /*
- This is the first line of a multi-line comment.
- This is the second line of a multi-line comment.
- This is the third line of a multi-line comment. */
-
- /* This is the first line of another multi-line comment. */
- /* This is the second line of another multi-line comment. */
- /* This is the third line of another multi-line comment. */
-
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Correct</b></p>
-<ul><pre>
- /* This is the first line of a multi-line comment.
- * This is the second line of a multi-line comment.
- * This is the third line of a multi-line comment.
- */
-
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<p>
- <b>Comments to the Right of Statements</b>.
- Comments to the right of statements in C source files are discouraged.
- If such comments are used, they should be (1) very short so that they do not exceed the line width (typically 78 characters), (2) aligned so that the comment begins in the same column on each line.
-</p>
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
- dog = cat; /* Make the dog be a cat */
- monkey = oxen; /* Make the monkey be an oxen */
- aardvark = macaque; /* Make the aardvark be a macaque */
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="blue"><b>Acceptable</b></p>
-<ul><pre>
- dog = cat; /* Make the dog be a cat. */
- monkey = oxen; /* Make the monkey be an oxen. */
- aardvark = macaque; /* Make the aardvark be a macaque. */
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Preferred</b></p>
-<ul><pre>
- /* Make the dog be a cat. */
-
- dog = cat;
-
- /* Make the monkey be an oxen. */
-
- monkey = oxen;
-
- /* Make the aardvark be a macaque. */
-
- aardvark = macaque;
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<p>
- <b>Comments to the Right of Data Definitions</b>.
- Comments to the right of a declaration with an enumeration or structure, on the other hand, are encouraged, provided that the comments are short and do not exceed the maximum line width (usually 78 characters).
- Columnar alignment of comments is very desirable (but often cannot be achieved without violating the line width).
-</p>
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
-struct animals_s
-{
- int dog; /* This is a dog */
- int cat; /* This is a cat */
- double monkey; /* This is a monkey */
- double oxen; /* This is an oxen */
- bool aardvark; /* This is an aardvark */
- bool macaque; /* This is a macaque */
-};
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="blue"><b>Acceptable</b></p>
-<ul><pre>
-struct animals_s
-{
- int dog; /* This is a dog. */
- int cat; /* This is a cat. */
- double monkey; /* This is a monkey. */
- double oxen; /* This is an oxen. */
- bool aardvark; /* This is an aardvark. */
- bool macaque; /* This is a macaque. */
-};
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Preferred</b></p>
-<ul><pre>
-struct animals_s
-{
- int dog; /* This is a dog. */
- int cat; /* This is a cat. */
- double monkey; /* This is a monkey. */
- double oxen; /* This is an oxen. */
- bool aardvark; /* This is an aardvark. */
- bool macaque; /* This is a macaque. */
-};
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<p>
- <b>Long Comments on the Right</b>.
- Comments on the right of statements or data definitions must be short and fit on the same line without exceeding the maximum line length.
- If a longer comment is needed, then it should appear above the statement of definition rather than to the right of the definition.
-</p>
-<p>
- <b>Breaking Long Comments to the Right of Statements</b>
- Breaking long comments to the right of statements is acceptable as well, but not encouraged.
- In this case the comment must be begin on the first line of the multi-line, right-hand comment with the opening comment delimiter (/*).
- The following lines of the multi-line, right hand comment must be with an asterisk (*) aligned in the same column as the asterisk in the preceding line.
- The closing comment delimiter must lie on the <i>same</i> line with the asterisk.
-</p>
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
- dog = cat; /* This assignment will convert what was at one time a lowly dog into a ferocious feline. */
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="blue"><b>Acceptable</b></p>
-<ul><pre>
- dog = cat; /* This assignment will convert what was at one time a
- * lowly dog into a ferocious feline. */
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Preferred</b></p>
-<ul><pre>
- /* This assignment will convert what was at one time a lowly dog into a
- * ferocious feline.
- */
-
- dog = cat;
-</ul></pre></font>
-</td></tr>
-</table></center>
-<p>
- <b>Note</b> that if the comment is continued on multiple lines, the comment alignment and multi-line comment rules still apply with one exception: The closing <code>*/</code> appears on the same line as the final text of the comment. This exception to the rule is enforced to keep the statements and definitions from becoming to spread out.
-</p>
-
-<p>
- <b>Block comments</b>.
- Block comments are only used to delimit groupings with the overall <a href="#fileorganization">file organization</a> and should not be used unless the usage is consistent with delimiting logical groupings in the program.
-</p>
-
-<p>
- <b>C Style Comments</b>.
- C99/C11/C++ style comments (beginning with <code>//</code>) should not be used with NuttX.
- NuttX generally follows C89 and all code outside of architecture specific directories must be compatible with C89.
-</p>
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
-// This is a structure of animals
-struct animals_s
-{
- int dog; // This is a dog
- int cat; // This is a cat
- double monkey; // This is a monkey
- double oxen; // This is an oxen
- bool aardvark; // This is an aardvark
- bool macaque; // This is a macaque
-};
-</ul></pre></font>
-</td></td>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Correct</b></p>
-<ul><pre>
-/* This is a structure of animals. */
-
-struct animals_s
-{
- int dog; /* This is a dog. */
- int cat; /* This is a cat. */
- double monkey; /* This is a monkey. */
- double oxen; /* This is an oxen. */
- bool aardvark; /* This is an aardvark. */
- bool macaque; /* This is a macaque. */
-};
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<p>
- <b>"Commenting Out" Large Code Blocks</b>.
- Do not use C or C++ comments to disable compilation of large blocks of code.
- Instead, use <code>#if 0</code> to do that.
- Make sure there is a comment before the <code>#if 0</code> to explain why the code is not compiled.
-</p>
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
-void some_function(void)
-{
- ... compiled code ...
-
- /*
- ... disabled code ..
- */
-
- ... compiled code ...
-}
-
-void some_function(void)
-{
- ... compiled code ...
-
- //
- // ... disabled code ..
- //
-
- ... compiled code ...
-}
-</ul></pre></font>
-</td></td>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Correct</b></p>
-<ul><pre>
-void some_function(void)
-{
- ... compiled code ...
-
- /* The following code is disabled because it is no longer needed. */
-
-#if 0
- ... disabled code ..
-#endif
-
- ... compiled code ...
-}
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<h2>1.4 <a name="braces">Braces</a></h2>
-
-<p>
- In general, the use of braces in the NuttX coding standard is similar to the use of braces in the <a href="https://www.gnu.org/prep/standards/standards.pdf">GNU Coding standards</a> with a few subtle differences.
-</p>
-
-<p><b>Coding Standard:</b></p>
-<ul>
- <li>
- <b>Always on Separate Lines</b>.
- Braces always appear on a separate line containing nothing else other than white space.
- </li>
- <li>
- <b>Never Comments on Braces</b>.
- Do not put comments on the same line as braces.
- </li>
- <li>
- <b>Compound Statements</b>.
- Within this document, an opening left brace followed by a sequence of statements, and ending with a closing right brace is referred to as a <i>compound statement</i>.
- </li>
- <li>
- <b>Nested Compound Statements</b>.
- In the case where there are nested compound statements that end with several consecutive right braces, each closing right brace must lie on a separate line and must be indented to match the corresponding opening brace.
- </li>
- <li>
- <b>Final brace followed by a single blank line</b>.
- The <i>final</i> right brace must be followed by a blank line as per standard rules.
- There are two exceptions to this rule:
- <ol>
- <li>
- In the case where there are nested several consecutive right braces, no blank lines should be inserted except for after the <i>final</i> right brace.
- </li>
- <li>
- No blank should be used to separate the final, closing right brace when it is followed by a <code>break;</code> statement.
- </li>
- </ol>
- </li>
- <li>
- <b>Special Indentation Rules</b>.
- Special <a href="#indentation">indentation rules</a> apply to braces.
- </li>
-</ul>
-
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
-while (true)
- {
- if (valid)
- {
- ...
- } /* if valid */
- else
- {
- ...
- } /* not valid */
- } /* end forever */
-if (a < b) {
- if (a < 0) {
- c = -a;
- } else {
- c = a;
- }
-} else {
- if (b < 0) {
- c = -b;
- } else {
- c = b;
- }
-}
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Correct</b></p>
-<ul><pre>
-while (true)
- {
- if (valid)
- {
- ...
- }
- else
- {
- ...
- }
- }
-
-if (a < b)
- {
- if (a < 0)
- {
- c = -a;
- }
- else
- {
- c = a;
- }
- }
-else
- {
- if (b < 0)
- {
- c = -b;
- }
- else
- {
- c = b;
- }
- }
-
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<p>
- <b>Exception to Indentation Rule for Braces</b>.
- The exception is braces that following structure, enumeration, union, and function declarations.
- There is no additional indentation for those braces;
- those braces align with the beginning of the definition
-</p>
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
-enum kinds_of_dogs_e
- {
- ...
- };
-
-struct dogs_s {
- ...
- union {
- ...
- } u;
- ...
-};
-
-struct cats_s
- {
- ...
- union
- {
- ...
- } u;
- ...
- };
-
-int animals(int animal)
- {
- ...
- }
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Correct</b></p>
-<ul><pre>
-enum kinds_of_dogs_e
-{
- ...
-};
-
-struct dogs_s
-{
- ...
- union
- {
- ...
- } u;
- ...
-};
-
-struct cats_s
-{
- ...
- union
- {
- ...
- } u;
- ...
-};
-
-int animals(int animal)
-{
- ...
-}
-
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<h2>1.5 <a name="indentation">Indentation</b></h2>
-
-<p>
- In general, the indentation in the NuttX coding standard is similar to the indentation requirements of the <a href="https://www.gnu.org/prep/standards/standards.pdf">GNU Coding standards</a> with a few subtle differences.
-</p>
-
-<p>
- <b>Indentation Unit</b>.
- Indentation is in units of two spaces; Each indentation level is twos spaces further to the right than the preceding indentation levels.
- TAB characters may not be used for indentation.
-</p>
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
- if (x == y) {
- dosomething(x);
- }
-
- if (x == y) {
- dosomething(x);
- }
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Correct</b></p>
-<ul><pre>
- if (x == y)
- {
- dosomething(x);
- }
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<p>
- <b>Use of TAB Characters</b>.
- The use of TAB characters for indentation is prohibited in C source and header files.
- TAB characters are, however, used in make files, assembly language source files, Kconfig files and some script files.
- When TAB characters are used in these files, spaces may not be used for indentation.
- The correct TAB setting is 4 spaces (not 8) in these cases.
-</p>
-<p>
- <b>Alignment of Braces</b>.
- Note that since braces must be on a separate line (see above), this indentation by two spaces has an interesting property:
-</p>
-<ul>
- <li><p>
- All C statements (and case selectors) lie on lines that are multiples of 4 spaces (beginning with an indentation of two): 2, 6, 10, ... (4*n + 2) (for indentation level n = 0, 1, ...)
- </p></li>
- <li><p>
- Braces lie on a separate line also indented by multiple of 4 spaces: 4, 8, 12, ... 4*n (for indentation level n = 1, 2, ...)
- </p></li>
-</ul>
-<p>
- Thus, all code at the indentation level should align on the same column.
- Similarly, opening and closing braces at the same indentation level should also align on the same (but different) column.
-</p>
-
-<p>
- <b>Indentation of Pre-Processor Lines</b>.
- C Pre-processor commands following any conditional computation are also indented following basically the indentation same rules, differing in that the <code>#</code> always remains in column 1.
-</p>
-<p>
- When C pre-processor statements are indented, they should be should be indented by 2 spaces per level-of-indentation following the <code>#</code>.
- C pre-processor statements should be indented when they are enclosed within C pre-processor conditional logic (<code>#if</code>..<code>#endif</code>). The level of indentation increases with each level of such nested conditional logic.
-</p>
-<p>
- C pre-processor statements should always be indented in this way in the <code>Pre-processor Definitions</code> <a href="#cfilestructure">section</a> of each file.
- C pre-processor statements may be indented in the <code>Public/Private Data</code> and <code>Public/Private Functions</code> sections of the file.
- However, often the indentation of C pre-processor statements conflicts with the indentation of the C code and makes the code more difficult to read.
- In such cases, indentation of C pre-processor statements should be omitted in those sections (only).
-</p>
-
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
-#ifdef CONFIG_ABC
-#define ABC_THING1 1
-#define ABC_THING2 2
-#define ABC_THING3 3
-#endif
-
-#ifdef CONFIG_ABC
- #define ABC_THING1 1
- #define ABC_THING2 2
- #define ABC_THING3 3
-#endif
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Correct</b></p>
-<ul><pre>
-#ifdef CONFIG_ABC
-# define ABC_THING1 1
-# define ABC_THING2 2
-# define ABC_THING3 3
-#endif
-
-#ifdef CONFIG_ABC
-# define ABC_THING1 1
-# define ABC_THING2 2
-# define ABC_THING3 3
-#endif
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<p>
- <b>Exception</b>.
- Each header file includes <a href="#idempotence">idempotence definitions</a> at the beginning of the header file.
- This conditional compilation does <i>not</i> cause any change to the indentation.
-</p>
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
-#ifndef __INCLUDE_SOMEHEADER_H
-# define __INCLUDE_SOMEHEADER_H
-...
-# define THING1 1
-# define THING2 2
-# define THING3 3
-...
-#endif /* __INCLUDE_SOMEHEADER_H */
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Correct</b></p>
-<ul><pre>
-#ifndef __INCLUDE_SOMEHEADER_H
-#define __INCLUDE_SOMEHEADER_H
-...
-#define THING1 1
-#define THING2 2
-#define THING3 3
-...
-#endif /* __INCLUDE_SOMEHEADER_H */
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<h2>1.6 <a name="parentheses"></a>Parentheses</a></h2>
-
-<p><b>Coding Standard:</b></p>
-<ul>
- <li>
- <b>Space after key words</b>.
- Do not put a left parenthesis (<code>(</code>) immediately after any C keywords (<code>for</code>, <code>switch</code>, <code>while</code>, <code>do</code>, <code>return</code>, etc.).
- Put a space before the left parenthesis in these cases.
- </li>
- <li>
- <b>Otherwise, no space before left parentheses</b>.
- Otherwise, there should be no space before the left parentheses
- </li>
- <li>
- <b>No space between function name and argument list</b>.
- There should be no space between a function name and an argument list.
- </li>
- <li>
- <b>Never space before the right parentheses</b>.
- There should never be space before a right parenthesis (<code>)</code>).
- </li>
- <li>
- <b>No parentheses around returned values</b>.
- Returned values should never be enclosed in parentheses unless the parentheses are required to force the correct order of operations in a computed return value.
- </li>
-</ul>
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
-int do_foobar ( void )
-{
- int ret = 0;
- int i;
-
- for( i = 0; ( ( i < 5 ) || ( ret < 10 ) ); i++ )
- {
- ret = foobar ( i );
- }
-
- return ( ret );
-}
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Correct</b></p>
-<ul><pre>
-int do_foobar(void)
-{
- int ret = 0;
- int i;
-
- for (i = 0; i < 5 || ret < 10; i++)
- {
- ret = foobar(i);
- }
-
- return ret;
-}
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<p>
- <b>NOTE:</b>
- Many people do not trust their understanding of the precedence of operators and so use lots of parentheses in expressions to force the order of evaluation even though the parentheses may have no effect.
- This will certainly avoid errors due to an unexpected order of evaluation, but can also make the code ugly and overly complex (as in the above example).
- In general, NuttX does not use unnecessary parentheses to force order of operations.
- There is no particular policy in this regard.
- However, you are are advised to check your C Programming Language book if necessary and avoid unnecessary parenthesis when possible.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <h1>2.0 <a name="datatypes">Data and Type Definitions</a></h1>
- </td>
- </tr>
-</table>
-
-<h2>2.1 <a name="onedatperline">One Definition/Declaration Per Line</a></h2>
-
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
- extern long time, money;
- char **ach, *bch;
- int i, j, k;
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Correct</b></p>
-<ul><pre>
- extern long time;
- extern long money;
- FAR char **ach;
- FAR char *bch;
- int i;
- int j;
- int k;
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<p>
- <b>NOTE</b>:
- See the discussion of <a href="#farnear">pointers</a> for information about the <code>FAR</code> qualifier used above.
-</p>
-
-<h2>2.2 <a name="globalvariable">Global Variables</a></h2>
-
-<b>Global vs. Local vs. Public vs. Private</b>
-By a <i>global</i> variable it is meant any variable defined outside of a function.
-The distinction is between this kind of <i>global</i> and function <i>local</i> definition and refers to the scope a symbol <i>within a file</i>.
-A related concept for all <i>global</i> names defined within a file is the scope of the name across different files.
-If the global symbol is pre-pended with the <code>static</code> storage class then the scope of the global symbol is within the file only.
-This is a somewhat different concept and within NuttX you will find these distinguished as <i>private</i> vs. <i>public</i> global symbols.
-However, within this standard, the term <i>global variable</i> will refer to any variable that has more than local scope.
-</li>
-
-<p><b>Coding Standard:</b></p>
-<ul>
- <li>
- <b>Short global variable names</b>.
- Names should be terse, but generally descriptive of what the variable is for.
- Try to say something with the variable name, but don't try to say too much.
- For example, the variable name of <code>g_filelen</code> is preferable to something like <code>g_lengthoffile</code>.
- </li>
- <li>
- <b>Global variable prefix</b>.
- All global variables begin with the prefix <code>g_</code> to indicate the scope of variable.
- </li>
- <li>
- <b>Module name prefix</b>
- If a global variable belongs in a <i>module</i> with a name of, say <code>xyz</code>, then that module should be included as part of the prefix like: <code>g_xyz_</code>.
- </li>
- <li>
- <b>Lowercase</b>,
- Use all lower case letters.
- </li>
- <li>
- <b>Minimal use of <code>'_'</code></b>.
- Preferably there are no <code>'_'</code> separators within the name.
- Long variable names might require some delimitation using <code>'_'</code>.
- Long variable names, however, are discouraged.
- </li>
- <li>
- <b>Use structures</b>.
- If possible, wrap all global variables within a structure to minimize the liklihood of name collisions.
- </li>
- <li>
- <b>Avoid global variables when possible</b>.
- Use of global variables, in general, is discourage unless there is no other reasonable solution.
- </li>
-</ul>
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
-extern int someint;
-static int anotherint;
-uint32_t dwA32BitInt;
-uint32_t gAGlobalVariable;
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="blue"><b>Acceptable</b></p>
-<ul><pre>
-extern int g_someint;
-static int g_anotherint;
-uint32_t g_a32bitint;
-uint32_t g_aglobal;
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Preferred</b></p>
-<ul><pre>
-struct my_variables_s
-{
- uint32_t a32bitint;
- uint32_t aglobal;
-};
-
-extern int g_someint;
-static int g_anotherint;
-struct my_variables_s g_myvariables;
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<h2>2.3 <a name="localvariable">Parameters and Local Variables</a></h2>
-
-<p><b>Coding Standard:</b></p>
-<ul>
- <li>
- <b>Common naming standard</b>.
- Naming for function parameters and local variables is the same.
- </li>
- <li>
- <b>Short variable names</b>.
- Names should be terse, but generally descriptive of what the variable is for.
- Try to say something with the variable name, but don't try to say too much.
- For example, the variable name of <code>len</code> is preferable to something like <code>lengthofiobuffer</code>.
- </li>
- <li>
- <b>No special ornamentation</b>.
- There is no special ornamentation of the name to indication that the variable is a local variable.
- The prefix <code>p</code> or <code>pp</code> may be used on names of pointers (or pointer to pointers) if it helps to distinguish the variable from some other local variable with a similar name.
- Even this convention is discouraged when not necessary.
- </li>
- <li>
- <b>Lowercase</b>
- Use all lower case letters.
- </li>
- <li>
- <b>Minimal use of single character variable names</b>.
- Short variable names are preferred.
- However, single character variable names should be avoided.
- Exceptions to this include <code>i</code>, <code>j</code>, and <code>k</code> which are reserved only for use as loop indices
- (part of our Fortran legacy).
- </li>
- <li>
- <b>Minimal use of <code>'_'</code></b>.
- Preferably there are no <code>'_'</code> separators within the name.
- Long variable names might require some delimitation using <code>'_'</code>.
- Long variable names, however, are discouraged.
- </li>
-</ul>
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
-uint32_t somefunction(int a, uint32_t dwBValue)
-{
- uint32_t this_is_a_long_variable_name = 1;
- int i;
-
- for (i = 0; i < a; i++)
- {
- this_is_a_long_variable_name *= dwBValue--;
- }
-
- return this_is_a_long_variable_name;
-}
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Correct</b></p>
-<ul><pre>
-uint32_t somefunction(int limit, uint32_t value)
-{
- uint32_t ret = 1;
- int i;
-
- for (i = 0; i < limit; i++)
- {
- ret *= value--;
- }
-
- return ret;
-}
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<p>
- <b>NOTE:</b>
- You will see the local variable named <code>ret</code> is frequently used in the code base for the name of a local variable whose value will be returned or to received the returned value from a called function.
-</p>
-
-<h2>2.4 <a name="typedefinitions"> Type Definitions</a></h2>
-
-<p><b>Coding Standard:</b></p>
-<ul>
- <li>
- <b>Short type names</b>.
- Type names should be terse, but generally descriptive of what the type is for.
- Try to say something with the type name, but don't try to say too much.
- For example, the type name of <code>fhandle_t</code> is preferable to something like <code>openfilehandle_t</code>.
- </li>
- <li>
- <b>Type name suffix</b>.
- All <code>typedef</code>'ed names end with the suffix <code>_t</code>.
- </li>
- <li>
- <b>Module name prefix</b>
- If a type belongs in a <i>module</i> with a name of, say <code>xyz</code>, then that module should be included as a prefix to the type name like: <code>xyz_</code>.
- </li>
- <li>
- <b>Lowercase</b>.
- Use all lower case letters.
- </li>
- <li>
- <b>Minimal use of <code>'_'</code></b>.
- Preferably there are few <code>'_'</code> separators within the type name.
- Long type names might require some delimitation using <code>'_'</code>.
- Long type names, however, are discouraged.
- </li>
-</ul>
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
-typedef void *myhandle;
-typedef int myInteger;
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Correct</b></p>
-<ul><pre>
-typedef FAR void *myhandle_t;
-typedef int myinteger_t;
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<p>
- <b>NOTE</b>:
- See the discussion of <a href="#farnear">pointers</a> for information about the <code>FAR</code> qualifier used above.
-</p>
-
-<h2>2.5 <a name="structures">Structures</a></h2>
-
-<p><b>Structure Naming</b></p>
-<ul>
- <li>
- <b>No un-named structures</b>.
- All structures must be named, even if they are part of a type definition.
- That is, a structure name must follow the reserved word <code>struct</code> in all structure definitions.
- There are two exceptions to this rule:
- <ol>
- <li>
- First for structures that are defined within another union or structure (discouraged). In those cases, the structure name should always be omitted.
- </li>
- <li>
- Second for structures as the type of a local variable. In this case, again, the structure name should always be omitted.
- </li>
- </ol>
- </li>
- <li>
- <b>Structured defined with structures discouraged</b>.
- Fields within a structure may be another structure that is defined only with the scope of the containing structure.
- This practice is acceptable, but discouraged.
- </li>
- <li>
- <b>No un-named structure fields</b>.
- Structure may contain other structures as fields.
- This this case, the structure field must be named.
- C11 permits such un-named structure fields within a structure.
- NuttX generally follows C89 and all code outside of architecture specific directories must be compatible with C89.
- <li>
- <b>No structure definitions within Type Definition</b>.
- The practice of defining a structure within a type definition is discouraged.
- It is preferred that the structure definition and the type definition be separate definitions.
- In general, the NuttX coding style discourages any <code>typdef</code>-ing of structures;
- normally the full structure name is used as types throughout the code.
- The reason for this is that is structure pointers may be forward referenced in header files without having to include the file the provides the type definition.
- This greatly reduces header file coupling.
- </li>
- <li>
- <b>Short structure names</b>.
- Structure names should be terse, but generally descriptive of what the structure contains.
- Try to say something with the structure name, but don't try to say too much.
- For example, the structure name of <code>xyz_info_s</code> is preferable to something like <code>xyz_datainputstatusinformation_s</code>.
- </li>
- <li>
- <b>Structure name suffix</b>.
- All structure names end with the suffix <code>_s</code>.
- </li>
- <li>
- <b>Module name prefix</b>
- If a structure belongs to a <i>module</i> with a name of, say <code>xyz</code>, then that module should be included as a prefix to the structure name like: <code>xyz_</code>.
- </li>
- <li>
- <b>Lowercase</b>.
- Use all lower case letters.
- </li>
- <li>
- <b>Minimal use of <code>'_'</code></b>.
- Preferably there are few <code>'_'</code> separators within the structure name.
- Long variable names might require some delimitation using <code>'_'</code>.
- Long variable names, however, are discouraged.
- </li>
-</ul>
-
-<p><b>Structure Field Naming</b></p>
-<ul>
- <li>
- <b>Common variable naming</b>.
- Structure field naming is generally the same as for local variables.
- </li>
- <li>
- <b>One definition per line</b>.
- The <a href="#onedatperline">one definition per line</a> rule applies to structure fields,
- including bit field definitions.
- </li>
- <li>
- <b>Each field should be commented</b>.
- Each structure field should be commented.
- Commenting should follow the <a href="#comments">standard conventions</a>.
- </li>
- <li>
- <b>Optional structure field prefix</b>.
- It make be helpful to add a two-letter prefix to each field name so that is is clear which structure the field belongs to.
- Although a good practice, that convention has not been used consistently in NuttX.
- </li>
- <li>
- <b>Lowercase</b>.
- Use all lower case letters.
- </li>
- <li>
- <b>Minimal use of <code>'_'</code></b>.
- Preferably there are few <code>'_'</code> separators within the field name.
- Long variable names might require some delimitation using <code>'_'</code>.
- Long variable names, however, are discouraged.
- </li>
-</ul>
-<p>
- <b>Other Applicable Coding Standards</b>.
- See sections related to <a href="#lines">line formatting</a>, <a href="#braces">use of braces</a>, <a href="#indentation">indentation</a>, and <a href="#comments">comments</a>.
-</p>
-<p>
- <b>Size Optimizations</b>.
- When declaring fields in structures, order the declarations in such a way as to minimize memory waste due of data alignment.
- This essentially means that that fields should be organized by data size, not by functionality:
- Put all pointers togeter, all <code>uint8_t</code>'s together, all <code>uint32_t</code>'s together.
- Data types withi well known like <code>uint8_t</code> and <code>uint32_t</code> should also be place in either ascending or descending size order.
-</p>
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
-typedef struct /* Un-named structure */
-{
- ...
- int val1, val2, val3; /* Values 1-3 */
- ...
-} xzy_info_t;
-
-struct xyz_information
-{
- ...
- uint8_t bita : 1, /* Bit A */
- bitb : 1, /* Bit B */
- bitc : 1; /* Bit C */
- ...
-};
-
-struct abc_s
-{
- ...
- struct
- {
- int a; /* Value A */
- int b; /* Value B */
- int c; /* Value C */
- }; /* Un-named structure field */
- ...
-};
-
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<ul>
-<font color="green">
-<p>
- <b>Correct</b>
-</p>
-<pre>
-struct xyz_info_s
-{
- ...
- int val1; /* Value 1 */
- int val2; /* Value 2 */
- int val3; /* Value 3 */
- ...
-};
-</pre>
-<font color="blue">
-<p>
- <b>Discouraged</b>
-</p>
-<pre>
-typedef struct xyz_info_s xzy_info_t;
-</pre>
-<p>
- The use of typedef'ed structures is acceptable but discouraged.
-</p>
-</font>
-<p>
- <b>Correct</b>
-</p>
-<pre>
-struct xyz_info_s
-{
- ...
- uint8_t bita : 1, /* Bit A */
- uint8_t bitb : 1, /* Bit B */
- uint8_t bitc : 1, /* Bit C */
- ...
-};
-</pre>
-<font color="blue">
-<p>
- <b>Discouraged</b>
-</p>
-<pre>
-struct abc_s
-{
- ...
- struct
- {
- int a; /* Value A */
- int b; /* Value B */
- int c; /* Value C */
- } abc;
- ...
-};
-</pre>
-<p>
- The use of structures defined within other structures is acceptable provided that they define named fields.
- The general practice of defining a structure within the scope of another structure, however, is still but discouraged in any case.
- The following is preferred:
-</p>
-</font>
-<p>
- <b>Preferred</b>
-</p>
-<pre>
-struct abc_s
-{
- ...
- int a; /* Value A */
- int b; /* Value B */
- int c; /* Value C */
- ...
-};
-
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<h2>2.6 <a name="unions">Unions</a></h2>
-<p>
- <b>Union and Field Names</b>.
- Naming of unions and fields within unions follow the same naming rules as for <a href="#structures">structures and structure fields</a>.
- The only difference is that the suffix <code>_u</code> is used to identify unions.
-</p>
-<p>
- <b>Other Applicable Coding Standards</b>.
- See sections related to <a href="#lines">line formatting</a>, <a href="#braces">use of braces</a>, <a href="#indentation">indentation</a>, and <a href="#comments">comments</a>.
-</p>
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Example</b></p>
-<ul><pre>
-union xyz_union_u /* All unions must be named */
-{
- uint8_t b[4]; /* Byte values. */
- uint16_t h[2]; /* Half word values. */
- uint32_t w; /* Word Value. */
-};
-</pre>
-<font color="blue"><pre>
-typedef union xyz_union_u xzy_union_t;
-</pre>
-<p>The use of typedef'ed unions is acceptable but discouraged.</p></font>
-<pre>
-struct xyz_info_s
-{
- ...
- union
- {
- uint8_t b[4]; /* Byte values. */
- uint16_t h[2]; /* Half word values. */
- uint32_t w; /* Word Value. */
- } u; /* All union fields must be named */
- ...
-};
-
-</ul></pre></font>
-</td></tr>
-</table></center>
-<p>
- <b>NOTE:</b>
- Note that the union fields within structures are often named <code>u</code>.
- This is another exception to the prohibition against using single character variable and field names.
- The short field name <code>u</code> clearly identifies a union field and prevents the full name of the union value from being excessively long.
-</p>
-
-<h2>2.7 <a name="enumerations">Enumerations</a></h2>
-<p>
- <b>Enumeration Naming</b>.
- Naming of enumerations follow the same naming rules as for <a href="#structures">structure</a> and <a href=#unions">union</a> naming.
- The only difference is that the suffix <code>_e</code> is used to identify an enumeration.
-</p>
-<p>
- <b>Enumeration Value Naming</b>.
- Enumeration values, however, following a naming convention more similar to <a href="#macros">macros</a>.
-</p>
-<ul>
- <li>
- <b>Uppercase</b>.
- Enumeration values are always in upper case.
- </li>
- <li>
- <b>Use of <code>'_'</code> encouraged</b>.
- Unlike other naming, use of the underscore character <code>_</code> to break up enumeration names is encouraged.
- </li>
- <li>
- <b>Prefix</b>.
- Each value in the enumeration should begin with an upper-case prefix that identifies the value as a member of the enumeration.
- This prefix should, ideally, derive from the name of the enumeration.
- </li>
- <li>
- <b>No dangling commas</b>.
- There should be no dangling comma on the final value of the enumeration.
- The most commonly used tool chain are tolerant of such dangling commas, but others will not.
- </li>
-</ul>
-<p>
- <b>Other Applicable Coding Standards</b>.
- See sections related to <a href="#lines">line formatting</a>, <a href="#braces">use of braces</a>, <a href="#indentation">indentation</a>, and <a href="#comments">comments</a>.
-</p>
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Example</b></p>
-<ul><pre>
-enum xyz_state_e
-{
- XYZ_STATE_UNINITIALIZED = 0, /* Uninitialized state. */
- XYZ_STATE_WAITING, /* Waiting for input state. */
- XYZ_STATE_BUSY, /* Busy processing input state. */
- XYZ_STATE_ERROR, /* Halted due to an error. */
- XYZ_STATE_TERMINATING, /* Terminating stated. */
- XYZ_STATE_TERMINATED /* Terminating stated. */
-};
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<h2>2.8 <a name="macros">C Pre-processor Macros</h2>
-
-<p><b>Coding Standard:</b></p>
-
-<p>
- <b>Macro Naming</b>.
- Macro naming following a naming convention similar to the naming of <a href="#enumerations">enumeration values</a>.
-</p>
-<ul>
- <li>
- <b>Uppercase</b>.
- Macro names are always in upper case.
- </li>
- <li>
- <b>Lowercase Exceptions</b>.
- There are a few lower case values in NuttX macro names. Such as a lower-case <code>p</code> for a period or decimal point (such as <code>VOLTAGE_3p3V</code>).
- I have also used lower-case <code>v</code> for a version number (such as <code>CONFIG_NET_IPv6</code>).
- However, these are exceptions to the rule rather than illustrating a rule.
- </li>
- <li>
- <b>Macros that could be functions</b>.
- Lower-case macro names are also acceptable if the macro is a substitute for a function name that might be used in some other context.
- In that case, normal function naming applies.
- </li>
- <li>
- <b>Use of <code>'_'</code> encouraged</b>.
- Unlike other naming, use of the underscore character <code>_</code> to break up macro names is encouraged.
- </li>
- <li>
- <b>Prefix</b>.
- Each related macro value should begin with an upper-case prefix that identifies the value as part of a set of values (and also to minimize the likelihood of naming collisions).
- </li>
- <li>
- <b>Single space after <code>#define</code></b>.
- A single space character should separate the <code>#define</code> from the macro name.
- Tabs are never used.
- </li>
- <li>
- <b>Normal commenting rules</b>.
- Normal commenting rules apply.
- </li>
- <li>
- <b>Line continuations</b>.
- Macro definitions may be continued on the next line by terminating the line with the <code>\</code> character just before the newline character.
- There should be a single space before the <code>\</code> character.
- Aligned <code>\</code> characters on multiple line continuations are discouraged because they are a maintenance problem.
- </li>
- <li>
- <b>Parentheses around macro argument expansions</b>.
- Macros may have argument lists.
- In the macros expansion, each argument should be enclosed in parentheses.
- </li>
- <li>
- <b>Real statements</b>.
- If a macro functions as a statement, then the macro expansion should be wrapped in <code>do { ... } while (0)</code> to assume that the macros is, indeed, a statement.
- </li>
- <li>
- <b><i>Magic numbers</i> are prohibited in code</b>.
- Any numeric value is not intuitively obvious, must be properly named and provided as either a pre-processor macro or an enumeration value.
- </li>
- <li>
- <b>Side effects</b>.
- Be careful of side effects.
- </li>
- <li>
- <b>Indentation</b>.
- See the <a href="#indentation">Indentation of Pre-Processor Lines</a> requirements above.
- </li>
-</ul>
-<p>
- <b>Other Applicable Coding Standards</b>.
- See sections related to <a href="#lines">line formatting</a>, <a href="#indentation">indentation</a>, and <a href="#comments">comments</a>.
-</p>
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
-#define max(a,b) a > b ? a : b
-
-#define ADD(x,y) x + y
-
-#ifdef HAVE_SOMEFUNCTION
-int somefunction(struct somestruct_s* psomething);
-#else
-#define SOMEFUNCTION() (0)
-#endif
-
-# define IS_A_CAT(c) ((c) == A_CAT)
-
-#define LONG_MACRO(a,b) \
- { \
- int value; \
- value = b-1; \
- a = b*value; \
- }
-
-#define DO_ASSIGN(a,b) a = b
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Correct</b></p>
-<ul><pre>
-#define MAX(a,b) (((a) > (b)) ? (a) : (b))
-
-#define ADD(x,y) ((x) + (y))
-
-#ifdef HAVE_SOMEFUNCTION
-int somefunction(struct somestruct_s* psomething);
-#else
-# define somefunction(p) (0)
-#endif
-
-# define IS_A_CAT(c) ((c) == A_CAT)
-
-#define LONG_MACRO(a,b) \
- { \
- int value; \
- value = (b)-1; \
- (a) = (b)*value; \
- }
-
-#define DO_ASSIGN(a,b) do { (a) = (b); } while (0)
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<h2>2.9 <a name=pointers>Pointer Variables</a></h2>
-<p>
- <b>Pointer Naming</b>.
- Pointers following same naming conventions as for other variable types.
- A pointer (or pointer-to-a-pointer) variable may be prefaced with <code>p</code> (or <code>pp</code>) with no intervening underscore character <code>_</code> in order to identify that variable is a pointer.
- That convention is not encouraged, however, and is only appropriate if there is some reason to be concerned that there might otherwise be confusion with another variable that differs only in not being a pointer.
-<p>
- <b>White Space</b>.
- The asterisk used in the declaration of a pointer variable or to dereference a pointer variable should be placed immediately before the variable name with no intervening spaces.
- A space should precede the asterisk in a cast to a pointer type.
-</p>
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
-int somefunction(struct somestruct_s* psomething);
-
-ptr = (struct somestruct_s*)value;
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Correct</b></p>
-<ul><pre>
-int somefunction(FAR struct somestruct_s *something);
-
-ptr = (FAR struct somestruct_s *)value;
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<p><a name="farnear">
- <b><code>FAR</code>, <code>NEAR</code>, <code>DSEG</code> and <code>CODE</code> pointers</b></a>.
- Some architectures require a qualifier on pointers to identify the address space into which the pointer refers.
- The macros <code>FAR</code>, <code>NEAR</code>, <code>DSEG</code> and <code>CODE</code> are defined in <code>include/nuttx/compiler.h</code> to provide meaning for this qualifiers when needed.
- For portability, the general rule is that pointers to data that may lie in the stack, heap, <code>.bss</code>, or <code>.data</code> should be prefaced by the qualifier <code>FAR</code>; pointers to functions probably lie in a code address space and should have the qualifier <code>CODE</code>.
- The typical effect of these macros on architectures where they have meaning to determine the size of the pointer (size in the sense of the width of the pointer value in bits).
-</p>
-
-<h2>2.10 <a name="initializers">Initializers</a></h2>
-<p>
- <b>Applicable Coding Standards</b>.
- See the section related to <a href="#parentheses">parentheses</a>.
-</p>
-<p>
- <b>C89 Compatibility</b>.
- All common NuttX code must conform to ANSII C89 requirements.
- Newer C standards permit more flexible initialization with named initializers and array initializers.
- However, these are not backward compatible with C89 and cannot be used in common code.
- Newer C99 features may be included in architecture-specific sub-directories where there is no possibility of the use of such older toolchains.
- C11 is included in NuttX, but has not been verified and, hence, it not encourage anywhere.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <h1>3.0 <a name="functions">Functions</a></h1>
- </td>
- </tr>
-</table>
-
-<h2>3.1 <a name="funcheaders">Function Headers</a></h2>
-
-<p><b>Coding Standard:</b></p>
-<ul>
- <li>
- <b>Function headers</b>.
- Each function is preceded by a function header. The function header is a <i>block comment</i> that provides information about the function.
- The block comment consists of the following:
- <p><ul>
- <li>
- The block comment begins with a line that consists of the opening C comment in column 1 (<code>/*</code>) followed by a series of asterisks extending to the length of the line (usually to column 78).
- </li>
- <li>
- The block comment ends with a line that consists of series of asterisks beginning at column 2 and extending to the near the end line (usually to column 77) followed by the closing C comment in (usually at column 78 for a total length of 79 characters).
- </li>
- <li>
- Information about the function is included in lines between the first and final lines.
- Each of these begin with a space in column 1, an sterisk (<code>*</code>) in column 2, and a space in column 3.
- </li>
- </ul></p>
- </li>
- <li>
- <b>Function header preceded by one blank line</b>.
- Exactly one blank line precedes each function header.
- </li>
- <li>
- <b>Function header followed by one blank line</b>.
- Exactly one blank line is placed after function header and before the function definition.
- </li>
- <li>
- <b>Function header sections</b>.
- Within the function header, the following data sections must be provided:
- <p><ul>
- <li>
- <b><code> * Name: </code></b> followed by the name of the function on the same line.
- </li>
- <li>
- <b><code> * Description:</code></b> followed by a description of the function beginning on the second line.
- Each line of the function description is indented by two additional spaces.
- </li>
- <li>
- <b><code> * Input Parameters:</code></b> followed by a description of the of each input parameter beginning on the second line.
- Each input parameter begins on a separator line indented by two additional spaces.
- The description needs to include (1) the name of the input parameters, and (2) a short description of the input parameter.
- </li>
- <li>
- <b><code> * Returned Value:</code></b> followed by a description of the of returned value(s) beginning on the second line.
- The description of the returned value should identify all error values returned by the function.
- </li>
- <li>
- <b><code> * Assumptions/Limitations:</code></b> followed by a any additional information that is needed to use the function correctly.
- This section is optional and may be omitted with there is no such special information required for use of the function.
- </li>
- </ul></p>
- Each of these data sections is separated by a single line like "<code> * </code>".
- </li>
-</ul>
-<p>
- <b>Function header template</b>.
- Refer to <a href="#cfilestructure">Appendix A</a> for the template for a function header.
-</p>
-
-<h2>3.2 <a name="funcname">Function Naming</a></h2>
-
-<p><b>Coding Standard:</b></p>
-<ul>
- <li>
- <b>Short function names</b>.
- Function names should be terse, but generally descriptive of what the function is for.
- Try to say something with the function name, but don't try to say too much.
- For example, the variable name of <code>xyz_putvalue</code> is preferable to something like <code>xyz_savethenewvalueinthebuffer</code>.
- </li>
- <li>
- <b>Lowercase</b>.
- Use all lower case letters.
- </li>
- <li>
- <b>Module prefix</b>.
- All functions in the same <i>module</i>, or <i>sub-system</i>, or within the same file should have a name beginning with a common prefix separated from the remainder of the function name with the underscore, <code>'_'</code>, character.
- For example, for a module called <i>xyz</i>, all of the functions should begin with <code>xyz_</code>.
- </li>
- <li>
- <b>Extended prefix</b>.
- Other larger functional grouping should have another level in the naming convention.
- For example, if module <i>xyz</i> contains a set of functions that manage a set of I/O buffers (IOB), then those functions all should get naming beginning with a common prefix like <code>xyz_iob_</code>.
- </li>
- <li>
- <b>Use of <code>'_'</code> discouraged</b>.
- Further use of the <code>'_'</code> separators is discouraged in function naming.
- Long function names might require some additional elimitation using <code>'_'</code>.
- Long function names, however, are also discouraged.
- </li>
- <li>
- <b>Verbs and Objects</b>.
- The remainder of the function name should be either in the form of <i>verb-object</i> or <i>object-verb</i>.
- It does not matter which as long as the usage is consistent within the <i>module</i>.
- Common verbs include <i>get</i> and <i>set</i> (or <i>put</i>) for operations that retrieve or store data, respectively.
- The verb <i>is</i> is reserved for functions that perform some test and return a boolean value to indicate the result of the test.
- In this case, the <i>object</i> should indicate what is testing and the return value of <code>true</code> should be consistent with result of the test being true.
- </li>
-</ul>
-
-<h2>3.3 <a name="parmlists">Parameter Lists</a></h2>
-
-<p>
- <b>Coding Standards</b>.
- See general rules for <a href="#localvariable">parameter naming</a>.
- See also the sections related to the use of <a href="#parentheses">parentheses</a>.
-</p>
-<p>
- <b>Use of <code>const</code> Parameters</b>.
- Use of the <code>const</code> storage class is encouraged.
- This is appropriate to indicate that the function will not modify the object.
-</p>
-
-<h2>3.4 <a name="funcbody">Function Body</a></h2>
-
-<p><b>Coding Standard:</b></p>
-<ul>
- <li>
- <b>Single compound statement</b>.
- The function body consists of a single compound statement.
- </li>
- <li>
- <b>Braces in column 1</b>
- The opening and close braces of the compound statement must be placed in column one.
- </li>
- <li>
- <b>First definition or statement in column 3</b>.
- The first data definitions or statements in the function body are idented by two spaces.
- Standards for statements are covered in the <a href="#statements">following paragraph</a>
- </li>
- <li>
- <b>Local variables first</b>.
- Because NuttX conforms to the older C89 standard, all variables that have scope over the compound statement must be defined at the beginning of the compound statement prior to any executable statements.
- Local variable definitions intermixed within the following sequence of executable statements are forbidden.
- A single blank line must follow the local variable definitions separating the local variable definitions from the following executable statements.
- <b>NOTE</b> that a function body consists of a compound statement, but typically so does the statement following <code>if</code>, <code>else</code>, <code>for</code>, <code>while</code>, <code>do</code>.
- Local variable definitions are also acceptable at the beginning of these compound statements as with any other.
- </li>
- <li>
- <b>Long functions are discouraged</b>.
- As a rule of thumb, the length of a function should be limited so that it would fit on a single page (if you were to print the source code).
- </li>
- <li>
- <b>Return Statement</b>.
- The argument of the <code>return</code> statement should <i>not</i> be enclosed in parentheses.
- A reasonable exception is the case where the returned value argument is a complex expression and where the parentheses improve the readability of the code.
- Such complex expressions might be Boolean expressions or expressions containing conditions.
- Simple arithmetic computations would not be considered <i>complex</i> expressions.
- </li>
- <li>
- <b>Space after the function body</b>.
- A one (and only one) blank line must follow the closing right brace of the function body.
- </li>
-</ul>
-<p>
- <b>Other Applicable Coding Standards</b>.
- See sections related to <a href="#general">General Conventions</a>, <a href="#localvariable">Parameters and Local Variables</a>, and <a href="#statements">Statements</a>.
-</p>
-
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
- int myfunction(int a, int b)
- {
- int c, d;
- c = a
- d = b;
-
- int e = c + d;
-
- for (int i = 0; i < a; i++)
- {
- for (int j = 0; j < b; j++)
- {
- e += j * d;
- }
- }
-
- return (e / a);
- }
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Correct</b></p>
-<ul><pre>
- int myfunction(int a, int b)
- {
- int c;
- int d;
- int e;
- int i;
-
- c = a
- d = b;
- e = c + d;
-
- for (i = 0; i < a; i++)
- {
- int j;
-
- for (j = 0; j < b; j++)
- {
- e += j * d;
- }
- }
-
- return e / a;
- }
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<h2><a name="retvalues">Returned Values</a></h2>
-
-<p>
- <b>OS Internal Functions</b>.
- In general, OS internal functions return a type <code>int</code> to indicate success or failure conditions.
- Non-negative values indicate success.
- The return value of zero is the typical success return value, but other successful return can be represented with other positive values.
- Errors are always reported with negative values.
- These negative values must be a well-defined <code>errno</code> as defined in the file <code>nuttx/include/errno.h</code>.
-</p>
-
-<p>
- <b>Application/OS Interface</b>.
- All but a few OS interfaces conform to documented standards that have precedence over the coding standards of this document.
-</p>
-
-<p>
- <b>Checking Return Values</b>.
- Callers of internal OS functions should always check return values for an error.
- At a minimum, a debug statement should indicate that an error has occurred.
- Ignored return values are always suspicious.
- All calls to <code>malloc</code> or <code>realloc</code>, in particular, must be checked for failures to allocate memory to avoid use of NULL pointers.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <h1>4.0 <a name="statements">Statements</a></h1>
- </td>
- </tr>
-</table>
-
-<h3>4.1 <a name="onestatement">One Statement Per Line</a></h3>
-
-<p><b>Coding Standard:</b></p>
-<ul>
- <li>
- <b>One statement per line</b>.
- There should never be more than one statement on a line.
- </li>
- <li>
- <b>No more than one assignment per statement</b>.
- Related to this, there should never be multiple assignments in the same statement.
- </li>
- <li>
- <b>Statements should never be on the same line as any keyword</b>.
- Statements should never be on the same line as case selectors or any C keyword.
- </li>
-</ul>
-<p>
- <b>Other Applicable Coding Standards</b>.
- See the section related to the use of <a href="#braces">braces</a>.
-</p>
-
-<center><table width="60%" border="1">
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
- if (var1 < var2) var1 = var2;
-
- case 5: var1 = var2; break;
-
- var1 = 5; var2 = 6; var3 = 7;
-
- var1 = var2 = var3 = 0;
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Correct</b></p>
-<ul><pre>
- if (var1 < var2)
- {
- var1 = var2;
- }
-
- case 5:
- {
- var1 = var2;
- }
- break;
-
- var1 = 5;
- var2 = 6;
- var3 = 7;
-
- var1 = 0;
- var2 = 0;
- var3 = 0;
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<h2>4.2 <a name="casts">Casts</a></h2>
-
-<p><b>Coding Standard:</b></p>
-<ul>
- <li>
- <b>No space in cast</b>.
- There should be no space between a cast and the value being cast.
- </li>
-</ul>
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
-struct something_s *x = (struct something_s*) y;
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Correct</b></p>
-<ul><pre>
-struct something_s *x = (struct something_s *)y;
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<h2>4.3 <a name="operators">Operators</a></h2>
-<p>
- <b>Spaces before and after binary operators</b>.
- All binary operators (operators that come between two values), such as <code>+</code>, <code>-</code>, <code>=</code>, <code>!=</code>, <code>==</code>, <code>></code>, etc. should have a space before and after the operator, for readability. As examples:
-</p>
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
-for=bar;
-if(a==b)
-for(i=0;i>5;i++)
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Correct</b></p>
-<ul><pre>
-for = bar;
-if (a == b)
-for (i = 0; i > 5; i++)
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<p>
- <b>No space separating unary operators</b>.
- Unary operators (operators that operate on only one value), such as <code>++</code>, should <i>not</i> have a space between the operator and the variable or number they are operating on.
-</p>
-<center><table width="60%" border=1>
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
-x ++;
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Correct</b></p>
-<ul><pre>
-x++;
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<p>
- <b>Forbidden Multicharacter Forms</b>.
- Many operators are expressed as a character in combination with <code>=</code> such as <code>+=</code>, <code>>=</code>, <code>>>=</code>, etc.
- Some compilers will accept the <code>=</code> at the beginning or the end of the sequence.
- This standard, however, requires that the <code>=</code> always appear last in order to avoid amiguities that may arise if the <code>=</code> were to appear first. For example, <code>a =++ b;</code> could also be interpreted as <code>a =+ +b;</code> or <code>a = ++b</code> all of which are very different.
-</p>
-
-<p>
-<h2>4.4 <a name="ifthenelse"></a><code>if then else</code> Statement</h2>
-
-<p><b>Coding Standard:</b></p>
-<ul>
- <li>
- <b><code>if</code> separated from <code><condition></code></b>.
- The <code>if</code> keyword and the <code><condition></code> must appear on the same line.
- The <code>if</code> keyword and the <code><condition></code> must be separated by a single space.
- </li>
- </li>
- <b>Keywords on separate lines</b>.
- <code>if <condition></code> and <code>else</code> must lie on separate lines with nothing else present on the line.
- </li>
- <li>
- <b>Indentation and parentheses</b>.
- <code>if <condition></code> follows the standard indentation and parentheses rules.
- </li>
- <li>
- <b>Alignment</b>.
- The <code>if</code> in the <code>if <condition></code> line and the <code>else</code> must be aligned at the same column.
- </li>
- <li>
- <b>Statement(s) always enclosed in braces</b>.
- Statement(s) following the <code>if <condition></code> and <code>else</code> keywords must always be enclosed in braces.
- Braces must follow the <code>if <condition></code> and <code>else</code> lines even in the cases where (a) there is no contained statement or (b) there is only a single statement!
- </li>
- <li>
- <b>Braces and indentation</b>.
- The placement of braces and statements must follow the standard rules for <a href="#braces">braces and indentation</a>.
- </li>
- <li>
- <b>Final brace followed by a single blank line</b>.
- The <i>final</i> right brace of the <code>if</code>-<code>else</code> must be followed by a blank line in most cases (the exception given below).
- This may be the final brace of the <code>if</code> compound statement if the <code>else</code> keyword is not present.
- Or it may be the the final brace of the <code>else</code> compound statement if present.
- A blank line never follows the right brace closing the <code>if</code> compound statement if the <code>else</code> keyword is present.
- Use of braces must follow all other standard rules for <a href="#braces">braces and spacing</a>.
- </li>
- <li>
- <b>Exception</b>.
- That blank line must also be omitted for certain cases where the <code>if <condition></code>-<code>else</code> statement is nested within another compound statement; there should be no blank lines between consecutive right braces as discussed in the standard rules for use of <a href="#braces">braces</a>.
- </li>
-</ul>
-<p>
- <b>Other Applicable Coding Standards</b>.
- See sections related to <a href="#braces">use of braces</a> and <a href="#indentation">indentation</a>.
-</p>
-
-<center><table width="60%" border="1">
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
- if(var1 < var2) var1 = var2;
-
- if(var > 0)
- var--;
- else
- var = 0;
-
- if (var1 > 0) {
- var1--;
- } else {
- var1 = 0;
- }
- var2 = var1;
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Correct</b></p>
-<ul><pre>
- if (var1 < var2
- {
- var1 = var2;
- }
-
- if (var > 0)
- {
- var--;
- }
- else
- {
- var = 0;
- }
-
- if (var1 > 0)
- {
- var1--;
- }
- else
- {
- var1 = 0;
- }
-
- var2 = var1;
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<p>
- <b><condition> <code>?</code> <then> <code>:</code> <else></b>
-</p>
-<ul>
- <li>
- <b>Only if the expression is short</b>.
- Use of this form is only appropriate if the entire sequence is short and fits neatly on the line.
- </li>
- <li>
- <b>Multiple lines forbidden</b>.
- This form is forbidden if it extends to more than one line.
- </li>
- <li>
- <b>Use of parentheses</b>.
- The condition and the entire sequence are often enclosed in parentheses.
- These are, however, not required if the expressions evaluate properly without them.
- </li>
-</ul>
-<p>
- <b>Other Applicable Coding Standards</b>.
- See sections related to <a href="#parentheses">parentheses</a>.
-</p>
-<center><table width="60%" border="1">
-<tr><td bgcolor="white">
-<p><font color="green"><b>Example</b></p>
-<ul><pre>
- int arg1 = arg2 > arg3 ? arg2 : arg3;
- int arg1 = ((arg2 > arg3) ? arg2 : arg3);
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<h2>4.5 <a name="switch"><code>switch</code> Statement</a></h2>
-
-<p><b>Definitions:</b></p>
-<ul>
- <li>
- <b><i>Case logic</i></b>.
- By <i>case logic</i> it is mean the <code>case</code> or <code>default</code> and all of the lines of code following the <code>case</code> or <code>default</code> up to the next <code>case</code>, <code>default</code>, or the right brace indicating the end of the switch statement.
- </li>
-</ul>
-
-<p><b>Coding Standard:</b></p>
-<ul>
- <li>
- <b><code>switch</code> separated from <code><value></code></b>.
- The <code>switch</code> keyword and the switch <code><value></code> must appear on the same line.
- The <code>if</code> keyword and the <code><value></code> must be separated by a single space.
- </li>
- <li>
- <b>Falling through</b>.
- Falling through a case statement into the next case statement is be permitted as long as a comment is included.
- </li>
- <li>
- <b><code>default</code> case</b>.
- The <code>default</code> case should always be present and trigger an error if it is reached when it should not be.
- </li>
- <li>
- <b><i>Case logic</i> in braces</b>.
- It is preferable that all <i>case logic</i> (except for the <code>break</code>) be enclosed in braces.
- If you need to instantiate local variables in case logic, then that logic must be surrounded with braces.
- </li>
- <li>
- <b><code>break</code> outside of braces</b>.
- <code>break</code> statements are normally indented by two spaces.
- When used conditionally with <i>case logic</i>, the placement of the break statement follows normal indentation rules.
- </li>
- <li>
- <b><i>Case logic</i> followed by a single blank line</b>.
- A single blank line must separate the <i>case logic</i> and any following <code>case</code> or <code>default</code>.
- The should, however, be no blank lines between the <i>case logic</i> and the closing right brace.
- </li>
- <li>
- <b>Switch followed by a single blank line</b>.
- The final right brace that closes the <code>switch <value></code> statement must be followed by a single blank line.
- </li>
- <li>
- <b>Exception</b>.
- That blank line must be omitted for certain cases where the <code>switch <value></code> statement is nested within another compound statement; there should be no blank lines between consecutive right braces as discussed in the standard rules for use of <a href="#braces">braces</a>.
- </li>
-</ul>
-<p>
- <b>Other Applicable Coding Standards</b>.
- See sections related to <a href="#braces">use of braces</a>, <a href="#indentation">indentation</a>, and <a href="#comments">comments</a>.
-</p>
-<center><table width="60%" border="1">
-<tr><td bgcolor="white">
-<p><font color="green"><b>Example</b></p>
-<ul><pre>
- switch (...)
- {
- case 1: /* Example of a comment following a case selector. */
- ...
-
- /* Example of a comment preceding a case selector. */
-
- case 2:
- {
- /* Example of comment following the case selector. */
-
- int value;
- ...
- }
- break;
-
- default:
- break;
- }
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<h2>4.6 <a name="while"><code>while</code> Statement</a></h2>
-<p><b>Coding Standard:</b></p>
-<ul>
- <li>
- <b><code>while</code> separated from <code><condition></code></b>.
- The <code>while</code> keyword and the <code><condition></code> must appear on the same line.
- The <code>while</code> keyword and the <code><condition></code> must be separated by a single space.
- </li>
- <li>
- <b>Keywords on separate lines</b>.
- <code>while <condition></code> must lie on a separate line with nothing else present on the line.
- </li>
- <li>
- <b>Indentation and parentheses</b>.
- <code>while <condition></code> follows the standard indentation and parentheses rules.
- </li>
- <li>
- <b>Statements enclosed in braces</b>
- Statement(s) following the <code>while <condition></code> must always be enclosed in braces, even if only a single statement follows.
- </li>
- <li>
- <b>No braces on null statements</b>.
- No braces are required if no statements follow the <code>while <condition></code>.
- The single semicolon (null statement) is sufficient;
- </li>
- <li>
- <b>Braces and indentation</b>.
- The placement of braces and statements must follow the standard rules for braces and indentation.
- </li>
- <li>
- <b>Followed by a single blank line</b>.
- The final right brace that closes the <code>while <condition></code> statement must be followed by a single blank line.
- </li>
- <li>
- <b>Exception</b>.
- That blank line must be omitted for certain cases where the <code>while <condition></code> statement is nested within another compound statement; there should be no blank lines between consecutive right braces as discussed in the standard rules for use of <a href="#braces">braces</a>.
- </li>
-</ul>
-<p>
- <b>Other Applicable Coding Standards</b>.
- See sections related to <a href="#braces">use of braces</a>, <a href="#indentation">indentation</a>, and <a href="#comments">comments</a>.
-</p>
-<center><table width="60%" border="1">
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
- while( notready() )
- {
- }
- ready = true;
-
- while (*ptr != '\0') ptr++;
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Correct</b></p>
-<ul><pre>
- while (notready());
-
- ready = true;
-
- while (*ptr != '\0')
- {
- ptr++;
- }
-
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<h2>4.7 <a name="dowhile"><code>do while</code> Statement</a></h2>
-<p><b>Coding Standard:</b></p>
-<ul>
- <li>
- <b>Keywords on separate lines</b>.
- <code>do</code> and <code>while <condition></code> must lie on separate lines with nothing else present on the line.
- </li>
- <li>
- <b>Indentation and parentheses</b>.
- <code>do .. while <condition></code> follows the standard indentation and parentheses rules.
- </li>
- <li>
- <b>Statements enclosed in braces</b>
- Statement(s) following the <code>do</code> must always be enclosed in braces, even if only a single statement (or no statement) follows.
- </li>
- <li>
- <b>Braces and indentation</b>.
- The placement of braces and statements must follow the standard rules for braces and indentation.
- </li>
- <li>
- <b><code>while</code> separated from <code><condition></code></b>.
- The <code>while</code> keyword and the <code><condition></code> must appear on the same line.
- The <code>while</code> keyword and the <code><condition></code> must be separated by a single space.
- </li>
- <li>
- <b>Followed by a single blank line</b>.
- The concluding <code>while <condition></code> must be followed by a single blank line.
- </li>
-</ul>
-<p>
- <b>Other Applicable Coding Standards</b>.
- See sections related to <a href="#braces">use of braces</a>, <a href="#indentation">indentation</a>, and <a href="#comments">comments</a>.
-</p>
-<center><table width="60%" border="1">
-<tr><td bgcolor="white">
-<p><font color="red"><b>Incorrect</b></p>
-<ul><pre>
- do {
- ready = !notready();
- } while (!ready);
- senddata();
-
- do ptr++; while (*ptr != '\0');
-</ul></pre></font>
-</td></tr>
-<tr><td bgcolor="white">
-<p><font color="green"><b>Correct</b></p>
-<ul><pre>
- do
- {
- ready = !notready();
- }
- while (!ready);
-
- senddata();
-
- do
- {
- ptr++;
- }
- while (*ptr != '\0');
-
-</ul></pre></font>
-</td></tr>
-</table></center>
-
-<h2>4.8 <a name="goto">Use of <code>goto</code></a></h2>
-<p><b>Coding Standard:</b></p>
-<ul>
- <li>
- <b>Limited Usage of <code>goto</code></b>.
- All use of the <code>goto</code> statement is prohibited except for one usage:
- for handling error conditions in complex, nested logic.
- A simple <code>goto</code> in those conditions can greatly improve the readability and complexity of the code.
- </li>
- <li>
- <b>Label Naming</b>.
- Labels must all lower case.
- The underscore character <code>_</code> is permitted to break up long labels.
- </li>
- <li>
- <b>Error Exit Labels</b>.
- The error exit label is normally called <code>errout</code>.
- Multiple error labels are often to required to <i>unwind</i> to recover resources committed in logic prior to the error to otherwise <i>undo</i> preceding operations.
- Naming for these other labels would be some like <code>errout_with_allocation</code>, <code>errout_with_openfile</code>, etc.
- </li>
- <li>
- <b>Label Positioning</b>.
- Labels are never indented.
- Labels must always begin in column 1.
- </li>
-</ul>
-<center><table width="60%" border="1">
-<tr><td bgcolor="white">
-<p><font color="green"><b>Example</b></p>
-<ul><pre>
- FAR struct some_struct_s *ptr;
- int fd;
- int ret;
- ...
-
- if (arg == NULL)
- {
- ret = -EINVAL;
- goto errout;
- }
- ...
- ptr = (FAR struct some_struct_s *)malloc(sizeof(struct some_struct_s));
- if (!ptr)
- {
- ret = -ENOMEM;
- goto errout;
- }
- ...
- fd = open(filename, O_RDONLY);
- if (fd < 0)
- {
- errcode = -errno;
- DEBUGASSERT(errcode > 0);
- goto errotout_with_alloc;
- }
- ...
- ret = readfile(fd);
- if (ret < 0)
- {
- goto errout_with_openfile;
- }
- ...
-errout_with_openfile:
- close(fd);
-
-errout_with_alloc:
- free(ptr);
-
-error:
- return ret;
-</ul></pre></font>
-</td></tr>
-</table></center>
-<p>
- <b>NOTE</b>:
- See the discussion of <a href="#farnear">pointers</a> for information about the <code>FAR</code> qualifier used above.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <h1>5.0 <a name="cplusplus">C++</a></h1>
- </td>
- </tr>
-</table>
-
-<p>
- There is no existing document that provides a complete coding standard for NuttX C++ files.
- This section is included here to provide some minimal guidance in C++ code development.
- In most details like indentation, spacing, and file organization, it is identical to the C coding standard.
- But there are significant differences in the acceptable standard beyond that.
- The primary differences are as follows:
-</p>
-<ol>
- <li>
- <p>
- C++ style comments are not only permissible but are required (other than for the following exception).
- This includes the block comments of in the <i>Source File Structure</i> described in an <a href="#appndxa">Appendix</a> to this standard.
- </p>
- </li>
- <li>
- <p>
- Deoxygen tags are acceptable. As are C style comments when needed to provide DOxygen tags.
- </p>
- </li>
- <li>
- <p>
- There is currently no requirement to conform any specific C++ version.
- However, for portability reasons, conformance to older, pre-C++11 standards is encouraged where reasonable.
- </p>
- <li>
- <p>
- C++ file name extensions: The extension <code>.cxx</code> is used for C++ source files; the extension <code>.hxx</code> is used for C++ header files.
- </p>
- <li>
- <p>
- All naming must use <i>CamelCase</i>.
- Use of the underbar character, '_' is discouraged.
- This includes variables, classes, structures, ..., etc.: All user-nameable C++ elements.
- Pre-processor definitions are still required to be all upper case.
- </p>
- </li>
- <li>
- <p>
- Local variable, method names, and function names must all begin with a lower case letter.
- As examples, <code>myLocalVariable</code> would be a compliant name for a local variable;
- <code>myMethod</code> would be a compliant name for a method;
- </p>
- <li>
- <p>
- Namespaces, global variable, class, structure, template, and enumeration names begin with a capital letter identifying what is being named:
- </p>
- </li>
- <p><ul>
- <dl>
- <dt>
- <i>Namespace Names</i>
- </dt>
- <dd>
- Namespaces begin with an upper case character but no particular character is specified.
- As an example, <code>MyNamespace</code> is fully compliant.
- </dd>
- <dt>
- <i>Global Variable Names</i>
- </dt>
- <dd>
- Global variables and singletons begin with an upper case '<b>G</b>'.
- For example, <code>GMyGlobalVariable</code>.
- The prefix <code>g_</code> is never used.
- </dd>
- <dt>
- <i>Implementation Class Names</i>
- </dt>
- <dd>
- Classes that implement methods begin with an upper case '<b>C</b>'.
- For example, <code>CMyClass</code>.
- A fully qualified method of <code>CMyClass</code> could be <code>MyNamespace::CMyClass::myMethod</code>
- </dd>
- <dt>
- <i>Pure Virtual Base Class Names</i>
- </dt>
- <dd>
- Such base classes begin with an upper case '<b>I</b>'.
- For example, <code>IMyInterface</code>.
- </dd>
- <dt>
- <i>Template Class Names</i>
- </dt>
- <dd>
- Template classes begin with an upper case '<b>T</b>'.
- For example, <code>TMyTemplate</code>.
- </dd>
- <dt>
- <i><code>typedef</code>'d Type Names</i>
- </dt>
- <dd>
- Currently all such types also begin with an upper case '<b>T</b>'.
- That probably needs some resolution to distinguish for template names.
- The suffix <code>_t</code> is never used.
- </dd>
- <dt>
- <i>Structure Names</i>
- </dt>
- <dd>
- Structures begin with an upper case '<b>S</b>'.
- For example, <code>SMyStructure</code>.
- The suffix <code>_s</code> is never used.
- </dd>
- <dt>
- <i>Enumerations Names</i>
- </dt>
- <dd>
- Enumerations begin with an upper case '<b>E</b>'.
- For example, <code>EMyEnumeration</code>.
- The suffix <code>_e</code> is never used.
- </ul></p>
- </dl>
-</ol>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <h1><a name="appndxa">Appendix A</a></h1>
- </td>
- </tr>
-</table>
-
-<h2><a name="cfilestructure">A.1 C Source File Structure</a></h2>
-<pre>
-/****************************************************************************
- * <i><Relative path to the file></i>
- * <i><Optional one line file description></i>
- *
- * Licensed to the Apache Software Foundation (ASF) under one or more
- * contributor license agreements. See the NOTICE file distributed with
- * this work for additional information regarding copyright ownership. The
- * ASF licenses this file to you under the Apache License, Version 2.0 (the
- * "License"); you may not use this file except in compliance with the
- * License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
- * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
- * License for the specific language governing permissions and limitations
- * under the License.
- *
- ****************************************************************************/
-
-/****************************************************************************
- * Included Files
- ****************************************************************************/
-</pre>
-<p><i>All header files are included here.</i></p>
-<pre>
-/****************************************************************************
- * Pre-processor Definitions
- ****************************************************************************/
-</pre>
-<p><i>All C pre-processor macros are defined here.</i></p>
-<pre>
-/****************************************************************************
- * Private Types
- ****************************************************************************/
-</pre>
-<p><i>Any types, enumerations, structures or unions used by the file are defined here.</i></p>
-<pre>
-/****************************************************************************
- * Private Function Prototypes
- ****************************************************************************/
-</pre>
-<p><i>Prototypes of all static functions in the file are provided here.</i></p>
-<pre>
-/****************************************************************************
- * Private Data
- ****************************************************************************/
-</pre>
-<p><i>All static data definitions appear here.</i></p>
-<pre>
-/****************************************************************************
- * Public Data
- ****************************************************************************/
-</pre>
-<p><i>All data definitions with global scope appear here.</i></p>
-<pre>
-/****************************************************************************
- * Private Functions
- ****************************************************************************/
-
-/****************************************************************************
- * Name: <i><Static function name></i>
- *
- * Description:
- * <i>Description of the operation of the static function.</i>
- *
- * Input Parameters:
- * <i>A list of input parameters, one-per-line, appears here along with a</i>
- * <i>description of each input parameter.</i>
- *
- * Returned Value:
- * <i>Description of the value returned by this function (if any),</i>
- * <i>including an enumeration of all possible error values.</i>
- *
- * Assumptions/Limitations:
- * <i>Anything else that one might need to know to use this function.</i>
- *
- ****************************************************************************/
-</pre>
-<p><i>All static functions in the file are defined in this grouping.
-Each is preceded by a function header similar to the above.</i></p>
-<pre>
-/****************************************************************************
- * Public Functions
- ****************************************************************************/
-
-/****************************************************************************
- * Name: <i><Global function name></i>
- *
- * Description:
- * <i>Description of the operation of the function.</i>
- *
- * Input Parameters:
- * <i>A list of input parameters, one-per-line, appears here along with a</i>
- * <i>description of each input parameter.</i>
- *
- * Returned Value:
- * <i>Description of the value returned by this function (if any),</i>
- * <i>including an enumeration of all possible error values.</i>
- *
- * Assumptions/Limitations:
- * <i>Anything else that one might need to know to use this function.</i>
- *
- ****************************************************************************/
-</pre>
-<p><i>All global functions in the file are defined here.</i></p>
-
-<h2><a name="hfilestructure">A.2 C Header File Structure</a></h2>
-
-<pre>
-/****************************************************************************
- * <i><Relative path to the file></i>
- * <i><Optional one line file description></i>
- *
- * Licensed to the Apache Software Foundation (ASF) under one or more
- * contributor license agreements. See the NOTICE file distributed with
- * this work for additional information regarding copyright ownership. The
- * ASF licenses this file to you under the Apache License, Version 2.0 (the
- * "License"); you may not use this file except in compliance with the
- * License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
- * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
- * License for the specific language governing permissions and limitations
- * under the License.
- *
- ****************************************************************************/
-</pre>
-<p><i>Header file <a href="#idempotence">idempotence</a> definitions go here</i></p>
-<pre>
-/****************************************************************************
- * Included Files
- ****************************************************************************/
-</pre>
-<p><i>All header files are included here.</i></p>
-<pre>
-/****************************************************************************
- * Pre-processor Definitions
- ****************************************************************************/
-</pre>
-<p><i>All C pre-processor macros are defined here.</i></p>
-<pre>
-/****************************************************************************
- * Public Types
- ****************************************************************************/
-
-#ifndef __ASSEMBLY__
-</pre>
-<p><i>Any types, enumerations, structures or unions are defined here.</i></p>
-<pre>
-/****************************************************************************
- * Public Data
- ****************************************************************************/
-
-#ifdef __cplusplus
-#define EXTERN extern "C"
-extern "C"
-{
-#else
-#define EXTERN extern
-#endif
-
-</pre>
-<p><i>All data declarations with global scope appear here, preceded by the definition <code>EXTERN</code>.</i></p>
-<pre>
-/****************************************************************************
- * Inline Functions
- ****************************************************************************/
-
-/****************************************************************************
- * Name: <i><Inline function name></i>
- *
- * Description:
- * <i>Description of the operation of the inline function.</i>
- *
- * Input Parameters:
- * <i>A list of input parameters, one-per-line, appears here along with a</i>
- * <i>description of each input parameter.</i>
- *
- * Returned Value:
- * <i>Description of the value returned by this function (if any),</i>
- * <i>including an enumeration of all possible error values.</i>
- *
- * Assumptions/Limitations:
- * <i>Anything else that one might need to know to use this function.</i>
- *
- ****************************************************************************/
-</pre>
-<p><i>Any static inline functions may be defined in this grouping.
-Each is preceded by a function header similar to the above.</i></p>
-<pre>
-/****************************************************************************
- * Public Function Prototypes
- ****************************************************************************/
-
-/****************************************************************************
- * Name: <i><Global function name></i>
- *
- * Description:
- * <i>Description of the operation of the function.</i>
- *
- * Input Parameters:
- * <i>A list of input parameters, one-per-line, appears here along with a</i>
- * <i>description of each input parameter.</i>
- *
- * Returned Value:
- * <i>Description of the value returned by this function (if any),</i>
- * <i>including an enumeration of all possible error values.</i>
- *
- * Assumptions/Limitations:
- * <i>Anything else that one might need to know to use this function.</i>
- *
- ****************************************************************************/
-</pre>
-<p><i>All global functions in the file are prototyped here. The keyword <code>extern</code> or the definition <code>EXTERN</code> are never used with function prototypes.</i></p>
-<pre>
-#undef EXTERN
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* __INCLUDE_ASSERT_H */
-</pre>
-<p><i>Ending with the header file <a href="#idempotence">idempotence</a> <code>#endif</code>.</i></p>
-
-</div>
-</div>
-
-</body>
-</html>
diff --git a/Documentation/NuttXGettingStarted.html b/Documentation/NuttXGettingStarted.html
deleted file mode 100644
index 6793c29..0000000
--- a/Documentation/NuttXGettingStarted.html
+++ /dev/null
@@ -1,25 +0,0 @@
-<html>
-<head>
-<title>NuttX Getting Started</title>
-</head>
-
-<body background="backgd.gif">
-<hr><hr>
-<table width ="100%">
- <tr align="center" bgcolor="#e4e4e4">
- <td>
- <h1><big><font color="#3c34ec"><i>Getting Started with NuttX</i></font></big></h1>
- <p>Last Updated: December 31, 2011</p>
- </td>
- </tr>
-</table>
-<hr><hr>
-<p><b>Getting Started</b>.
- There is no official "Getting Started" Guide for NuttX yet.
- However, most everything that you need to get started with NuttX can be found in the
- <a href="https://github.com/apache/incubator-nuttx/blob/master/README.txt" target="_blank">NuttX README.txt</a>.
-</p>
-<p>There is an unofficial introductory guide to NuttX available called the
- <a href="https://nuttx-companion.readthedocs.io/">NuttX Companion</a>.</p>
-</body>
-</html>
diff --git a/Documentation/README.html b/Documentation/README.html
deleted file mode 100644
index 3024cf5..0000000
--- a/Documentation/README.html
+++ /dev/null
@@ -1,649 +0,0 @@
-<html>
-<head>
-<title>README Files</title>
-</head>
-<body background="backgd.gif">
-<hr><hr>
-<table width ="100%">
- <tr align="center" bgcolor="#e4e4e4">
- <td>
- <h1><big><font color="#3c34ec"><i>NuttX README Files</i></font></big></h1>
- <p>Last Updated: February 17, 2019</p>
- </td>
- </tr>
-</table>
-<p>
- Additional information can be found in the <code>Documentation/</code> directory and
- also in <code>README</code> files that are scattered throughout the source tree.
- Below is a guide to the available <code>README</code> files.
- Some <code>README</code> files contain more important information than others.
- The key <code>README</code> files are shown in <code><i><b>BOLDFACE/ITALIC</i></b></code> below.
-</p>
-<p>
- Below is a guide to the available README files in the NuttX source tree:
-</p>
-
-<ul><pre>
-nuttx/
- |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/README.txt" target="_blank"><b>README.txt</b></a>
- |- arch/
- | |
- | |- arm/
- | | `- src
- | | |- common
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/arch/arm/src/common/README_lwl_console.txt" target="_blank"><b>README_lwl_console.txt</b></a>
- | | |- lpc214x
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/arch/arm/src/lpc214x/README.txt" target="_blank">README.txt</a>
- | | `- stm32l4
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/arch/arm/src/stm32l4/README.txt" target="_blank">stm32l4/README.txt</a>
- | |- renesas/
- | | |- include/
- | | | `-<a href="https://bitbucket.org/nuttx/nuttx/src/master/arch/renesas/include/README.txt" target="_blank">README.txt</a>
- | | |- src/
- | | | `-<a href="https://bitbucket.org/nuttx/nuttx/src/master/arch/renesas/src/README.txt" target="_blank">README.txt</a>
- | |- x86/
- | | |- include/
- | | | `-<a href="https://bitbucket.org/nuttx/nuttx/src/master/arch/x86/include/README.txt" target="_blank">README.txt</a>
- | | `- src/
- | | `-<a href="https://bitbucket.org/nuttx/nuttx/src/master/arch/x86/src/README.txt" target="_blank">README.txt</a>
- | |- z80/
- | | |- src/z80
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/arch/z80/src/z80/README.txt" target="_blank">README.txt</a>
- | | `- src/z180
- | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/arch/z80/src/z180/README.txt" target="_blank">README.txt</a>
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/arch/z80/src/z180/z180_mmu.txt" target="_blank">z180_mmu.txt</a>
- | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/arch/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- |- audio/
- | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/audio/README.txt" target="_blank"><b><i>README.txt</i></b></a>
-
- |- boards/
- | |- arm/
- | | |- a1x/
- | | | `- pcduino-a10/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/a1x/pcduino-a10/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- am335x/
- | | | `- beaglebone-black/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/am335x/beaglebone-black/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- c5471/
- | | | `- c5471evm/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/c5471/c5471evm/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- cxd56xx/
- | | | `- spresense/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/cxd56xx/spresense/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- dm320/
- | | | `- ntosd-dm320/
- | | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/dm320/ntosd-dm320/doc/README.txt" target="_blank"><i>doc/README.txt</i></a>
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/dm320/ntosd-dm320/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- efm32/
- | | | |- efm32-g8xx-stk/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/efm32/efm32-g8xx-stk/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- efm32gg-stk3700/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/efm32/efm32gg-stk3700/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | `- olimex-efm32g880f128-stk/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/efm32/olimex-efm32g880f128-stk/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- imx6/
- | | | `- sabre-6quad/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/imx6/sabre-6quad/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- imxrt/
- | | | |- imxrt1050-evk/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/imxrt/imxrt1050-evk/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | `- imxrt1060-evk/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/imxrt/imxrt1060-evk/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- kinetis/
- | | | |- freedom-k28f/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/kinetis/freedom-k28f/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- freedom-k64f/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/kinetis/freedom-k64f/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- freedom-k66f/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/kinetis/freedom-k66f/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- kwikstik-k40/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/kinetis/kwikstik-k40/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- teensy-3.x/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/kinetis/teensy-3.x/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- twr-k60n512/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/kinetis/twr-k60n512/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | `- twr-k64f120m/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/kinetis/twr-k64f120m/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- kl/
- | | | |- freedom-kl25z/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/kl/freedom-kl25z/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- freedom-kl26z/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/kl/freedom-kl26z/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | `- teensy-lc/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/kl/teensy-lc/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- lc823450/
- | | | `- lc823450-xgevk/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/lc823450/lc823450-xgevk/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- lpc17xx_40xx/
- | | | |- lincoln60/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/lpc17xx_40xx/lincoln60/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- lpc4088-devkit/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/lpc17xx_40xx/lpc4088-devkit/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- lpc4088-quickstart/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/lpc17xx_40xx/lpc4088-quickstart/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- lpcxpresso-lpc1768/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/lpc17xx_40xx/lpcxpresso-lpc1768/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- lx_cpu/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/lpc17xx_40xx/lx_cpu/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- mbed/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/lpc17xx_40xx/mbed/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- mcb1700/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/lpc17xx_40xx/mcb1700/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- olimex-lpc1766stk/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/lpc17xx_40xx/olimex-lpc1766stk/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- open1788/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/lpc17xx_40xx/open1788/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- pnev5180b/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/lpc17xx_40xx/pnev5180b/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- u-blox-c027/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/lpc17xx_40xx/u-blox-c027/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | `- zkit-arm-1769/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/lpc17xx_40xx/zkit-arm-1769/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- lpc214x/
- | | | |- mcu123-lpc214x/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/lpc214x/mcu123-lpc214x/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | `- zp214xpa/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/lpc214x/zp214xpa/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- lpc2378/
- | | | `- olimex-lpc2378/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/lpc2378/olimex-lpc2378/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- lpc31xx/
- | | | |- ea3131/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/lpc31xx/ea3131/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- ea3152/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/lpc31xx/ea3152/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | `- olimex-lpc-h3131/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/lpc31xx/olimex-lpc-h3131/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- lpc43xx/
- | | | |- bambino-200e/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/lpc43xx/bambino-200e/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- lpc4330-xplorer/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/lpc43xx/lpc4330-xplorer/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- lpc4337-ws/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/lpc43xx/lpc4337-ws/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- lpc4357-evb/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/lpc43xx/lpc4357-evb/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | `- lpc4370-link2/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/lpc43xx/lpc4370-link2/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- lpc54xx/
- | | | `- lpcxpresso-lpc54628/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/lpc54xx/lpcxpresso-lpc54628/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- max326xx/
- | | | `- max32660-evsys/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/max326xx/max32660-evsys/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- moxart/
- | | | `- moxa/
- | | |- nrf52/
- | | | `- nrf52-generic/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/nrf52/nrf52-generic/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- nuc1xx/
- | | | `- nutiny-nuc120/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/nuc1xx/nutiny-nuc120/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- s32k1xx/
- | | | |- s32k118evb/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/s32k1xx/s32k118evb/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- s32k146evb/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/s32k1xx/s32k146evb/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | `- s32k148evb/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/s32k1xx/s32k148evb/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- sam34/
- | | | |- arduino-due/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/sam34/arduino-due/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- flipnclick-sam3x/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/sam34/flipnclick-sam3x/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- sam3u-ek/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/sam34/sam3u-ek/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- sam4cmp-db/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/sam34/sam4cmp-db/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- sam4e-ek/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/sam34/sam4e-ek/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- sam4l-xplained/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/sam34/sam4l-xplained/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- sam4s-xplained/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/sam34/sam4s-xplained/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | `- sam4s-xplained-pro/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/sam34/sam4s-xplained-pro/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- sama5/
- | | | |- sama5d2-xult/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/sama5/sama5d2-xult/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- sama5d3x-ek/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/sama5/sama5d3x-ek/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- sama5d3-xplained/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/sama5/sama5d3-xplained/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | `- sama5d4-ek/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/sama5/sama5d4-ek/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- samd2l2/
- | | | |- arduino-m0/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/samd2l2/arduino-m0/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- samd20-xplained/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/samd2l2/samd20-xplained/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- samd21-xplained/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/samd2l2/samd21-xplained/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | `- saml21-xplained/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/samd2l2/saml21-xplained/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- samd5e5/
- | | | `- metro-m4/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/samd5e5/metro-m4/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- samv7/
- | | | |- same70-xplained/
- | | | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/samv7/same70-xplained/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | `- samv71-xult/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/samv7/samv71-xult/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- stm32/
- | | | |- axoloti/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/axoloti/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- b-g474e-dpow1/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/b-g474e-dpow1/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- clicker2-stm32/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/clicker2-stm32/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- cloudctrl/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/cloudctrl/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- fire-stm32v2/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/fire-stm32v2/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- hymini-stm32v/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/hymini-stm32v/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- maple/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/maple/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- mikroe-stm32f4/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/mikroe-stm32f4/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- nucleo-f103rb/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/nucleo-f103rb/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- nucleo-f207zg/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/nucleo-f207zg/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- nucleo-f302r8/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/nucleo-f302r8/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- nucleo-f303re/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/nucleo-f303re/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- nucleo-f303ze/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/nucleo-f303ze/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- nucleo-f334r8/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/nucleo-f334r8/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- nucleo-f410rb/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/nucleo-f410rb/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- nucleo-f446re/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/nucleo-f446re/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- nucleo-f4x1re/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/nucleo-f4x1re/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- nucleo-l152re/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/nucleo-l152re/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- olimexino-stm32/
- | | | |- olimex-stm32-e407/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/olimex-stm32-e407/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- olimex-stm32-h405/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/olimex-stm32-h405/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- olimex-stm32-h407/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/olimex-stm32-h407/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- olimex-stm32-p107/
- | | | |- olimex-stm32-p207/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/olimex-stm32-p207/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- olimex-stm32-p407/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/olimex-stm32-p407/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- omnibusf4/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/omnibusf4/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- photon/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/photon/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- shenzhou/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/shenzhou/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- stm32_tiny/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/stm32_tiny/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- stm3210e-eval/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/stm3210e-eval/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- stm3220g-eval/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/stm3220g-eval/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- stm3240g-eval/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/stm3240g-eval/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- stm32butterfly2/
- | | | |- stm32f103-minimum/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/stm32f103-minimum/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- stm32f334-disco/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/stm32f334-disco/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- stm32f3discovery/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/stm32f3discovery/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- stm32f411e-disco/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/stm32f411e-disco/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- stm32f429i-disco/
- | | | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/stm32f429i-disco/configs/fb/README.txt" target="_blank"><i>configs/fb/README.txt</i></a>
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/stm32f429i-disco/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- stm32f4discovery/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/stm32f4discovery/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- stm32ldiscovery/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/stm32ldiscovery/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- stm32vldiscovery/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/stm32vldiscovery/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | `- viewtool-stm32f107/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32/viewtool-stm32f107/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- stm32f0l0g0/
- | | | |- b-l072z-lrwan1/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32f0l0g0/b-l072z-lrwan1/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- nucleo-f072rb/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32f0l0g0/nucleo-f072rb/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- nucleo-f091rc/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32f0l0g0/nucleo-f091rc/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- nucleo-g070rb/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32f0l0g0/nucleo-g070rb/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- nucleo-g071rb/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32f0l0g0/nucleo-g071rb/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- nucleo-l073rz/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32f0l0g0/nucleo-l073rz/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- stm32f051-discovery/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32f0l0g0/stm32f051-discovery/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | `- stm32f072-discovery/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32f0l0g0/stm32f072-discovery/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- stm32f7/
- | | | |- nucleo-144/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32f7/nucleo-144/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- stm32f746g-disco/
- | | | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32f7/stm32f746g-disco/configs/fb/README.txt" target="_blank"><i>configs/fb/README.txt</i></a>
- | | | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32f7/stm32f746g-disco/configs/nxdemo/README.txt" target="_blank"><i>configs/nxdemo/README.txt</i></a>
- | | | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32f7/stm32f746g-disco/configs/nxterm/README.txt" target="_blank"><i>configs/nxterm/README.txt</i></a>
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32f7/stm32f746g-disco/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- stm32f746-ws/
- | | | `- stm32f769i-disco/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32f7/stm32f769i-disco/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- stm32h7/
- | | | `- nucleo-h743zi/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32h7/nucleo-h743zi/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- stm32l4/
- | | | |- b-l475e-iot01a/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32l4/b-l475e-iot01a/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- nucleo-l432kc/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32l4/nucleo-l432kc/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- nucleo-l452re/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32l4/nucleo-l452re/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- nucleo-l476rg/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32l4/nucleo-l476rg/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- nucleo-l496zg/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32l4/nucleo-l496zg/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- stm32l476-mdk/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32l4/stm32l476-mdk/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- stm32l476vg-disco/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32l4/stm32l476vg-disco/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | `- stm32l4r9ai-disco/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/stm32l4/stm32l4r9ai-disco/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- str71x/
- | | | `- olimex-strp711/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/str71x/olimex-strp711/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- tiva/
- | | | |- dk-tm4c129x/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/tiva/dk-tm4c129x/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- eagle100/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/tiva/eagle100/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- ekk-lm3s9b96/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/tiva/ekk-lm3s9b96/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- launchxl-cc1310/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/tiva/launchxl-cc1310/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- launchxl-cc1312r1/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/tiva/launchxl-cc1312r1/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- lm3s6432-s2e/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/tiva/lm3s6432-s2e/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- lm3s6965-ek/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/tiva/lm3s6965-ek/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- lm3s8962-ek/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/tiva/lm3s8962-ek/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- lm4f120-launchpad/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/tiva/lm4f120-launchpad/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- tm4c123g-launchpad/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/tiva/tm4c123g-launchpad/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | `- tm4c1294-launchpad/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/tiva/tm4c1294-launchpad/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- tms570/
- | | | |- launchxl-tms57004/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/tms570/launchxl-tms57004/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | `- tms570ls31x-usb-kit/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/tms570/tms570ls31x-usb-kit/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | `- xmc4/
- | | `- xmc4500-relax/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/arm/xmc4/xmc4500-relax/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | |- avr/
- | | |- at32uc3/
- | | | `- avr32dev1/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/avr/at32uc3/avr32dev1/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- at90usb/
- | | | |- micropendous3/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/avr/at90usb/micropendous3/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | `- teensy-2.0/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/avr/at90usb/teensy-2.0/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | `- atmega/
- | | |- amber/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/avr/atmega/amber/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- arduino-mega2560/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/avr/atmega/arduino-mega2560/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | `- moteino-mega/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/avr/atmega/moteino-mega/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | |- hc/
- | | `- m9s12/
- | | |- demo9s12ne64/
- | | |` `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/hc/m9s12/demo9s12ne64/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | `- ne64badge/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/hc/m9s12/ne64badge/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | |- mips/
- | | |- pic32mx/
- | | | |- mirtoo/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/mips/pic32mx/mirtoo/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- pic32mx7mmb/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/mips/pic32mx/pic32mx7mmb/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- pic32mx-starterkit/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/mips/pic32mx/pic32mx-starterkit/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- sure-pic32mx/
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/mips/pic32mx/sure-pic32mx/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | `- ubw32/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/mips/pic32mx/ubw32/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | `-pic32mz/
- | | |- flipnclick-pic32mz/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/mips/pic32mz/flipnclick-pic32mz/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | `- pic32mz-starterkit/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/mips/pic32mz/pic32mz-starterkit/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | |- misoc/
- | | `- lm32/
- | | `- misoc/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/misoc/lm32/misoc/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | |- or1k/
- | | `- mor1kx/
- | | `- or1k/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/or1k/mor1kx/or1k/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | |- renesas/
- | | |- m16c/
- | | | `- skp16c26/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/renesas/m16c/skp16c26/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | `-sh1/
- | | `- us7032evb1/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/renesas/sh1/us7032evb1/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | |- risc-v/
- | | |- gap8/
- | | | `- gapuino/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/risc-v/gap8/gapuino/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | `-nr5m100/
- | | `- nr5m100-nexys4/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/risc-v/nr5m100/nr5m100-nexys4/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | |- sim/
- | | `- sim/
- | | `- sim/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/sim/sim/sim/include/README.txt" target="_blank"><b><i>include/README.txt</i></b></a>
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/sim/sim/sim/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | |- x86/
- | | `- qemu/
- | | `- qemu-i486/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/x86/qemu/qemu-i486/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | |- xtensa/
- | | `- esp32/
- | | `- esp32-core/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/xtensa/esp32/esp32-core/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | |- z16/
- | | `- z16f/
- | | `- z16f2800100zcog/
- | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/z16/z16f/z16f2800100zcog/configs/nsh/README.txt" target="_blank"><b><i>configs/nsh/README.txt</i></b></a>
- | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/z16/z16f/z16f2800100zcog/configs/ostest/README.txt" target="_blank"><i>configs/ostest/README.txt</i></a>
- | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/z16/z16f/z16f2800100zcog/configs/pashello/README.txt" target="_blank"><i>configs/pashello/README.txt</i></a>
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/z16/z16f/z16f2800100zcog/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | |- z80/
- | | |- ez80/
- | | | |- ez80f910200kitg/
- | | | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/z80/ez80/ez80f910200kitg/configs/ostest/README.txt" target="_blank"><i>configs/ostest/README.txt</i></a>
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/z80/ez80/ez80f910200kitg/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- ez80f910200zco/
- | | | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/z80/ez80/ez80f910200zco/configs/dhcpd/README.txt" target="_blank"><i>configs/dhcpd/README.txt</i></a>
- | | | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/z80/ez80/ez80f910200zco/configs/httpd/README.txt" target="_blank"><i>configs/httpd/README.txt/</i></a>
- | | | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/z80/ez80/ez80f910200zco/configs/nettest/README.txt" target="_blank"><i>configs/nettest/README.txt</i></a>
- | | | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/z80/ez80/ez80f910200zco/configs/nsh/README.txt" target="_blank"><i>configs/nsh/README.txt</i></a>
- | | | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/z80/ez80/ez80f910200zco/configs/poll/README.txt" target="_blank"><b><i>configs/poll/README.txt</i></b></a>
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/z80/ez80/ez80f910200zco/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | |- makerlisp/
- | | | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/z80/ez80/makerlisp/configs/nsh_flash/README.txt" target="_blank"><i>configs/nsh_flash/README.txt</i></b></a>
- | | | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/z80/ez80/makerlisp/configs/nsh_ram/README.txt" target="_blank"><i>configs/nsh_ram/README.txt</i></b></a>
- | | | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/z80/ez80/makerlisp/configs/sdboot/README.txt" target="_blank"><i>configs/sdboot/README.txt</i></b></a>
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/z80/ez80/makerlisp/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | `- z20x/
- | | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/z80/ez80/z20x/configs/nsh_flash/README.txt" target="_blank"><i>configs/nsh_flash/README.txt</i></b></a>
- | | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/z80/ez80/z20x/configs/nsh_ram/README.txt" target="_blank"><i>configs/nsh_ram/README.txt</i></b></a>
- | | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/z80/ez80/z20x/configs/sdboot/README.txt" target="_blank"><i>configs/sdboot/README.txt</i></b></a>
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/z80/ez80/z20x/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- z180/
- | | | `- p112/
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/z80/z180/p112/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | |- z8/
- | | | |- z8encore000zco/
- | | | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/z80/z8/z8encore000zco/configs/ostest/README.txt" target="_blank"><i>configs/ostest/README.txt</i></a>
- | | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/z80/z8/z8encore000zco/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | | `- z8f64200100kit/
- | | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/z80/z8/z8f64200100kit/configs/ostest/README.txt" target="_blank"><b><i>configs/ostest/README.txt</i></b></a>
- | | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/z80/z8/z8f64200100kit/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | `- z80/
- | | `- z80sim/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/z80/z80/z80sim/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | ` <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- |- drivers/
- | |- eeprom/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/drivers/eeprom/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | |- lcd/
- | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/drivers/lcd/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/drivers/lcd/pcf8574_lcd_backpack_readme.txt" target="_blank"><b><i>pcf8574_lcd_backpack_readme.txt</i></b></a>
- | |- mtd/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/drivers/mtd/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | |- sensors/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/drivers/sensors/README.txt" target="_blank">README.txt</a>
- | |- syslog/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/drivers/syslog/README.txt" target="_blank">README.txt</a>
- | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/drivers/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- |- fs/
- | |- binfs/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/fs/binfs/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | |- cromfs/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/fs/cromfs/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | |- mmap/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/fs/mmap/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | |- nxffs/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/fs/nxffs/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | |- smartfs/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/fs/smartfs/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | |- procfs/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/fs/procfs/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | |- spiffs/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/fs/spiffs/README.txt" target="_blank"><b><i>README.md</i></b></a>
- | `- unionfs/
- | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/fs/unionfs/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- |- graphics/
- | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/graphics/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- |-libs
- | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/libs/README.txt" target="_blank">README.txt</a>
- | |- libc/
- | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/libs/libc/zoneinfo/README.txt" target="_blank">zoneinfo/README.txt</a>
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/libs/libc/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | |- libdsp/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/libs/libdsp/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | |- libnx/
- | | |- <a href="https://bitbucket.org/nuttx/nuttx/src/master/libs/libnx/nxfonts/README.txt" target="_blank">libnx/README.txt</a>
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/libs/libnx/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | |- libxx/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/libs/libxx/README.txt" target="_blank"><b><i>README.txt</i></b></a>
-
- |- mm/
- | |- shm/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/mm/shm/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/mm/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- |- net/
- | |- sixlowpan/
- | | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/net/sixlowpan/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/net/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- |- pass1/
- | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/pass1/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- |- syscall/
- | `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/syscall/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- `- tools/
- `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/tools/README.txt" target="_blank"><b><i>README.txt</i></b></a>
-</pre></ul>
-
-<p>
- Below is a guide to the available README files in the semi-optional <code>apps/</code> source tree:
-</p>
-
-<ul><pre>
-apps/
- |- <a href="https://bitbucket.org/nuttx/apps/src/master/README.txt" target="_blank"><b>README.txt</b></a>
- |- examples/
- | |- <a href="https://bitbucket.org/nuttx/apps/src/master/examples/bastest/README.txt" target="_blank">bastest/README.txt</a>
- | |- <a href="https://bitbucket.org/nuttx/apps/src/master/examples/json/README.txt" target="_blank">json/README.txt</a>
- | |- <a href="https://bitbucket.org/nuttx/apps/src/master/examples/pashello/README.txt" target="_blank">pashello/README.txt</a>
- | `- <a href="https://bitbucket.org/nuttx/apps/src/master/examples/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- |- gpsutils/
- | `- <a href="https://bitbucket.org/nuttx/apps/src/master/gpsutils/minmea/README.txt" target="_blank">"<b><i>minmea/README.txt</i></b></a>
- |- graphics/
- | |- <a href="https://bitbucket.org/nuttx/apps/src/master/graphics/tiff/README.txt" target="_blank">"<b><i>tiff/README.txt</i></b></a>
- | `- <a href="https://bitbucket.org/nuttx/apps/src/master/graphics/traveler/tools/tcledit/README.txt" target="_blank">"<b><i>traveler/tools/tcledit/README.txt</i></b></a>
- |- interpreters/
- | |- <a href="https://bitbucket.org/nuttx/apps/src/master/interpreters/bas/README.txt" target="_blank"><b><i>bas/README.txt</i></b></a>
- | |- <a href="https://bitbucket.org/nuttx/apps/src/master/interpreters/ficl/README.txt" target="_blank"><b><i>ficl/README.txt</i></b></a>
- | `- <a href="https://bitbucket.org/nuttx/apps/src/master/interpreters/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- |- modbus/
- | `- <a href="https://bitbucket.org/nuttx/apps/src/master/modbus/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- |- netutils/
- | | |- <a href="https://bitbucket.org/nuttx/apps/src/master/netutils/discover/README.txt" target="_blank">discover/README.txt</a>
- | | |- <a href="https://bitbucket.org/nuttx/apps/src/master/netutils/ftpc/README.txt" target="_blank">ftpc/README.txt</a>
- | | |- <a href="https://bitbucket.org/nuttx/apps/src/master/netutils/json/README.txt" target="_blank">json/README.txt</a>
- | | |- <a href="https://bitbucket.org/nuttx/apps/src/master/netutils/telnetd/README.txt" target="_blank">telnetd/README.txt</a>
- | `- <a href="https://bitbucket.org/nuttx/apps/src/master/netutils/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- |- nshlib/
- | `- <a href="https://bitbucket.org/nuttx/apps/src/master/nshlib/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- |- NxWidgets/
- | |- Doxygen
- | | `- <a href="https://bitbucket.org/nuttx/apps/src/master/graphics/NxWidgets/Doxygen/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | |- tools
- | | `- <a href="https://bitbucket.org/nuttx/apps/src/master/graphics/NxWidgets/tools/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | |- UnitTests
- | | `- <a href="https://bitbucket.org/nuttx/apps/src/master/graphics/NxWidgets/UnitTests/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- | `- <a href="https://bitbucket.org/nuttx/apps/src/master/graphics/NxWidgets/README.txt" target="_blank"><b><i>README.txt</i></b></a>
- |- system/
- | |- <a href="https://bitbucket.org/nuttx/apps/src/master/system/cdcacm/README.txt" target="_blank"><b><i>cdcacm/README.txt</i></b></a>
- | |- <a href="https://bitbucket.org/nuttx/apps/src/master/system/i2c/README.txt" target="_blank"><b><i>i2c/README.txt</i></b></a>
- | |- <a href="https://bitbucket.org/nuttx/apps/src/master/system/inifile/README.txt" target="_blank">inifile/README.txt</a>
- | |- <a href="https://bitbucket.org/nuttx/apps/src/master/system/install/README.txt" target="_blank">install/README.txt</a>
- | |- <a href="https://bitbucket.org/nuttx/apps/src/master/system/nsh/README.txt" target="_blank"><b><i>nsh/README.txt</i></b></a>
- | |- <a href="https://bitbucket.org/nuttx/apps/src/master/system/nxplayer/README.txt" target="_blank"><b><i>nxplayer/README.txt</i></b></a>
- | |- <a href="https://bitbucket.org/nuttx/apps/src/master/system/psmq/README.txt" target="_blank"><b><i>psmq/README.txt</i></b></a>
- | |- <a href="https://bitbucket.org/nuttx/apps/src/master/system/symtab/README.txt" target="_blank"><b><i>symtab/README.txt</i></b></a>
- | |- <a href="https://bitbucket.org/nuttx/apps/src/master/system/termcurses/README.txt" target="_blank"><b><i>termcurses/README.txt</i></b></a>
- | |- <a href="https://bitbucket.org/nuttx/apps/src/master/system/usbmsc/README.txt" target="_blank">usbmsc/README.txt</a>
- | `- <a href="https://bitbucket.org/nuttx/apps/src/master/system/zmodem/README.txt" target="_blank">zmodem/README.txt</a>
- `- wireless
- |- bluetooth
- | `- <a href="https://bitbucket.org/nuttx/apps/src/master/wireless/bluetooth/btsak/README.txt" target="_blank"><b>btsak/README.txt</b></a>
- `- ieee802154
- `- <a href="https://bitbucket.org/nuttx/apps/src/master/wireless/ieee802154/i8sak/README.txt" target="_blank"><b>i8sak/README.txt</b></a>
-</pre></ul>
-
-<p>
- Additional README.txt files in the other, related repositories:
-</p>
-
-<ul><pre>
-buildroot/
- `- <a href="https://bitbucket.org/nuttx/buildroot/src/master/README.txt" target="_blank"><b><i>README.txt</i></b></a>
-
-tools/
- `- <a href="https://bitbucket.org/nuttx/tools/src/master/README.txt" target="_blank"><b><i>README.txt</i></b></a>
-
-uClibc++/
- `- <a href="https://bitbucket.org/nuttx/uclibc/src/master/README.txt" target="_blank"><b><i>README.txt</i></b></a>
-
-</pre></ul>
-</body>
-</html>
diff --git a/Documentation/backgd.gif b/Documentation/backgd.gif
deleted file mode 100644
index e81f153..0000000
Binary files a/Documentation/backgd.gif and /dev/null differ
diff --git a/Documentation/redirect.html b/Documentation/redirect.html
deleted file mode 100644
index 13e75cd..0000000
--- a/Documentation/redirect.html
+++ /dev/null
@@ -1,20 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
-<html>
-<head>
-<title>The NuttX RTOS</title>
-<meta http-equiv="REFRESH" content="5;url=http://nuttx.org"></HEAD>
-<body background="backgd.gif">
-<table width ="100%">
- <tr align="center" bgcolor="#e4e4e4">
- <td>
- <h1><big><font color="#3c34ec"><i>The NuttX RTOS</i></font></big></h1>
- </td>
- </tr>
-</table>
-<hr><hr>
-<big><center>
- The NuttX RTOS web site has moved to <a href="http://nuttx.org">nuttx.org</a>.
- Please update your bookmarks and wait while you are redirected there.
-</center></big>
-</body>
-</html>
diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 0000000..a485625
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1 @@
+/_build
diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..36feb34
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,22 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS ?=
+SPHINXBUILD ?= sphinx-build
+SOURCEDIR = .
+BUILDDIR = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+ @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+html: clean
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+ @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/doc/Pipfile b/doc/Pipfile
new file mode 100644
index 0000000..5a000c6
--- /dev/null
+++ b/doc/Pipfile
@@ -0,0 +1,14 @@
+[[source]]
+name = "pypi"
+url = "https://pypi.org/simple"
+verify_ssl = true
+
+[dev-packages]
+
+[packages]
+sphinx = "*"
+recommonmark = "*"
+sphinx_rtd_theme = "*"
+
+[requires]
+python_version = "3.7"
diff --git a/doc/Pipfile.lock b/doc/Pipfile.lock
new file mode 100644
index 0000000..73e1881
--- /dev/null
+++ b/doc/Pipfile.lock
@@ -0,0 +1,244 @@
+{
+ "_meta": {
+ "hash": {
+ "sha256": "d3d0367e13851216b99ed5af8e34abf7e35fecdae5484dc2b61400b733f1536f"
+ },
+ "pipfile-spec": 6,
+ "requires": {
+ "python_version": "3.7"
+ },
+ "sources": [
+ {
+ "name": "pypi",
+ "url": "https://pypi.org/simple",
+ "verify_ssl": true
+ }
+ ]
+ },
+ "default": {
+ "alabaster": {
+ "hashes": [
+ "sha256:446438bdcca0e05bd45ea2de1668c1d9b032e1a9154c2c259092d77031ddd359",
+ "sha256:a661d72d58e6ea8a57f7a86e37d86716863ee5e92788398526d58b26a4e4dc02"
+ ],
+ "version": "==0.7.12"
+ },
+ "babel": {
+ "hashes": [
+ "sha256:1aac2ae2d0d8ea368fa90906567f5c08463d98ade155c0c4bfedd6a0f7160e38",
+ "sha256:d670ea0b10f8b723672d3a6abeb87b565b244da220d76b4dba1b66269ec152d4"
+ ],
+ "version": "==2.8.0"
+ },
+ "certifi": {
+ "hashes": [
+ "sha256:5930595817496dd21bb8dc35dad090f1c2cd0adfaf21204bf6732ca5d8ee34d3",
+ "sha256:8fc0819f1f30ba15bdb34cceffb9ef04d99f420f68eb75d901e9560b8749fc41"
+ ],
+ "version": "==2020.6.20"
+ },
+ "chardet": {
+ "hashes": [
+ "sha256:84ab92ed1c4d4f16916e05906b6b75a6c0fb5db821cc65e70cbd64a3e2a5eaae",
+ "sha256:fc323ffcaeaed0e0a02bf4d117757b98aed530d9ed4531e3e15460124c106691"
+ ],
+ "version": "==3.0.4"
+ },
+ "commonmark": {
+ "hashes": [
+ "sha256:452f9dc859be7f06631ddcb328b6919c67984aca654e5fefb3914d54691aed60",
+ "sha256:da2f38c92590f83de410ba1a3cbceafbc74fee9def35f9251ba9a971d6d66fd9"
+ ],
+ "version": "==0.9.1"
+ },
+ "docutils": {
+ "hashes": [
+ "sha256:0c5b78adfbf7762415433f5515cd5c9e762339e23369dbe8000d84a4bf4ab3af",
+ "sha256:c2de3a60e9e7d07be26b7f2b00ca0309c207e06c100f9cc2a94931fc75a478fc"
+ ],
+ "version": "==0.16"
+ },
+ "idna": {
+ "hashes": [
+ "sha256:b307872f855b18632ce0c21c5e45be78c0ea7ae4c15c828c20788b26921eb3f6",
+ "sha256:b97d804b1e9b523befed77c48dacec60e6dcb0b5391d57af6a65a312a90648c0"
+ ],
+ "version": "==2.10"
+ },
+ "imagesize": {
+ "hashes": [
+ "sha256:6965f19a6a2039c7d48bca7dba2473069ff854c36ae6f19d2cde309d998228a1",
+ "sha256:b1f6b5a4eab1f73479a50fb79fcf729514a900c341d8503d62a62dbc4127a2b1"
+ ],
+ "version": "==1.2.0"
+ },
+ "jinja2": {
+ "hashes": [
+ "sha256:89aab215427ef59c34ad58735269eb58b1a5808103067f7bb9d5836c651b3bb0",
+ "sha256:f0a4641d3cf955324a89c04f3d94663aa4d638abe8f733ecd3582848e1c37035"
+ ],
+ "version": "==2.11.2"
+ },
+ "markupsafe": {
+ "hashes": [
+ "sha256:00bc623926325b26bb9605ae9eae8a215691f33cae5df11ca5424f06f2d1f473",
+ "sha256:09027a7803a62ca78792ad89403b1b7a73a01c8cb65909cd876f7fcebd79b161",
+ "sha256:09c4b7f37d6c648cb13f9230d847adf22f8171b1ccc4d5682398e77f40309235",
+ "sha256:1027c282dad077d0bae18be6794e6b6b8c91d58ed8a8d89a89d59693b9131db5",
+ "sha256:13d3144e1e340870b25e7b10b98d779608c02016d5184cfb9927a9f10c689f42",
+ "sha256:24982cc2533820871eba85ba648cd53d8623687ff11cbb805be4ff7b4c971aff",
+ "sha256:29872e92839765e546828bb7754a68c418d927cd064fd4708fab9fe9c8bb116b",
+ "sha256:43a55c2930bbc139570ac2452adf3d70cdbb3cfe5912c71cdce1c2c6bbd9c5d1",
+ "sha256:46c99d2de99945ec5cb54f23c8cd5689f6d7177305ebff350a58ce5f8de1669e",
+ "sha256:500d4957e52ddc3351cabf489e79c91c17f6e0899158447047588650b5e69183",
+ "sha256:535f6fc4d397c1563d08b88e485c3496cf5784e927af890fb3c3aac7f933ec66",
+ "sha256:596510de112c685489095da617b5bcbbac7dd6384aeebeda4df6025d0256a81b",
+ "sha256:62fe6c95e3ec8a7fad637b7f3d372c15ec1caa01ab47926cfdf7a75b40e0eac1",
+ "sha256:6788b695d50a51edb699cb55e35487e430fa21f1ed838122d722e0ff0ac5ba15",
+ "sha256:6dd73240d2af64df90aa7c4e7481e23825ea70af4b4922f8ede5b9e35f78a3b1",
+ "sha256:717ba8fe3ae9cc0006d7c451f0bb265ee07739daf76355d06366154ee68d221e",
+ "sha256:79855e1c5b8da654cf486b830bd42c06e8780cea587384cf6545b7d9ac013a0b",
+ "sha256:7c1699dfe0cf8ff607dbdcc1e9b9af1755371f92a68f706051cc8c37d447c905",
+ "sha256:88e5fcfb52ee7b911e8bb6d6aa2fd21fbecc674eadd44118a9cc3863f938e735",
+ "sha256:8defac2f2ccd6805ebf65f5eeb132adcf2ab57aa11fdf4c0dd5169a004710e7d",
+ "sha256:98c7086708b163d425c67c7a91bad6e466bb99d797aa64f965e9d25c12111a5e",
+ "sha256:9add70b36c5666a2ed02b43b335fe19002ee5235efd4b8a89bfcf9005bebac0d",
+ "sha256:9bf40443012702a1d2070043cb6291650a0841ece432556f784f004937f0f32c",
+ "sha256:ade5e387d2ad0d7ebf59146cc00c8044acbd863725f887353a10df825fc8ae21",
+ "sha256:b00c1de48212e4cc9603895652c5c410df699856a2853135b3967591e4beebc2",
+ "sha256:b1282f8c00509d99fef04d8ba936b156d419be841854fe901d8ae224c59f0be5",
+ "sha256:b2051432115498d3562c084a49bba65d97cf251f5a331c64a12ee7e04dacc51b",
+ "sha256:ba59edeaa2fc6114428f1637ffff42da1e311e29382d81b339c1817d37ec93c6",
+ "sha256:c8716a48d94b06bb3b2524c2b77e055fb313aeb4ea620c8dd03a105574ba704f",
+ "sha256:cd5df75523866410809ca100dc9681e301e3c27567cf498077e8551b6d20e42f",
+ "sha256:cdb132fc825c38e1aeec2c8aa9338310d29d337bebbd7baa06889d09a60a1fa2",
+ "sha256:e249096428b3ae81b08327a63a485ad0878de3fb939049038579ac0ef61e17e7",
+ "sha256:e8313f01ba26fbbe36c7be1966a7b7424942f670f38e666995b88d012765b9be"
+ ],
+ "version": "==1.1.1"
+ },
+ "packaging": {
+ "hashes": [
+ "sha256:4357f74f47b9c12db93624a82154e9b120fa8293699949152b22065d556079f8",
+ "sha256:998416ba6962ae7fbd6596850b80e17859a5753ba17c32284f67bfff33784181"
+ ],
+ "version": "==20.4"
+ },
+ "pygments": {
+ "hashes": [
+ "sha256:647344a061c249a3b74e230c739f434d7ea4d8b1d5f3721bc0f3558049b38f44",
+ "sha256:ff7a40b4860b727ab48fad6360eb351cc1b33cbf9b15a0f689ca5353e9463324"
+ ],
+ "version": "==2.6.1"
+ },
+ "pyparsing": {
+ "hashes": [
+ "sha256:c203ec8783bf771a155b207279b9bccb8dea02d8f0c9e5f8ead507bc3246ecc1",
+ "sha256:ef9d7589ef3c200abe66653d3f1ab1033c3c419ae9b9bdb1240a85b024efc88b"
+ ],
+ "version": "==2.4.7"
+ },
+ "pytz": {
+ "hashes": [
+ "sha256:a494d53b6d39c3c6e44c3bec237336e14305e4f29bbf800b599253057fbb79ed",
+ "sha256:c35965d010ce31b23eeb663ed3cc8c906275d6be1a34393a1d73a41febf4a048"
+ ],
+ "version": "==2020.1"
+ },
+ "recommonmark": {
+ "hashes": [
+ "sha256:29cd4faeb6c5268c633634f2d69aef9431e0f4d347f90659fd0aab20e541efeb",
+ "sha256:2ec4207a574289355d5b6ae4ae4abb29043346ca12cdd5f07d374dc5987d2852"
+ ],
+ "index": "pypi",
+ "version": "==0.6.0"
+ },
+ "requests": {
+ "hashes": [
+ "sha256:b3559a131db72c33ee969480840fff4bb6dd111de7dd27c8ee1f820f4f00231b",
+ "sha256:fe75cc94a9443b9246fc7049224f75604b113c36acb93f87b80ed42c44cbb898"
+ ],
+ "version": "==2.24.0"
+ },
+ "six": {
+ "hashes": [
+ "sha256:30639c035cdb23534cd4aa2dd52c3bf48f06e5f4a941509c8bafd8ce11080259",
+ "sha256:8b74bedcbbbaca38ff6d7491d76f2b06b3592611af620f8426e82dddb04a5ced"
+ ],
+ "version": "==1.15.0"
+ },
+ "snowballstemmer": {
+ "hashes": [
+ "sha256:209f257d7533fdb3cb73bdbd24f436239ca3b2fa67d56f6ff88e86be08cc5ef0",
+ "sha256:df3bac3df4c2c01363f3dd2cfa78cce2840a79b9f1c2d2de9ce8d31683992f52"
+ ],
+ "version": "==2.0.0"
+ },
+ "sphinx": {
+ "hashes": [
+ "sha256:97dbf2e31fc5684bb805104b8ad34434ed70e6c588f6896991b2fdfd2bef8c00",
+ "sha256:b9daeb9b39aa1ffefc2809b43604109825300300b987a24f45976c001ba1a8fd"
+ ],
+ "index": "pypi",
+ "version": "==3.1.2"
+ },
+ "sphinx-rtd-theme": {
+ "hashes": [
+ "sha256:22c795ba2832a169ca301cd0a083f7a434e09c538c70beb42782c073651b707d",
+ "sha256:373413d0f82425aaa28fb288009bf0d0964711d347763af2f1b65cafcb028c82"
+ ],
+ "index": "pypi",
+ "version": "==0.5.0"
+ },
+ "sphinxcontrib-applehelp": {
+ "hashes": [
+ "sha256:806111e5e962be97c29ec4c1e7fe277bfd19e9652fb1a4392105b43e01af885a",
+ "sha256:a072735ec80e7675e3f432fcae8610ecf509c5f1869d17e2eecff44389cdbc58"
+ ],
+ "version": "==1.0.2"
+ },
+ "sphinxcontrib-devhelp": {
+ "hashes": [
+ "sha256:8165223f9a335cc1af7ffe1ed31d2871f325254c0423bc0c4c7cd1c1e4734a2e",
+ "sha256:ff7f1afa7b9642e7060379360a67e9c41e8f3121f2ce9164266f61b9f4b338e4"
+ ],
+ "version": "==1.0.2"
+ },
+ "sphinxcontrib-htmlhelp": {
+ "hashes": [
+ "sha256:3c0bc24a2c41e340ac37c85ced6dafc879ab485c095b1d65d2461ac2f7cca86f",
+ "sha256:e8f5bb7e31b2dbb25b9cc435c8ab7a79787ebf7f906155729338f3156d93659b"
+ ],
+ "version": "==1.0.3"
+ },
+ "sphinxcontrib-jsmath": {
+ "hashes": [
+ "sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178",
+ "sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8"
+ ],
+ "version": "==1.0.1"
+ },
+ "sphinxcontrib-qthelp": {
+ "hashes": [
+ "sha256:4c33767ee058b70dba89a6fc5c1892c0d57a54be67ddd3e7875a18d14cba5a72",
+ "sha256:bd9fc24bcb748a8d51fd4ecaade681350aa63009a347a8c14e637895444dfab6"
+ ],
+ "version": "==1.0.3"
+ },
+ "sphinxcontrib-serializinghtml": {
+ "hashes": [
+ "sha256:eaa0eccc86e982a9b939b2b82d12cc5d013385ba5eadcc7e4fed23f4405f77bc",
+ "sha256:f242a81d423f59617a8e5cf16f5d4d74e28ee9a66f9e5b637a18082991db5a9a"
+ ],
+ "version": "==1.1.4"
+ },
+ "urllib3": {
+ "hashes": [
+ "sha256:3018294ebefce6572a474f0604c2021e33b3fd8006ecd11d62107a5d2a963527",
+ "sha256:88206b0eb87e6d677d424843ac5209e3fb9d0190d0ee169599165ec25e9d9115"
+ ],
+ "version": "==1.25.9"
+ }
+ },
+ "develop": {}
+}
diff --git a/doc/_static/custom.css b/doc/_static/custom.css
new file mode 100644
index 0000000..058bf37
--- /dev/null
+++ b/doc/_static/custom.css
@@ -0,0 +1,25 @@
+/* Make content wider */
+
+.wy-nav-content {
+ max-width: 1200px !important;
+}
+
+/* Make links inside C definitions more visible */
+
+.c a:link {
+ color: black;
+}
+
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+
+ .wy-table-responsive table td {
+ /* !important prevents the common CSS stylesheets from overriding
+ this as on RTD they are loaded after this stylesheet */
+ white-space: normal !important;
+ }
+
+ .wy-table-responsive {
+ overflow: visible !important;
+ }
+}
diff --git a/doc/_static/favicon.ico b/doc/_static/favicon.ico
new file mode 100644
index 0000000..4066865
Binary files /dev/null and b/doc/_static/favicon.ico differ
diff --git a/doc/applications/index.rst b/doc/applications/index.rst
new file mode 100644
index 0000000..489d45d
--- /dev/null
+++ b/doc/applications/index.rst
@@ -0,0 +1,6 @@
+Applications
+============
+
+.. note:: This is to be used to describe how applications work in NuttX as well as to ducment
+ existing ones.
+
diff --git a/doc/boards/index.rst b/doc/boards/index.rst
new file mode 100644
index 0000000..6e96a41
--- /dev/null
+++ b/doc/boards/index.rst
@@ -0,0 +1,8 @@
+Supported Boards
+================
+
+.. note::
+ Include a full list of supported boards, organized by architecture / family / vendor.
+ Each board should have its own entry, a photo, brief hardware specifications, features
+ supported (currently working in NuttX), how to flash, special toolchains required, etc.
+
diff --git a/doc/components/binfmt.rst b/doc/components/binfmt.rst
new file mode 100644
index 0000000..1267153
--- /dev/null
+++ b/doc/components/binfmt.rst
@@ -0,0 +1,372 @@
+=============
+Binary Loader
+=============
+
+The purpose of a *binary loader* is to load and
+execute modules in various *binary formats* that reside in a file
+system. Loading refers instantiating the binary module in some fashion,
+usually copy all or some of the binary module into memory and then
+linking the module with other components. In most architectures, it is
+the base FLASH code that is the primary component that the binary module
+must link with because that is where the RTOS and primary tasks reside.
+Program modules can then be executed after they have been loaded.
+
+**Binary Formats**. The binary loader provides generic support for
+different binary formats. It supports a *registration interface* that
+allows the number of support binary formats to be loaded at run time.
+Each binary format provides a common, interface for use by the binary
+loader. When asked to load a binary, the binary loader will query each
+registered binary format, providing it with the path of the binary
+object to be loaded. The binary loader will stop when first binary
+format the recognizes the binary object and successfully loads it or
+when all registered binary formats have attempt loading the binary
+object and failed.
+
+At present, the following binary formats are support by NuttX:
+
+ - **ELF**. Standard ELF formatted files.
+ - **NXFLAT**. NuttX NXFLAT formatted files. More information about the
+ NXFLAT binary format can be found in the `NXFLAT
+ documentation <NuttXNxFlat.html>`__.
+
+**Executables and Libraries** The generic binary loader logic does not
+care what it is that it being loaded. It could load an executable
+program or a library. There are no strict rules, but a library will tend
+to export symbols and a program will tend to import symbols: The program
+will use the symbols exported by the library. However, at this point in
+time, none of the supported binary formats support exporting of symbols.
+
+**binfmt**. In the NuttX source code, the short name ``binfmt`` is used
+to refer to the NuttX binary loader. This is the name of the directory
+containing the binary loader and the name of the header files and
+variables used by the binary loader.
+
+The name ``binfmt`` is the same name used by the Linux binary loader.
+However, the NuttX binary loader is an independent development and
+shares nothing with the Linux binary loader other the same name and the
+same basic functionality.
+
+Binary Loader Interface
+=======================
+
+Header Files
+------------
+
+The interface to the binary loader is described in the header file
+``include/nuttx/binfmt/binfmt.h``.
+A brief summary of the data structurs and interfaces prototyped in that
+header file are listed below.
+
+Data Structures
+---------------
+
+When a binary format registers with the binary loader, it provides a
+pointer to a write-able instance of :c:struct:`binfmt_s`.
+
+.. c:struct:: binfmt_s
+
+ .. code-block:: c
+
+ struct binfmt_s
+ {
+ FAR struct binfmt_s *next; /* Supports a singly-linked list */
+ int (*load)(FAR struct binary_s *bin); /* Verify and load binary into memory */
+ };
+
+
+ The ``load`` method is used to load the binary format into memory. It
+ returns either ``OK`` (0) meaning that the binary object was loaded
+ successfully, or a negated ``errno`` indicating why the object was not
+ loaded.
+
+.. c:struct:: binary_s
+
+ The type ``struct binary_s`` is use both to (1) describe the binary
+ object to be loaded, and if successfully loaded, (2) to provide
+ information about where and how the binary object was loaded. That
+ structure is shown below:
+
+ .. code-block:: c
+
+ struct symtab_s;
+ struct binary_s
+ {
+ /* Information provided to the loader to load and bind a module */
+
+ FAR const char *filename; /* Full path to the binary to be loaded */
+ FAR const char **argv; /* Argument list */
+ FAR const struct symtab_s *exports; /* Table of exported symbols */
+ int nexports; /* The number of symbols in exports[] */
+
+ /* Information provided from the loader (if successful) describing the
+ * resources used by the loaded module.
+ */
+
+ main_t entrypt; /* Entry point into a program module */
+ FAR void *mapped; /* Memory-mapped, address space */
+ FAR void *alloc[BINFMT_NALLOC]; /* Allocated address spaces */
+
+ /* Constructors/destructors */
+
+ #ifdef CONFIG_BINFMT_CONSTRUCTORS
+ FAR binfmt_ctor_t *ctors; /* Pointer to a list of constructors */
+ FAR binfmt_dtor_t *dtors; /* Pointer to a list of destructors */
+ uint16_t nctors; /* Number of constructors in the list */
+ uint16_t ndtors; /* Number of destructors in the list */
+ #endif
+
+ /* Address environment.
+ *
+ * addrenv - This is the handle created by up_addrenv_create() that can be
+ * used to manage the tasks address space.
+ */
+
+ #ifdef CONFIG_ARCH_ADDRENV
+ group_addrenv_t addrenv; /* Task group address environment */
+ #endif
+
+ size_t mapsize; /* Size of the mapped address region (needed for munmap) */
+
+ /* Start-up information that is provided by the loader, but may be modified
+ * by the caller between load_module() and exec_module() calls.
+ */
+
+ uint8_t priority; /* Task execution priority */
+ size_t stacksize; /* Size of the stack in bytes (unallocated) */
+ };
+
+ Where the types ``binfmt_ctor_t`` and ``binfmt_dtor_t`` define the type
+ of one C++ constructor or destructor:
+
+ .. code-block:: c
+
+ typedef FAR void (*binfmt_ctor_t)(void);
+ typedef FAR void (*binfmt_dtor_t)(void);
+
+Function Interfaces
+-------------------
+
+Binary format management
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. c:function:: int register_binfmt(FAR struct binfmt_s *binfmt)
+
+ Register a loader for a binary format.
+
+ :return: This is a NuttX internal function so it follows the convention
+ that 0 (OK) is returned on success and a negated errno is returned on
+ failure.
+
+.. c:function:: int unregister_binfmt(FAR struct binfmt_s *binfmt)
+
+ Register a loader for a binary format.
+
+ :return:
+ This is a NuttX internal function so it follows the convention
+ that 0 (OK) is returned on success and a negated errno is returned on
+ failure.
+
+Basic module management
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. c:function:: int load_module(FAR struct binary_s *bin)
+
+ Load a module into memory, bind it to an exported symbol take,
+ and prep the module for execution.
+
+ :param bin:
+ The ``filename`` field will be used
+ in order to locate the module to be loaded from the file system.
+ The filename must be the full, absolute path to the file to be executed
+ unless ``CONFIG_LIB_ENVPATH`` is defined. In that case, filename may be
+ a relative path; a set of candidate absolute paths will be generated using
+ the ``PATH`` environment variable and ``load_module()`` will attempt to load each
+ file that is found at those absolute paths.
+
+ :return:
+ This is a NuttX internal function so it follows the convention that 0 (``OK``)
+ is returned on success and a negated ``errno`` is returned on failure.
+
+.. c:function:: int unload_module(FAR struct binary_s *bin)
+
+ Unload a (non-executing) module from memory. If the module has been started
+ (via :c:func:`exec_module`) and has not exited, calling this will be fatal.
+
+ However, this function must be called after the module exist. How this is
+ done is up to your logic. Perhaps you register it to be called by :c:func:`on_exit`?
+
+ :return:
+ This is a NuttX internal function so it follows the convention that 0 (``OK``)
+ is returned on success and a negated ``errno`` is returned on failure.
+
+.. c:function:: int exec_module(FAR const struct binary_s *bin);
+
+ Execute a module that has been loaded into memory by :c:func:`load_module`.
+
+ :return:
+ This is a NuttX internal function so it follows the convention that 0 (``OK``)
+ is returned on success and a negated ``errno`` is returned on failure.
+
+.. c:function:: int exec(FAR const char *filename, FAR const char **argv, FAR const struct symtab_s *exports, int nexports)
+
+ This is a convenience function that wraps :c:func:`load_module` and
+ :c:func:`exec_module` into one call.
+
+ :param filename: Full path to the binary to be loaded.
+ :param argv: Argument list.
+ :param exports: Table of exported symbols.
+ :param exports: The number of symbols in exports.
+
+ :return:
+ This is an end-user function, so it follows the normal convention:
+ Returns 0 (``OK``) on success. On failure, it returns -1 (ERROR)
+ with ``errno`` set appropriately.
+
+``PATH`` traversal logic
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. c:function:: ENVPATH_HANDLE envpath_init(void);
+
+ Initialize for the traversal of each value in the ``PATH`` variable. The
+ usage is sequence is as follows:
+
+ #. Call :c:func:`envpath_init` to initialize for the traversal.
+ ``envpath_init()`` will return an opaque handle that can then be
+ provided to :c:func:`envpath_next` and :c:func:`envpath_release`.
+ #. Call :c:func:`envpath_next` repeatedly to examine every file that lies in
+ the directories of the ``PATH`` variable.
+ #. Call :c:func:`envpath_release` to free resources set aside by
+ :c:func:`envpath_init`.
+
+ :return:
+ On success, :c:func:`envpath_init` return a non-``NULL``, opaque handle
+ that may subsequently be used in calls to :c:func:`envpath_next` and
+ :c:func:`envpath_release`. On error, a ``NULL`` handle value will be returned.
+ The most likely cause of an error would be that there is no value
+ associated with the ``PATH`` variable.
+
+.. c:function:: FAR char *envpath_next(ENVPATH_HANDLE handle, FAR const char *relpath)
+
+ Traverse all possible values in the PATH variable in attempt to find the
+ full path to an executable file when only a relative path is provided.
+
+ :param handle: The handle value returned by :c:func:`envpath_init`.
+ :param relpath: The relative path to the file to be found.
+
+ :return:
+ On success, a non-``NULL`` pointer to a null-terminated string is provided.
+ This is the full path to a file that exists in the file system.
+ This function will verify that the file exists (but will not verify that it is marked executable).
+
+ .. note::
+ The string pointer return in the success case points to allocated memory.
+ This memory must be freed by the called by calling :c:func:`kmm_free`.
+
+ ``NULL`` relpath from any absolute path in the ``PATH`` variable.
+ In this case, there is no point in calling :c:func:`envpath_next` further;
+ :c:func:`envpath_release` must be called to release resources set aside by
+ :c:func:`envpath_init`.
+
+.. c:function:: void envpath_release(ENVPATH_HANDLE handle)
+
+Release all resources set aside by envpath_init when the
+handle value was created. The handle value is invalid on
+return from this function. Attempts to all :c:func:`envpath_next`
+or :c:func:`envpath_release` with such a stale handle will result
+in undefined (i.e., not good) behavior.
+
+ :param handle: The handle value returned by :c:func:`envpath_init`.
+
+Symbol Tables
+=============
+
+**Symbol Tables**. Symbol tables are lists of name value mappings: The
+name is a string that identifies a symbol, and the value is an address
+in memory where the symbol of that name has been positioned. In most
+NuttX architectures symbol tables are required, as a minimum, in order
+to dynamically link the loaded binary object with the base code on
+FLASH. Since the binary object was separately built and separately
+linked, these symbols will appear as *undefined* symbols in the binary
+object. The binary loader will use the symbol table to look up the
+symbol by its name and to provide the address associated with the symbol
+as needed to perform the dynamic linking of the binary object to the
+base FLASH code.
+
+Symbol Table Header Files
+-------------------------
+
+The interface to the symbol table logic is described in the header file
+``include/nuttx/binfmt/symtab.h``.
+A brief summary of the data structurs and interfaces prototyped in that
+header file are listed below.
+
+Symbol Table Data Structures
+----------------------------
+
+.. c:struct:: symbtab_s
+
+ Describes one entry in the symbol table.
+
+ .. code-block:: c
+
+ struct symtab_s
+ {
+ FAR const char *sym_name; /* A pointer to the symbol name string */
+ FAR const void *sym_value; /* The value associated with the string */
+ };
+
+ A symbol table is a fixed size array of ``struct symtab_s``. The
+ information is intentionally minimal and supports only:
+
+ #. Function pointers as ``sym_values``. Of other kinds of values need to
+ be supported, then typing information would also need to be included
+ in the structure.
+ #. Fixed size arrays. There is no explicit provisional for dynamically
+ adding or removing entries from the symbol table (realloc might be
+ used for that purpose if needed). The intention is to support only
+ fixed size arrays completely defined at compilation or link time.
+
+Symbol Table Function Interfaces
+--------------------------------
+
+.. c:function:: FAR const struct symtab_s *symtab_findbyname(FAR const struct symtab_s *symtab, FAR const char *name, int nsyms);
+
+ Find the symbol in the symbol table with the matching name.
+ This version assumes that table is not ordered with respect to
+ symbol name and, hence, access time will be linear with respect
+ to ``nsyms``.
+
+ :return:
+ A reference to the symbol table entry if an entry with the matching name is found; NULL is returned if the entry is not found.
+
+.. c:function:: FAR const struct symtab_s *symtab_findorderedbyname(FAR const struct symtab_s *symtab, FAR const char *name, int nsyms);
+
+ Find the symbol in the symbol table with the matching name.
+ This version assumes that table ordered with respect to symbol name.
+
+ :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.
+
+
+.. c:function:: FAR const struct symtab_s *symtab_findbyvalue(FAR const struct symtab_s *symtab, FAR void *value, int nsyms);
+
+ Find the symbol in the symbol table whose value closest
+ (but not greater than), the provided value. This version assumes
+ that table is not ordered with respect to symbol name and, hence,
+ access time will be linear with respect to ``nsyms``.
+
+ :return:
+ A reference to the symbol table entry if an entry with the matching
+ name is found; ``NULL`` is returned if the entry is not found.
+
+Configuration Variables
+=======================
+
+ - ``CONFIG_BINFMT_DISABLE``: By default, support for loadable binary formats is built.
+ This logic may be suppressed be defining this setting.
+ - ``CONFIG_BINFMT_CONSTRUCTORS``: Build in support for C++ constructors in loaded modules.
+ - ``CONFIG_SYMTAB_ORDEREDBYNAME``: Symbol tables are order by name (rather than value).
+
+Additional configuration options may be required for the each enabled
+binary format.
diff --git a/doc/components/drivers/index.rst b/doc/components/drivers/index.rst
new file mode 100644
index 0000000..28af15d
--- /dev/null
+++ b/doc/components/drivers/index.rst
@@ -0,0 +1,941 @@
+==============
+Device Drivers
+==============
+
+NuttX supports a variety of device drivers including:
+
+ - *Character* Device Drivers,
+ - *Block* Device Drivers, and
+ - Other *Specialized* Drivers.
+
+These different device driver types are discussed in the following
+paragraphs. Note: device driver support depends on the
+*in-memory*, *pseudo* file system that is enabled by default.
+
+Character Device Drivers
+************************
+
+Character device drivers have these properties:
+
+- ``include/nuttx/fs/fs.h``. All structures and APIs needed
+ to work with character drivers are provided in this header
+ file.
+
+- ``struct file_operations``. Each character device driver
+ must implement an instance of ``struct file_operations``. That
+ structure defines a call table with the following methods:
+
+- ``int register_driver(const char *path, const struct file_operations *fops, mode_t mode, void *priv);``.
+ Each character driver registers itself by calling
+ ``register_driver()``, passing it the ``path`` where it will
+ appear in the `pseudo-file-system <#NxFileSystem>`__ and it's
+ initialized instance of ``struct file_operations``.
+
+- **User Access**. After it has been registered, the character
+ driver can be accessed by user code using the standard `driver
+ operations <NuttxUserGuide.html#driveroperations>`__ including
+ ``open()``, ``close()``, ``read()``, ``write()``, etc.
+
+- **Specialized Character Drivers**. Within the common character
+ driver framework, there are different specific varieties of
+ *specialized* character drivers. The unique requirements of the
+ underlying device hardware often mandates some customization of
+ the character driver. These customizations tend to take the
+ form of:
+
+ - Device-specific ``ioctl()`` commands used to performed
+ specialized operations on the device. These ``ioctl()`` will
+ be documented in header files under ``include/nuttx`` that
+ detail the specific device interface.
+ - Specialized I/O formats. Some devices will require that
+ ``read()`` and/or ``write()`` operations use data conforming
+ to a specific format, rather than a plain stream of bytes.
+ These specialized I/O formats will be documented in header
+ files under ``include/nuttx`` that detail the specific
+ device interface. The typical representation of the I/O
+ format will be a C structure definition.
+
+ The specialized character drivers support by NuttX are
+ documented in the following paragraphs.
+
+- **Examples**: ``drivers/dev_null.c``, ``drivers/fifo.c``,
+ ``drivers/serial.c``, etc.
+
+Serial Device Drivers
+=====================
+
+- ``include/nuttx/serial/serial.h``. All structures and APIs
+ needed to work with serial drivers are provided in this header
+ file.
+
+- ``struct uart_ops_s``. Each serial device driver must
+ implement an instance of ``struct uart_ops_s``. That structure
+ defines a call table with the following methods:
+
+- ``int uart_register(FAR const char *path, FAR uart_dev_t *dev);``.
+ A serial driver may register itself by calling
+ ``uart_register()``, passing it the ``path`` where it will
+ appear in the `pseudo-file-system <#NxFileSystem>`__ and it's
+ initialized instance of ``struct uart_ops_s``. By convention,
+ serial device drivers are registered at paths like
+ ``/dev/ttyS0``, ``/dev/ttyS1``, etc. See the
+ ``uart_register()`` implementation in ``drivers/serial.c``.
+
+- **User Access**. Serial drivers are, ultimately, normal
+ `character drivers <#chardrivers>`__ and are accessed as other
+ character drivers.
+
+- **Examples**: ``arch/arm/src/stm32/stm32_serial.c``,
+ ``arch/arm/src/lpc214x/lpc214x_serial.c``,
+ ``arch/z16/src/z16f/z16f_serial.c``, etc.
+
+Touchscreen Device Drivers
+==========================
+
+NuttX supports a two-part touchscreen driver architecture.
+
+#. An "upper half", generic driver that provides the common
+ touchscreen interface to application level code, and
+#. A "lower half", platform-specific driver that implements the
+ low-level touchscreen controls to implement the touchscreen
+ functionality.
+
+Files supporting the touchscreen controller (TSC) driver can be
+found in the following locations:
+
+- **Interface Definition**. The header files for NuttX
+ touchscreen drivers reside in the
+ ``include/nuttx/include/input`` directory. The interface
+ between the touchscreen controller "upper half" and "lower
+ half" drivers are *not* common, but vary from
+ controller-to-controller. Because of this, each touchscreen
+ driver has its own unique header file that describes the "upper
+ half"/"lower half" interface in that directory. The application
+ level interface to each touchscreen driver, on the other hand,
+ *is* the same for each touchscreen driver and is described
+ ``include/nuttx/include/input/touchscreen.h``. The touchscreen
+ driver uses a standard character driver framework but read
+ operations return specially formatted data.
+- **"Upper Half" Driver**. The controller-specific, "upper half"
+ touchscreen drivers reside in the directory ``drivers/input``.
+- **"Lower Half" Drivers**. Platform-specific touchscreen drivers
+ reside in either: (1) The
+ ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>* directory
+ for the processor architectures that have build in touchscreen
+ controllers or (2) the
+ ``boards/``\ *<arch>*\ ``/``\ *<chip>*\ ``/``\ *<board>*\ ``/src/``
+ directory for boards that use an external touchscreen
+ controller chip.
+
+Analog (ADC/DAC) Drivers
+========================
+
+The NuttX analog drivers are split into two parts:
+
+#. An "upper half", generic driver that provides the common analog
+ interface to application level code, and
+#. A "lower half", platform-specific driver that implements the
+ low-level controls to implement the analog functionality.
+
+- General header files for the NuttX analog drivers reside in
+ ``include/nuttx/analog/``. These header files includes both the
+ application level interface to the analog driver as well as the
+ interface between the "upper half" and "lower half" drivers.
+- Common analog logic and share-able analog drivers reside in the
+ ``drivers/analog/``.
+- Platform-specific drivers reside in
+ ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>* directory
+ for the specific processor *<architecture>* and for the
+ specific *<chip>* analog peripheral devices.
+
+ADC Drivers
+-----------
+
+- ``include/nuttx/analog/adc.h``. All structures and APIs needed
+ to work with ADC drivers are provided in this header file. This
+ header file includes:
+
+ #. Structures and interface descriptions needed to develop a
+ low-level, architecture-specific, ADC driver.
+ #. To register the ADC driver with a common ADC character
+ driver.
+ #. Interfaces needed for interfacing user programs with the
+ common ADC character driver.
+
+- ``drivers/analog/adc.c``. The implementation of the common ADC
+ character driver.
+
+DAC Drivers
+-----------
+
+- ``include/nuttx/analog/dac.h``. All structures and APIs needed
+ to work with DAC drivers are provided in this header file. This
+ header file includes:
+
+ #. Structures and interface descriptions needed to develop a
+ low-level, architecture-specific, DAC driver.
+ #. To register the DAC driver with a common DAC character
+ driver.
+ #. Interfaces needed for interfacing user programs with the
+ common DAC character driver.
+
+- ``drivers/analog/dac.c``. The implementation of the common DAC
+ character driver.
+
+PWM Drivers
+===========
+
+For the purposes of this driver, a PWM device is any device that
+generates periodic output pulses of controlled frequency and pulse
+width. Such a device might be used, for example, to perform
+pulse-width modulated output or frequency/pulse-count modulated
+output (such as might be needed to control a stepper motor).
+
+The NuttX PWM driver is split into two parts:
+
+#. An "upper half", generic driver that provides the common PWM
+ interface to application level code, and
+#. A "lower half", platform-specific driver that implements the
+ low-level timer controls to implement the PWM functionality.
+
+Files supporting PWM can be found in the following locations:
+
+- **Interface Definition**. The header file for the NuttX PWM
+ driver reside at ``include/nuttx/timers/pwm.h``. This header
+ file includes both the application level interface to the PWM
+ driver as well as the interface between the "upper half" and
+ "lower half" drivers. The PWM module uses a standard character
+ driver framework. However, since the PWM driver is a devices
+ control interface and not a data transfer interface, the
+ majority of the functionality available to the application is
+ implemented in driver ioctl calls.
+- **"Upper Half" Driver**. The generic, "upper half" PWM driver
+ resides at ``drivers/pwm.c``.
+- **"Lower Half" Drivers**. Platform-specific PWM drivers reside
+ in ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>*
+ directory for the specific processor *<architecture>* and for
+ the specific *<chip>* PWM peripheral devices.
+
+CAN Drivers
+===========
+
+NuttX supports only a very low-level CAN driver. This driver
+supports only the data exchange and does not include any
+high-level CAN protocol. The NuttX CAN driver is split into two
+parts:
+
+#. An "upper half", generic driver that provides the common CAN
+ interface to application level code, and
+#. A "lower half", platform-specific driver that implements the
+ low-level timer controls to implement the CAN functionality.
+
+Files supporting CAN can be found in the following locations:
+
+- **Interface Definition**. The header file for the NuttX CAN
+ driver resides at ``include/nuttx/can/can.h``. This header file
+ includes both the application level interface to the CAN driver
+ as well as the interface between the "upper half" and "lower
+ half" drivers. The CAN module uses a standard character driver
+ framework.
+- **"Upper Half" Driver**. The generic, "upper half" CAN driver
+ resides at ``drivers/can.c``.
+- **"Lower Half" Drivers**. Platform-specific CAN drivers reside
+ in ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>*
+ directory for the specific processor *<architecture>* and for
+ the specific *<chip>* CAN peripheral devices.
+
+**Usage Note**: When reading from the CAN driver multiple messages
+may be returned, depending on (1) the size the returned can
+messages, and (2) the size of the buffer provided to receive CAN
+messages. *Never assume that a single message will be returned*...
+if you do this, *you will lose CAN data* under conditions where
+your read buffer can hold more than one small message. Below is an
+example about how you should think of the CAN read operation:
+
+Quadrature Encoder Drivers
+==========================
+
+NuttX supports a low-level, two-part Quadrature Encoder driver.
+
+#. An "upper half", generic driver that provides the common
+ Quadrature Encoder interface to application level code, and
+#. A "lower half", platform-specific driver that implements the
+ low-level timer controls to implement the Quadrature Encoder
+ functionality.
+
+Files supporting the Quadrature Encoder can be found in the
+following locations:
+
+- **Interface Definition**. The header file for the NuttX
+ Quadrature Encoder driver reside at
+ ``include/nuttx/sensors/qencoder.h``. This header file includes
+ both the application level interface to the Quadrature Encoder
+ driver as well as the interface between the "upper half" and
+ "lower half" drivers. The Quadrature Encoder module uses a
+ standard character driver framework.
+- **"Upper Half" Driver**. The generic, "upper half" Quadrature
+ Encoder driver resides at ``drivers/sensors/qencoder.c``.
+- **"Lower Half" Drivers**. Platform-specific Quadrature Encoder
+ drivers reside in
+ ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>* directory
+ for the specific processor *<architecture>* and for the
+ specific *<chip>* Quadrature Encoder peripheral devices.
+
+Timer Drivers
+=============
+
+NuttX supports a low-level, two-part timer driver.
+
+#. An "upper half", generic driver that provides the common timer
+ interface to application level code, and
+#. A "lower half", platform-specific driver that implements the
+ low-level timer controls to implement the timer functionality.
+
+Files supporting the timer driver can be found in the following
+locations:
+
+- **Interface Definition**. The header file for the NuttX timer
+ driver reside at ``include/nuttx/timers/timer.h``. This header
+ file includes both the application level interface to the timer
+ driver as well as the interface between the "upper half" and
+ "lower half" drivers. The timer driver uses a standard
+ character driver framework.
+- **"Upper Half" Driver**. The generic, "upper half" timer driver
+ resides at ``drivers/timers/timer.c``.
+- **"Lower Half" Drivers**. Platform-specific timer drivers
+ reside in ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>*
+ directory for the specific processor *<architecture>* and for
+ the specific *<chip>* timer peripheral devices.
+
+RTC Drivers
+===========
+
+NuttX supports a low-level, two-part RealTime Clock (RTC) driver.
+
+#. An "upper half", generic driver that provides the common RTC
+ interface to application level code, and
+#. A "lower half", platform-specific driver that implements the
+ low-level timer controls to implement the RTC functionality.
+
+Files supporting the RTC driver can be found in the following
+locations:
+
+- **Interface Definition**. The header file for the NuttX RTC
+ driver reside at ``include/nuttx/timers/rtc.h``. This header
+ file includes both the application level interface to the RTC
+ driver as well as the interface between the "upper half" and
+ "lower half" drivers. The RTC driver uses a standard character
+ driver framework.
+- **"Upper Half" Driver**. The generic, "upper half" RTC driver
+ resides at ``drivers/timers/rtc.c``.
+- **"Lower Half" Drivers**. Platform-specific RTC drivers reside
+ in ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>*
+ directory for the specific processor *<architecture>* and for
+ the specific *<chip>* RTC peripheral devices.
+
+Watchdog Timer Drivers
+======================
+
+NuttX supports a low-level, two-part watchdog timer driver.
+
+#. An "upper half", generic driver that provides the common
+ watchdog timer interface to application level code, and
+#. A "lower half", platform-specific driver that implements the
+ low-level timer controls to implement the watchdog timer
+ functionality.
+
+Files supporting the watchdog timer driver can be found in the
+following locations:
+
+- **Interface Definition**. The header file for the NuttX
+ watchdog timer driver reside at
+ ``include/nuttx/timers/watchdog.h``. This header file includes
+ both the application level interface to the watchdog timer
+ driver as well as the interface between the "upper half" and
+ "lower half" drivers. The watchdog timer driver uses a standard
+ character driver framework.
+- **"Upper Half" Driver**. The generic, "upper half" watchdog
+ timer driver resides at ``drivers/timers/watchdog.c``.
+- **"Lower Half" Drivers**. Platform-specific watchdog timer
+ drivers reside in
+ ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>* directory
+ for the specific processor *<architecture>* and for the
+ specific *<chip>* watchdog timer peripheral devices.
+
+Keyboard/Keypad Drivers
+=======================
+
+**Keypads vs. Keyboards** Keyboards and keypads are really the
+same devices for NuttX. A keypad is thought of as simply a
+keyboard with fewer keys.
+
+**Special Commands**. In NuttX, a keyboard/keypad driver is simply
+a character driver that may have an (optional) encoding/decoding
+layer on the data returned by the character driver. A keyboard may
+return simple text data (alphabetic, numeric, and punctuation) or
+control characters (enter, control-C, etc.) when a key is pressed.
+We can think about this the "normal" keyboard data stream.
+However, in addition, most keyboards support actions that cannot
+be represented as text or control data. Such actions include
+things like cursor controls (home, up arrow, page down, etc.),
+editing functions (insert, delete, etc.), volume controls, (mute,
+volume up, etc.) and other special functions. In this case, some
+special encoding may be required to multiplex the normal text data
+and special command key press data streams.
+
+**Key Press and Release Events** Sometimes the time that a key is
+released is needed by applications as well. Thus, in addition to
+normal and special key press events, it may also be necessary to
+encode normal and special key release events.
+
+**Encoding/Decoding** Layer. An optional encoding/decoding layer
+can be used with the basic character driver to encode the keyboard
+events into the text data stream. The function interfaces that
+comprise that encoding/decoding layer are defined in the header
+file ``include/nuttx/input/kbd_code.h``. These functions provide
+an matched set of (a) driver encoding interfaces, and (b)
+application decoding interfaces.
+
+#. **Driver Encoding Interfaces**. These are interfaces used by
+ the keyboard/keypad driver to encode keyboard events and data.
+
+ - ``kbd_press()``
+
+ **Function Prototype:**
+
+ **Description:**
+
+ **Input Parameters:**
+
+ - ``ch``: The character to be added to the output stream.
+ - ``stream``: An instance of ``lib_outstream_s`` to perform
+ the actual low-level put operation.
+
+ **Returned Value:**
+
+ - ``kbd_release()``
+
+ **Function Prototype:**
+
+ **Description:**
+
+ **Input Parameters:**
+
+ - ``ch``: The character associated with the key that was
+ released.
+ - ``stream``: An instance of ``lib_outstream_s`` to perform
+ the actual low-level put operation.
+
+ **Returned Value:**
+
+ - ``kbd_specpress()``
+
+ **Function Prototype:**
+
+ **Description:**
+
+ **Input Parameters:**
+
+ - ``keycode``: The command to be added to the output
+ stream. The enumeration ``enum kbd_keycode_e keycode``
+ identifies all commands known to the system.
+ - ``stream``: An instance of ``lib_outstream_s`` to perform
+ the actual low-level put operation.
+
+ **Returned Value:**
+
+ - ``kbd_specrel()``
+
+ **Function Prototype:**
+
+ **Description:**
+
+ **Input Parameters:**
+
+ - ``keycode``: The command to be added to the output
+ stream. The enumeration ``enum kbd_keycode_e keycode``
+ identifies all commands known to the system.
+ - ``stream``: An instance of ``lib_outstream_s`` to perform
+ the actual low-level put operation.
+
+ **Returned Value:**
+
+#. **Application Decoding Interfaces**. These are user interfaces
+ to decode the values returned by the keyboard/keypad driver.
+
+ - ``kbd_decode()``
+
+ **Function Prototype:**
+
+ **Description:**
+
+ **Input Parameters:**
+
+ - ``stream``: An instance of ``lib_instream_s`` to perform
+ the actual low-level get operation.
+ - ``pch``: The location to save the returned value. This
+ may be either a normal, character code or a special
+ command (i.e., a value from ``enum kbd_getstate_s``.
+ - ``state``: A user provided buffer to support parsing.
+ This structure should be cleared the first time that
+ ``kbd_decode()`` is called.
+
+ **Returned Value:**
+
+ - ``KBD_PRESS`` (0)**: Indicates the successful receipt
+ of normal, keyboard data. This corresponds to a keypress
+ event. The returned value in ``pch`` is a simple byte of
+ text or control data.
+ - ``KBD_RELEASE`` (1)**: Indicates a key release event.
+ The returned value in ``pch`` is the byte of text or
+ control data corresponding to the released key.
+ - ``KBD_SPECPRESS`` (2)**: Indicates the successful
+ receipt of a special keyboard command. The returned value
+ in ``pch`` is a value from ``enum kbd_getstate_s``.
+ - ``KBD_SPECREL`` (3)**: Indicates a special command key
+ release event. The returned value in ``pch`` is a value
+ from ``enum kbd_getstate_s``.
+ - ``KBD_ERROR`` (``EOF``)**: An error has getting the
+ next character (reported by the ``stream``). Normally
+ indicates the end of file.
+
+**I/O Streams**. Notice the use of the abstract I/O streams in
+these interfaces. These stream interfaces are defined in
+``include/nuttx/streams.h``.
+
+Block Device Drivers
+********************
+
+Block device drivers have these properties:
+
+- ``include/nuttx/fs/fs.h``. All structures and APIs needed
+ to work with block drivers are provided in this header file.
+
+- ``struct block_operations``. Each block device driver must
+ implement an instance of ``struct block_operations``. That
+ structure defines a call table with the following methods:
+
+- ``int register_blockdriver(const char *path, const struct block_operations *bops, mode_t mode, void *priv);``.
+ Each block driver registers itself by calling
+ ``register_blockdriver()``, passing it the ``path`` where it
+ will appear in the `pseudo-file-system <#NxFileSystem>`__ and
+ it's initialized instance of ``struct block_operations``.
+
+- **User Access**. Users do not normally access block drivers
+ directly, rather, they access block drivers indirectly through
+ the ``mount()`` API. The ``mount()`` API binds a block driver
+ instance with a file system and with a mountpoint. Then the
+ user may use the block driver to access the file system on the
+ underlying media. *Example*: See the ``cmd_mount()``
+ implementation in ``apps/nshlib/nsh_fscmds.c``.
+
+- **Accessing a Character Driver as a Block Device**. See the
+ loop device at ``drivers/loop.c``. *Example*: See the
+ ``cmd_losetup()`` implementation in
+ ``apps/nshlib/nsh_fscmds.c``.
+
+- **Accessing a Block Driver as Character Device**. See the
+ Block-to-Character (BCH) conversion logic in ``drivers/bch/``.
+ *Example*: See the ``cmd_dd()`` implementation in
+ ``apps/nshlib/nsh_ddcmd.c``.
+
+- **Examples**. ``drivers/loop.c``,
+ ``drivers/mmcsd/mmcsd_spi.c``, ``drivers/ramdisk.c``, etc.
+
+Specialized Device Drivers
+**************************
+
+All device drivers that are accessible to application logic are
+either: (1) Character device drivers that can be accessed via the
+standard driver operations (``open()``, ``close()``, ``read()``,
+``write()``, etc.), or (2) block drivers that can be accessing
+only as part of mounting a file system or other special use cases
+as described in the preceding paragraph.
+
+In addition to this, there are also specialized "drivers" that can
+be used only within the OS logic itself and are not accessible to
+application logic. These specialized drivers are discussed in the
+following paragraphs.
+
+Ethernet Device Drivers
+=======================
+
+- ``include/nuttx/net/netdev.h``. All structures and APIs
+ needed to work with Ethernet drivers are provided in this
+ header file. The structure ``struct net_driver_s`` defines the
+ interface and is passed to the network via
+ ``netdev_register()``.
+
+- ``int netdev_register(FAR struct net_driver_s *dev, enum net_lltype_e lltype);``.
+ Each Ethernet driver registers itself by calling
+ ``netdev_register()``.
+
+- **Examples**: ``drivers/net/dm90x0.c``,
+ ``arch/drivers/arm/src/c5471/c5471_ethernet.c``,
+ ``arch/z80/src/ez80/ez80_emac.c``, etc.
+
+SPI Device Drivers
+==================
+
+- ``include/nuttx/spi/spi.h``. All structures and APIs needed
+ to work with SPI drivers are provided in this header file.
+
+- ``struct spi_ops_s``. Each SPI device driver must implement
+ an instance of ``struct spi_ops_s``. That structure defines a
+ call table with the following methods:
+
+- **Binding SPI Drivers**. SPI drivers are not normally directly
+ accessed by user code, but are usually bound to another, higher
+ level device driver. See for example,
+ ``int mmcsd_spislotinitialize(int minor, int slotno, FAR struct spi_dev_s *spi)``
+ in ``drivers/mmcsd/mmcsd_spi.c``. In general, the binding
+ sequence is:
+
+ #. Get an instance of ``struct spi_dev_s`` from the
+ hardware-specific SPI device driver, and
+ #. Provide that instance to the initialization method of the
+ higher level device driver.
+
+- **Examples**: ``drivers/loop.c``,
+ ``drivers/mmcsd/mmcsd_spi.c``, ``drivers/ramdisk.c``, etc.
+
+I2C Device Drivers
+==================
+
+- ``include/nuttx/i2c/i2c.h``. All structures and APIs needed
+ to work with I2C drivers are provided in this header file.
+
+- ``struct i2c_ops_s``. Each I2C device driver must implement
+ an instance of ``struct i2c_ops_s``. That structure defines a
+ call table with the following methods:
+
+- **Binding I2C Drivers**. I2C drivers are not normally directly
+ accessed by user code, but are usually bound to another, higher
+ level device driver. In general, the binding sequence is:
+
+ #. Get an instance of ``struct i2c_master_s`` from the
+ hardware-specific I2C device driver, and
+ #. Provide that instance to the initialization method of the
+ higher level device driver.
+
+- **Examples**: ``arch/z80/src/ez80/ez80_i2c.c``,
+ ``arch/z80/src/z8/z8_i2c.c``, etc.
+
+Frame Buffer Drivers
+====================
+
+- ``include/nuttx/video/fb.h``. All structures and APIs
+ needed to work with frame buffer drivers are provided in this
+ header file.
+
+- ``struct fb_vtable_s``. Each frame buffer device driver
+ must implement an instance of ``struct fb_vtable_s``. That
+ structure defines a call table with the following methods:
+
+ Get information about the video controller configuration and
+ the configuration of each color plane.
+
+ The following are provided only if the video hardware supports
+ RGB color mapping:
+
+ The following are provided only if the video hardware supports
+ a hardware cursor:
+
+- **Binding Frame Buffer Drivers**. Frame buffer drivers are not
+ normally directly accessed by user code, but are usually bound
+ to another, higher level device driver. In general, the binding
+ sequence is:
+
+ #. Get an instance of ``struct fb_vtable_s`` from the
+ hardware-specific frame buffer device driver, and
+ #. Provide that instance to the initialization method of the
+ higher level device driver.
+
+- **Examples**: ``arch/sim/src/up_framebuffer.c``. See also the
+ usage of the frame buffer driver in the ``graphics/``
+ directory.
+
+LCD Drivers
+===========
+
+- ``include/nuttx/lcd/lcd.h``. Structures and APIs needed to
+ work with LCD drivers are provided in this header file. This
+ header file also depends on some of the same definitions used
+ for the frame buffer driver as provided in
+ ``include/nuttx/video/fb.h``.
+
+- ``struct lcd_dev_s``. Each LCD device driver must implement
+ an instance of ``struct lcd_dev_s``. That structure defines a
+ call table with the following methods:
+
+ Get information about the LCD video controller configuration
+ and the configuration of each LCD color plane.
+
+ The following are provided only if the video hardware supports
+ RGB color mapping:
+
+ The following are provided only if the video hardware supports
+ a hardware cursor:
+
+ Get the LCD panel power status (0: full off -
+ ``CONFIG_LCD_MAXPOWER``: full on). On backlit LCDs, this
+ setting may correspond to the backlight setting.
+
+ Enable/disable LCD panel power (0: full off -
+ ``CONFIG_LCD_MAXPOWER``: full on). On backlit LCDs, this
+ setting may correspond to the backlight setting.
+
+ Get the current contrast setting (0-CONFIG_LCD_MAXCONTRAST) \*/
+
+ Set LCD panel contrast (0-CONFIG_LCD_MAXCONTRAST)
+
+- **Binding LCD Drivers**. LCD drivers are not normally directly
+ accessed by user code, but are usually bound to another, higher
+ level device driver. In general, the binding sequence is:
+
+ #. Get an instance of ``struct lcd_dev_s`` from the
+ hardware-specific LCD device driver, and
+ #. Provide that instance to the initialization method of the
+ higher level device driver.
+
+- **Examples**: ``drivers/lcd/p14201.c``,
+ ``boards/arm/sam34/sam3u-ek/src/up_lcd.c.`` See also the usage
+ of the LCD driver in the ``graphics/`` directory.
+
+Memory Technology Device Drivers
+================================
+
+- ``include/nuttx/mtd/mtd.h``. All structures and APIs needed
+ to work with MTD drivers are provided in this header file.
+
+- ``struct mtd_dev_s``. Each MTD device driver must implement
+ an instance of ``struct mtd_dev_s``. That structure defines a
+ call table with the following methods:
+
+ Erase the specified erase blocks (units are erase blocks):
+
+ Read/write from the specified read/write blocks:
+
+ Some devices may support byte oriented reads (optional). Most
+ MTD devices are inherently block oriented so byte-oriented
+ accesses are not supported. It is recommended that low-level
+ drivers not support read() if it requires buffering.
+
+ Some devices may also support byte oriented writes (optional).
+ Most MTD devices are inherently block oriented so byte-oriented
+ accesses are not supported. It is recommended that low-level
+ drivers not support read() if it requires buffering. This
+ interface is only available if ``CONFIG_MTD_BYTE_WRITE`` is
+ defined.
+
+ Support other, less frequently used commands:
+
+ - ``MTDIOC_GEOMETRY``: Get MTD geometry
+ - ``MTDIOC_XIPBASE:``: Convert block to physical address for
+ eXecute-In-Place
+ - ``MTDIOC_BULKERASE``: Erase the entire device
+
+ is provided via a single ``ioctl`` method (see
+ ``include/nuttx/fs/ioctl.h``):
+
+- **Binding MTD Drivers**. MTD drivers are not normally directly
+ accessed by user code, but are usually bound to another, higher
+ level device driver. In general, the binding sequence is:
+
+ #. Get an instance of ``struct mtd_dev_s`` from the
+ hardware-specific MTD device driver, and
+ #. Provide that instance to the initialization method of the
+ higher level device driver.
+
+- **Examples**: ``drivers/mtd/m25px.c`` and ``drivers/mtd/ftl.c``
+
+SDIO Device Drivers
+===================
+
+- ``include/nuttx/sdio.h``. All structures and APIs needed to
+ work with SDIO drivers are provided in this header file.
+
+- ``struct sdio_dev_s``. Each SDIO device driver must
+ implement an instance of ``struct sdio_dev_s``. That structure
+ defines a call table with the following methods:
+
+ Mutual exclusion:
+
+ Initialization/setup:
+
+ Command/Status/Data Transfer:
+
+ Event/Callback support:
+
+ DMA support:
+
+- **Binding SDIO Drivers**. SDIO drivers are not normally
+ directly accessed by user code, but are usually bound to
+ another, higher level device driver. In general, the binding
+ sequence is:
+
+ #. Get an instance of ``struct sdio_dev_s`` from the
+ hardware-specific SDIO device driver, and
+ #. Provide that instance to the initialization method of the
+ higher level device driver.
+
+- **Examples**: ``arch/arm/src/stm32/stm32_sdio.c`` and
+ ``drivers/mmcsd/mmcsd_sdio.c``
+
+USB Host-Side Drivers
+=====================
+
+- ``include/nuttx/usb/usbhost.h``. All structures and APIs
+ needed to work with USB host-side drivers are provided in this
+ header file.
+
+- ``struct usbhost_driver_s`` and
+ ``struct usbhost_connection_s``. Each USB host controller
+ driver must implement an instance of
+ ``struct usbhost_driver_s`` and
+ ``struct usbhost_connection_s``: ``struct usbhost_driver_s``
+ provides the interface between the USB host driver and the USB
+ class driver; ``struct usbhost_connection_s`` provides the
+ interface between the USB host driver and platform-specific
+ connection management and device enumeration logic. These
+ structures are defined in ``include/nuttx/usb/usbhost.h``.
+
+ **Examples**: ``arch/arm/src/lpc17xx_40xx/lpc17_40_usbhost.c``,
+ ``arch/arm/src/stm32/stm32_otgfshost.c``,
+ ``arch/arm/src/sama5/sam_ohci.c``, and
+ ``arch/arm/src/sama5/sam_ehci.c``.
+
+- ``struct usbhost_class_s``. Each USB host class driver must
+ implement an instance of ``struct usbhost_class_s``. This
+ structure is also defined in ``include/nuttx/usb/usbhost.h``.
+
+ **Examples**: ``drivers/usbhost/usbhost_storage.c``
+
+- **USB Host Class Driver Registry**. The NuttX USB host
+ infrastructure includes a *registry*. During its
+ initialization, each USB host class driver must call the
+ interface, ``usbhost_registerclass()`` in order add its
+ interface to the registry. Later, when a USB device is
+ connected, the USB host controller will look up the USB host
+ class driver that is needed to support the connected device in
+ this registry.
+
+ **Examples**: ``drivers/usbhost/usbhost_registry.c``,
+ ``drivers/usbhost/usbhost_registerclass.c``, and
+ ``drivers/usbhost/usbhost_findclass.c``,
+
+- **Detection and Enumeration of Connected Devices**. Each USB
+ host device controller supports two methods that are used to
+ detect and enumeration newly connected devices (and also detect
+ disconnected devices):
+
+ - ``int (*wait)(FAR struct usbhost_connection_s *drvr, FAR const bool *connected);``
+
+ Wait for a device to be connected or disconnected.
+
+ - ``int (*enumerate)(FAR struct usbhost_connection_s *drvr, int rhpndx);``
+
+ Enumerate the device connected to a root hub port. As part
+ of this enumeration process, the driver will (1) get the
+ device's configuration descriptor, (2) extract the class ID
+ info from the configuration descriptor, (3) call
+ ``usbhost_findclass(``) to find the class that supports this
+ device, (4) call the ``create()`` method on the
+ ``struct usbhost_registry_s interface`` to get a class
+ instance, and finally (5) call the ``connect()`` method of
+ the ``struct usbhost_class_s`` interface. After that, the
+ class is in charge of the sequence of operations.
+
+- **Binding USB Host-Side Drivers**. USB host-side controller
+ drivers are not normally directly accessed by user code, but
+ are usually bound to another, higher level USB host class
+ driver. The class driver exports the standard NuttX device
+ interface so that the connected USB device can be accessed just
+ as with other, similar, on-board devices. For example, the USB
+ host mass storage class driver
+ (``drivers/usbhost/usbhost_storage.c``) will register a
+ standard, NuttX block driver interface (like ``/dev/sda``) that
+ can be used to mount a file system just as with any other other
+ block driver instance. In general, the binding sequence is:
+
+ #. Each USB host class driver includes an initialization entry
+ point that is called from the application at initialization
+ time. This driver calls ``usbhost_registerclass()`` during
+ this initialization in order to makes itself available in
+ the event the device that it supports is connected.
+
+ **Examples**: The function ``usbhost_msc_initialize()`` in
+ the file ``drivers/usbhost/usbhost_storage.c``
+
+ #. Each application must include a *waiter* thread thread that
+ (1) calls the USB host controller driver's ``wait()`` to
+ detect the connection of a device, and then (2) call the USB
+ host controller driver's ``enumerate`` method to bind the
+ registered USB host class driver to the USB host controller
+ driver.
+
+ **Examples**: The function ``nsh_waiter()`` in the file
+ ``boards/arm/lpc17xx_40xx/olimex-lpc1766stk/src/lpc17_40_appinit.c``.
+
+ #. As part of its operation during the binding operation, the
+ USB host class driver will register an instances of a
+ standard NuttX driver under the ``/dev`` directory. To
+ repeat the above example, the USB host mass storage class
+ driver (``drivers/usbhost/usbhost_storage.c``) will register
+ a standard, NuttX block driver interface (like ``/dev/sda``)
+ that can be used to mount a file system just as with any
+ other other block driver instance.
+
+ **Examples**: See the call to ``register_blockdriver()`` in
+ the function ``usbhost_initvolume()`` in the file
+ ``drivers/usbhost/usbhost_storage.c``.
+
+USB Device-Side Drivers
+=======================
+
+- ``include/nuttx/usb/usbdev.h``. All structures and APIs
+ needed to work with USB device-side drivers are provided in
+ this header file.
+
+- ``include/nuttx/usb/usbdev_trace.h``. Declarations needed
+ to work with the NuttX USB device driver trace capability. That
+ USB trace capability is detailed in `separate
+ document <UsbTrace.html>`__.
+
+- ``struct usbdev_s``. Each USB device controller driver must
+ implement an instance of ``struct usbdev_s``. This structure is
+ defined in ``include/nuttx/usb/usbdev.h``.
+
+ **Examples**: ``arch/arm/src/dm320/dm320_usbdev.c``,
+ ``arch/arm/src/lpc17xx_40xx/lpc17_40_usbdev.c``,
+ ``arch/arm/src/lpc214x/lpc214x_usbdev.c``,
+ ``arch/arm/src/lpc313x/lpc313x_usbdev.c``, and
+ ``arch/arm/src/stm32/stm32_usbdev.c``.
+
+- ``struct usbdevclass_driver_s``. Each USB device class
+ driver must implement an instance of
+ ``struct usbdevclass_driver_s``. This structure is also defined
+ in ``include/nuttx/usb/usbdev.h``.
+
+ **Examples**: ``drivers/usbdev/pl2303.c`` and
+ ``drivers/usbdev/usbmsc.c``
+
+- **Binding USB Device-Side Drivers**. USB device-side controller
+ drivers are not normally directly accessed by user code, but
+ are usually bound to another, higher level USB device class
+ driver. The class driver is then configured to export the USB
+ device functionality. In general, the binding sequence is:
+
+ #. Each USB device class driver includes an initialization
+ entry point that is called from the application at
+ initialization time.
+
+ **Examples**: The function ``usbdev_serialinitialize()`` in
+ the file ``drivers/usbdev/pl2303.c`` and the function
+ in the file ``drivers/usbdev/usbmsc.c``
+
+ #. These initialization functions called the driver API,
+ ``usbdev_register()``. This driver function will *bind* the
+ USB class driver to the USB device controller driver,
+ completing the initialization.
+
diff --git a/doc/components/filesystem.rst b/doc/components/filesystem.rst
new file mode 100644
index 0000000..5794dc3
--- /dev/null
+++ b/doc/components/filesystem.rst
@@ -0,0 +1,43 @@
+=================
+NuttX File System
+=================
+
+**Overview**. NuttX includes an optional, scalable file system.
+This file-system may be omitted altogether; NuttX does not depend
+on the presence of any file system.
+
+**Pseudo Root File System**. A simple *in-memory*, *pseudo* file
+system can be enabled by default. This is an *in-memory* file
+system because it does not require any storage medium or block
+driver support. Rather, file system contents are generated
+on-the-fly as referenced via standard file system operations
+(open, close, read, write, etc.). In this sense, the file system
+is *pseudo* file system (in the same sense that the Linux
+``/proc`` file system is also referred to as a pseudo file
+system).
+
+Any user supplied data or logic can be accessed via the
+pseudo-file system. Built in support is provided for character and
+block `drivers <#DeviceDrivers>`__ in the ``/dev`` pseudo file
+system directory.
+
+**Mounted File Systems** The simple in-memory file system can be
+extended my mounting block devices that provide access to true
+file systems backed up via some mass storage device. NuttX
+supports the standard ``mount()`` command that allows a block
+driver to be bound to a mountpoint within the pseudo file system
+and to a file system. At present, NuttX supports the standard VFAT
+and ROMFS file systems, a special, wear-leveling NuttX FLASH File
+System (NXFFS), as well as a Network File System client (NFS
+version 3, UDP).
+
+**Comparison to Linux** From a programming perspective, the NuttX
+file system appears very similar to a Linux file system. However,
+there is a fundamental difference: The NuttX root file system is a
+pseudo file system and true file systems may be mounted in the
+pseudo file system. In the typical Linux installation by
+comparison, the Linux root file system is a true file system and
+pseudo file systems may be mounted in the true, root file system.
+The approach selected by NuttX is intended to support greater
+scalability from the very tiny platform to the moderate platform.
+
diff --git a/doc/components/index.rst b/doc/components/index.rst
new file mode 100644
index 0000000..aa34634
--- /dev/null
+++ b/doc/components/index.rst
@@ -0,0 +1,20 @@
+OS Components
+=============
+
+.. note::
+ TODO: add brief intro
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Contents:
+
+ nsh/index.rst
+ power.rst
+ syslog.rst
+ binfmt.rst
+ drivers/index.rst
+ filesystem.rst
+ nxflat.rst
+ nxgraphics/index.rst
+ nxwidgets.rst
+ paging.rst
diff --git a/doc/components/nsh/builtin.rst b/doc/components/nsh/builtin.rst
new file mode 100644
index 0000000..338a539
--- /dev/null
+++ b/doc/components/nsh/builtin.rst
@@ -0,0 +1,204 @@
+***************************
+NSH "Built-In" Applications
+***************************
+
+**Overview.** In addition to these commands that are a part of NSH,
+external programs can also be executed as NSH commands. These external
+programs are called "Built-In" Applications for historic reasons. That
+terminology is somewhat confusing because the actual NSH commands as
+described above are truly "built-into" NSH whereas these applications
+are really external to NuttX.
+
+These applications are built-into NSH in the sense that they can be
+executed by simply typing the name of the application at the NSH prompt.
+Built-in application support is enabled with these configuration option:
+
+ - ``CONFIG_BUILTIN``: Enable NuttX support for builtin applications.
+ - ``CONFIG_NSH_BUILTIN_APPS``: Enable NSH support for builtin
+ applications.
+
+When these configuration options are set, you will also be able to see
+the built-in applications if you enter "nsh> help". They will appear at
+the bottom of the list of NSH commands under::
+
+ Builtin Apps:
+
+Note that no detailed help information beyond the name of the built-in
+application is provided.
+
+Built-In Applications
+~~~~~~~~~~~~~~~~~~~~~
+
+**Overview.** The underlying logic that supports the NSH built-in
+applications is called "Built-In Applications". The builtin application
+logic can be found at ``apps/builtin``. This logic simply does the
+following:
+
+ #. It supports registration mechanism so that builtin applications can
+ dynamically register themselves at build time, and
+
+ #. Utility functions to look up, list, and execute the builtin
+ applications.
+
+**Built-In Application Utility Functions**. The utility functions
+exported by the builtin application logic are prototyped in
+``nuttx/include/nuttx/lib/builtin.h`` and ``apps/include/builtin.h``.
+These utility functions include:
+
+ - ``int builtin_isavail(FAR const char *appname);`` Checks for
+ availability of application registered as ``appname`` during build
+ time.
+
+ - ``const char *builtin_getname(int index);`` Returns a pointer to a
+ name of built-in application pointed by the ``index``. This is the
+ utility function that is used by NSH in order to list the available
+ built-in applications when "``nsh> help``" is entered.
+
+ - ``int exec_builtin(FAR const char *appname, FAR const char **argv);``
+ Executes built-in builtin application registered during compile time.
+ This is the utility function used by NSH to execute the built-in
+ application.
+
+**Autogenerated Header Files**. Application entry points with their
+requirements are gathered together in two files when NuttX is first
+built:
+
+ #. ``apps/builtin/builtin_proto.h``: Prototypes of application task
+ entry points.
+
+ #. ``apps/builtin/builtin_list.h``: Application specific information and
+ start-up requirements
+
+**Registration of Built-In Applications**. The NuttX build occurs in
+several phases as different build targets are executed: (1) *context*
+when the configuration is established, (2) *depend* when target
+dependencies are generated, and (3) *default* (``all``) when the normal
+compilation and link operations are performed. Built-in application
+information is collected during the make *context* build phase.
+
+An example application that can be "built-in" is be found in the
+``apps/examples/hello directory``. Let's walk through this specific
+cause to illustrate the general way that built-in applications are
+created and how they register themselves so that they can be used from
+NSH.
+
+``apps/examples/hello``. The main routine for apps/examples/hello can be
+found in ``apps/examples/hello/main.c``. The main routine is:
+
+.. code-block:: c
+
+ int hello_main(int argc, char *argv[])
+ {
+ printf("Hello, World!!\n");
+ return 0;
+ }
+
+This is the built in function that will be registered during the
+*context* build phase of the NuttX build. That registration is performed
+by logic in ``apps/examples/hello/Makefile``. But the build system gets
+to that logic through a rather tortuous path:
+
+ #. The top-level context make target is in ``nuttx/Makefile``. All build
+ targets depend upon the *context* build target. For the ``apps/``
+ directory, this build target will execute the *context* target in the
+ ``apps/Makefile``.
+
+ #. The ``apps/Makefile`` will, in turn, execute the *context* targets in
+ all of the configured sub-directories. In our case will include the
+ ``Makefile`` in ``apps/examples``.
+
+ #. And finally, the ``apps/examples/Makefile`` will execute the
+ *context* target in all configured ``example``\ sub-directories,
+ getting us finally to ``apps/examples/Makefile`` which is covered
+ below.
+
+**NOTE**: Since this context build phase can only be executed one time,
+any subsequent configuration changes that you make will, then, not be
+reflected in the build sequence. That is a common area of confusion.
+Before you can instantiate the new configuration, you have to first get
+rid of the old configuration. The most drastic way to this is::
+
+ make distclean
+
+But then you will have to re-configuration NuttX from scratch. But if
+you only want to re-build the configuration in the ``apps/``
+sub-directory, then there is a less labor-intensive way to do that. The
+following NuttX make command will remove the configuration only from the
+``apps/`` directory and will let you continue without re-configuring
+everything::
+
+ make apps_distclean
+
+Logic for the ``context`` target in ``apps/examples/hello/Makefile``
+registers the ``hello_main()`` application in the ``builtin``'s
+``builtin_proto.h``\ and ``builtin_list.h`` files. That logic that does
+that in ``apps/examples/hello/Makefile`` is abstracted below:
+
+ #. First, the ``Makefile`` includes ``apps/Make.defs``::
+
+ include $(APPDIR)/Make.defs
+
+ This defines a macro called ``REGISTER`` that adds data to the
+ *builtin* header files::
+
+ define REGISTER
+ @echo "Register: $1"
+ @echo "{ \"$1\", $2, $3, $4 }," >> "$(APPDIR)/builtin/builtin_list.h"
+ @echo "EXTERN int $4(int argc, char *argv[]);" >> "$(APPDIR)/builtin/builtin_proto.h"
+ endef
+
+ When this macro runs, you will see the output in the build
+ "``Register: hello``", that is a sure sign that the registration was
+ successful.
+
+ #. The make file then defines the application name (``hello``), the task
+ priority (default), and the stack size that will be allocated in the
+ task runs (2K)::
+
+ APPNAME = hello
+ PRIORITY = SCHED_PRIORITY_DEFAULT
+ STACKSIZE = 2048
+
+ #. And finally, the ``Makefile`` invokes the ``REGISTER`` macro to added
+ the ``hello_main()`` builtin application. Then, when the system build
+ completes, the ``hello`` command can be executed from the NSH command
+ line. When the ``hello`` command is executed, it will start the task
+ with entry point ``hello_main()`` with the default priority and with
+ a stack size of 2K::
+
+ context:
+ $(call REGISTER,$(APPNAME),$(PRIORITY),$(STACKSIZE),$(APPNAME)_main)
+
+
+**Other Uses of Built-In Application.** The primary purpose of builtin
+applications is to support command line execution of applications from
+NSH. However, there is one other use of builtin applications that should
+be mentioned.
+
+ #. **binfs**. *binfs* is a tiny file system located at
+ ``apps/builtin/binfs.c``. This provides an alternative what of
+ visualizing installed builtin applications. Without *binfs*, you can
+ see the installed builtin applications using the NSH help command.
+ *binfs* will create a tiny pseudo-file system mounted at ``/bin``.
+ Using *binfs*, you can see the available builtin applications by
+ listing the contents of ``/bin`` directory. This gives some
+ superficial Unix-like compatibility, but does not really add any new
+ functionality.
+
+Synchronous Built-In Applications
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, built-in commands started from the NSH command line will run
+asynchronously with NSH. If you want to force NSH to execute commands
+then wait for the command to execute, you can enable that feature by
+adding the following to the NuttX configuration file::
+
+ CONFIG_SCHED_WAITPID=y
+
+This configuration option enables support for the standard ``waitpid()``
+RTOS interface. When that interface is enabled, NSH will use it to wait,
+sleeping until the built-in application executes to completion.
+
+Of course, even with ``CONFIG_SCHED_WAITPID=y`` defined, specific
+applications can still be forced to run asynchronously by adding the
+ampersand (&) after the NSH command.
diff --git a/doc/components/nsh/commands.rst b/doc/components/nsh/commands.rst
new file mode 100644
index 0000000..3e125ee
--- /dev/null
+++ b/doc/components/nsh/commands.rst
@@ -0,0 +1,1692 @@
+********
+Commands
+********
+
+Evaluate Expression (test)
+--------------------------
+
+**Command Syntax:**
+
+.. code-block:: fish
+
+ [ <expression> ]
+ test <expression>
+
+**Synopsis**. These are two alternative forms of the same command.
+They support evaluation of a boolean expression which sets
+``$?``. This command is used most frequently as
+the conditional command following the ``if`` in the
+``if-then[-else]-fi``.
+
+**Expression Syntax:**
+
+::
+
+ expression = simple-expression | !expression | expression -o expression | expression -a expression
+
+ simple-expression = unary-expression | binary-expression
+
+ unary-expression = string-unary | file-unary
+
+ string-unary = -n string | -z string
+
+ file-unary = -b file | -c file | -d file | -e file | -f file | -r file | -s file | -w file
+
+ binary-expression = string-binary | numeric-binary
+
+ string-binary = string = string | string == string | string != string
+
+ numeric-binary = integer -eq integer | integer -ge integer | integer -gt integer | integer -le integer | integer -lt integer | integer -ne integer
+
+Add a Routing Table Entry (addroute)
+------------------------------------
+
+**Command Syntax:**
+
+::
+
+ addroute <target> [<netmask>] <router>
+ addroute default <ipaddr> <interface>
+
+**Synopsis**. This command adds an entry in the routing table. The
+new entry will map the IP address of a router on a local network
+(<router>) to an external network characterized by the <target> IP
+address and a network mask <netmask>
+
+The netmask may also be expressed using IPv4 CIDR or IPv6 slash
+notation. In that case, the netmask need not be provided.
+
+**Example:**
+
+::
+
+ nsh> addroute addroute 11.0.0.0 255.255.255.0 10.0.0.2
+
+which is equivalent to
+
+::
+
+ nsh> addroute 11.0.0.0/24 10.0.0.2
+
+The second form of the addroute command can be used to set the
+default gateway.
+
+Access the ARP table (arp)
+**************************
+
+**Command syntax**::
+
+ arp [-t|-a <ipaddr> |-d <ipaddr> |-s <ipaddr> <hwaddr>]
+
+**Synopsis**: Access the OS ARP table.
+
+ -a <ipaddr> Will show the hardware address that the IP address <ipaddr> is
+ mapped to.
+ -d <ipaddr> Will delete the mapping for the IP address <ipaddr> from the
+ ARP table.
+ -s <ipaddr hwaddr> Will set (or replace) the mapping of the IP address <ipaddr> to
+ the hardware address <hwaddr>.
+ -t Will dump the entire content of the ARP table. This option is
+ only available if ``CONFIG_NETLINK_ROUTE`` is enabled.
+
+**Example**::
+
+ nsh> arp -a 10.0.0.1
+ nsh: arp: no such ARP entry: 10.0.0.1
+
+ nsh> arp -s 10.0.0.1 00:13:3b:12:73:e6
+ nsh> arp -a 10.0.0.1
+ HWAddr: 00:13:3b:12:73:e6
+
+ nsh> arp -d 10.0.0.1
+ nsh> arp -a 10.0.0.1
+ nsh: arp: no such ARP entry: 10.0.0.1
+
+Base64 Decode (base64dec)
+*************************
+
+**Command Syntax**::
+
+ base64dec [-w] [-f] <string or filepath>
+
+**Synopsis**. *To be provided.*
+
+Base64 Encode (base64enc)
+*************************
+
+**Command Syntax**::
+
+ base64enc [-w] [-f] <string or filepath>
+
+**Synopsis**. *To be provided.*
+
+Extract Base File/Directory Name (basename)
+*******************************************
+
+**Command Syntax**::
+
+ basename <path> [<suffix>]
+
+**Synopsis**. Extract the final string from a ``<path>`` by
+removing the preceding path segments and (optionally) removing any
+trailing ``<suffix>``.
+
+Terminate a Loop (break)
+************************
+
+**Command Syntax**::
+
+ break
+
+**Synopsis**. The ``break`` command is only meaningful within the
+body of the a `while <#looping>`__ or `until <#looping>`__ loop,
+between the ``do`` and ``done`` tokens. Outside of a loop,
+``break`` command does nothing. If the ``break`` command is
+executed within the body of a loop, the loop will immediately
+terminate and execution will continue with the next command
+immediately following the ``done`` token.
+
+Concatenate Files (cat)
+***********************
+
+**Command Syntax**::
+
+ cat <path> [<path> [<path> ...]]
+
+**Synopsis**. This command copies and concatenates all of the
+files at ``<path>`` to the console (or to another file if the
+output is redirected).
+
+Change Current Working Directory (cd)
+*************************************
+
+**Command Syntax**::
+
+ cd [<dir-path>|-|~|..]
+
+**Synopsis**. Changes the current working directory (``PWD``).
+Also sets the previous working directory environment variable
+(``OLDPWD``).
+
+**Forms:**
+
+================== =====================================
+``cd <dir-path>`` sets the current working directory to <dir-path>.
+``cd -`` sets the current working directory to the previous
+ working directory ($OLDPWD). Equivalent to cd $OLDPWD.
+``cd`` or ``cd ~`` set the current working directory to the 'home' directory.
+ The home directory can be configured by setting CONFIG_LIB_HOMEDIR
+ in the configuration file. The default home directory is /.
+``cd ..`` sets the current working directory to the parent directory.
+================== =====================================
+
+Compare Files (cmp)
+*******************
+
+**Command Syntax**::
+
+ cmp <path1> <path2>
+
+**Synopsis**. Compare of the contents of the file at ``<path1>``
+with the contents of the file at ``<path2>``. Returns an
+indication only if the files differ.
+
+Copy Files (cp)
+***************
+
+**Command Syntax**::
+
+ cp <source-path> <dest-path>
+
+**Synopsis**. Copy of the contents of the file at
+``<source-path>`` to the location in the file system indicated by
+``<dest-path>``.
+
+Show or set the date and time (date)
+************************************
+
+**Command Syntax**::
+
+ date [-s "MMM DD HH:MM:SS YYYY"]
+
+**Synopsis**. Show or set the current date and time.
+
+Only one format is used both on display and when setting the
+date/time: ``MMM DD HH:MM:SS YYYY``. For example,
+
+24-hour time is used.
+
+Copy and Convert Files (dd)
+***************************
+
+**Command Syntax**::
+
+ dd if=<infile> of=<outfile> [bs=<sectsize>] [count=<sectors>] [skip=<sectors>]
+
+**Synopsis**. Copy blocks from <infile> to <outfile>. <infile> or
+<outfile> may be the path to a standard file, a character device,
+or a block device. Examples follow:
+
+Read from character device, write to regular file. This will
+create a new file of the specified size filled with zero::
+
+ nsh> ls -l /dev
+ /dev:
+ crw-rw-rw- 0 zero
+ nsh> dd if=/dev/zero of=/tmp/zeros bs=64 count=16
+ nsh> ls -l /tmp
+ /tmp:
+ -rw-rw-rw- 1024 ZEROS
+
+Read from character device, write to block device. This will fill
+the entire block device with zeros::
+
+ nsh> ls -l /dev
+ /dev:
+ brw-rw-rw- 0 ram0
+ crw-rw-rw- 0 zero
+ nsh> dd if=/dev/zero of=/dev/ram0
+
+Read from a block device, write to a character device. This will
+read the entire block device and dump the contents in the bit
+bucket::
+
+ nsh> ls -l /dev
+ /dev:
+ crw-rw-rw- 0 null
+ brw-rw-rw- 0 ram0
+ nsh> dd if=/dev/ram0 of=/dev/null
+
+Delete a Routing Table Entry (delroute)
+***************************************
+
+**Command Syntax**::
+
+ delroute <target> [<netmask>]
+
+**Synopsis**. The entry removed will be the first entry in the
+routing table that matches the external network characterized by
+the <target> IP address and the network mask <netmask>
+
+The netmask may also be expressed using IPv4 CIDR or IPv6 slash
+notation. In that case, the netmask need not be provided.
+
+**Example**::
+
+ nsh> delroute 11.0.0.0 255.255.255.0
+
+which is equivalent to::
+
+ nsh> delroute 11.0.0.0/24
+
+Show Volume Status (df)
+***********************
+
+**Command Syntax**::
+
+ df [-h]
+
+**Synopsis**. Show the state of each mounted volume. As an
+example::
+
+ nsh> mount
+ /etc type romfs
+ /tmp type vfat
+ nsh> df
+ Block Number
+ Size Blocks Used Available Mounted on
+ 64 6 6 0 /etc
+ 512 985 2 983 /tmp
+ nsh>
+
+If ``CONFIG_NSH_CMDOPT_DF_H`` is defined in the NuttX
+configuration, then the ``df`` will also support an option ``-h``
+which may be used to show the volume information in *human
+readable* format.
+
+Extract Path to a File/Directory (dirname)
+******************************************
+
+**Command Syntax**::
+
+ dirname <path>
+
+**Synopsis**. Extract the path string leading up to the full
+``<path>`` by removing the final directory or file name.
+
+Dump Buffered SYSLOG Output (dmesg)
+***********************************
+
+**Command Syntax**::
+
+ dmesg
+
+**Synopsis**. This command can be used to dump (and clear) the
+content of any buffered syslog output messages. This command is
+only available if ``CONFIG_RAMLOG_SYSLOG`` is enabled. In that
+case, syslog output will be collected in an in-memory, circular
+buffer. Entering the ``dmesg`` command will dump the content of
+that in-memory, circular buffer to the NSH console output.
+``dmesg`` has the side effect of clearing the buffered data so
+that entering ``dmesg`` again will show only newly buffered data.
+
+Echo Strings and Variables (echo)
+*********************************
+
+**Command Syntax**::
+
+ echo [-n] [<string|$name> [<string|$name>...]]
+
+**Synopsis**. Copy the sequence of strings and expanded
+environment variables to console output (or to a file if the
+output is re-directed).
+
+The ``-n`` option suppresses the trailing newline character.
+
+Show Environment Variables (env)
+********************************
+
+**Command Syntax**::
+
+ env
+
+**Synopsis**. Show the current name-value pairs in the
+environment. Example::
+
+ nsh> env
+ PATH=/bin
+
+ nsh> set foo bar
+ nsh> env
+ PATH=/bin
+ foo=bar
+
+ nsh> unset PATH
+ nsh> env
+ foo=bar
+
+ nsh>
+
+.. note::NSH local variables are *not* shown by the ``env``
+ command.
+
+Execute User Code (exec)
+************************
+
+**Command Syntax**::
+
+ exec <hex-address>
+
+**Synopsis**. Execute the user logic at address ``<hex-address>``.
+NSH will pause until the execution unless the user logic is
+executed in background via ``exec <hex-address> &``.
+
+Exit NSH (exit)
+***************
+
+**Command Syntax**::
+
+ exit
+
+**Synopsis**. Exit NSH. Only useful for the serial front end if
+you have started some other tasks (perhaps using the ``exec``
+command) and you would like to have NSH out of the way. For the
+telnet front-end, ``exit`` terminates the telnet session.
+
+Set an Environment Variable (export)
+************************************
+
+**Command Syntax**::
+
+ export <name> [<value>]
+
+**Synopsis**. The ``export`` command sets an environment variable,
+or promotes an NSH variable to an environment variable. As
+examples:
+
+ #. Using ``export`` to promote an NSH variable to an environment
+ variable::
+
+ nsh> env
+ PATH=/bin
+
+ nsh> set foo bar
+ nsh> env
+ PATH=/bin
+
+ nsh> export foo
+ nsh> env
+ PATH=/bin
+ foo=bar
+
+ A group-wide environment variable is created with the same
+ value as the local NSH variable; the local NSH variable is
+ removed.
+
+ .. note::This behavior differs from the Bash shell. Bash would
+ retain the local Bash variable which will shadow the
+ environment variable of the same name and same value.
+
+ #. Using ``export`` to set an environment variable::
+
+ nsh> export dog poop
+ nsh> env
+ PATH=/bin
+ foo=bar
+ dog=poop
+
+The ``export`` command is not supported by NSH unless both
+``CONFIG_NSH_VARS=y`` and ``CONFIG_DISABLE_ENVIRON``\ is not set.
+
+Show Memory Manager Status (free)
+*********************************
+
+**Command Syntax**::
+
+ free
+
+**Synopsis**. Show the current state of the memory allocator. For
+example::
+
+ nsh> free
+ total used free largest
+ Mem: 4194288 1591552 2602736 2601584
+ nsh>
+
+**Where:**
+
+======= ======================================
+total This is the total size of memory allocated for use by malloc in bytes.
+used This is the total size of memory occupied by chunks handed out by malloc.
+free This is the total size of memory occupied by free (not in use) chunks.
+largest Size of the largest free (not in use) chunk.
+======= ======================================
+
+Get File Via TFTP (get)
+***********************
+
+**Command Syntax**::
+
+ get [-b|-n] [-f <local-path>] -h <ip-address> <remote-path>
+
+**Synopsis**. Copy the file at ``<remote-address>`` from the host
+whose IP address is identified by ``<ip-address>``.
+
+**Other options**
+
+=================== ============================================
+``-f <local-path>`` The file will be saved relative to the current working directory unless <local-path> is provided.
+``-n`` Selects text ("netascii") transfer mode (default).
+``-b`` Selects binary ("octet") transfer mode
+=================== ============================================
+
+Show Usage Command Usage (help)
+*******************************
+
+**Command Syntax**::
+
+ help [-v] [<cmd>]
+
+**Synopsis**. Presents summary information about NSH commands to
+console.
+
+**Options**
+
+========= ====================
+``-v`` how verbose output will full command usage.
+``<cmd>`` Show full command usage only for this command.
+========= ====================
+
+Hexadecimal Dump of File or Device (hexdump)
+********************************************
+
+**Command Syntax**::
+
+ hexdump <file or device> [skip=<bytes>] [count=<bytes>]
+
+**Synopsis**. Dump data in hexadecimal format from a file or
+character device
+
+================= ==================================
+``skip=<bytes>`` Will skip <bytes> number of bytes from the beginning.
+``count=<bytes>`` Will stop after dumping <bytes> number of bytes.
+================= ==================================
+
+The ``skip`` and ``count`` options are only available if
+``CONFIG_NSH_CMDOPT_HEXDUMP`` is defined in the NuttX
+configuration.
+
+Manage Network Configuration (ifconfig)
+***************************************
+
+**Command Syntax**::
+
+ ifconfig [nic_name [<ip-address>|dhcp]] [dr|gw|gateway <dr-address>] [netmask <net-mask>] [dns <dns-address>] [hw <hw-mac>]]
+
+**Synopsis**. Multiple forms of the ``ifconfig`` command are
+supported:
+
+ #. With one or no arguments, ``ifconfig`` will shows the current
+ configuration of the network and, perhaps, the status of
+ Ethernet device::
+
+ ifconfig
+ ifconfig [nic_name]
+
+ As an example::
+
+ nsh> ifconfig
+ eth0 HWaddr 00:18:11:80:10:06
+ IPaddr:10.0.0.2 DRaddr:10.0.0.1 Mask:255.255.255.0
+
+ If network statistics are enabled (``CONFIG_NET_STATISTICS``),
+ then this command will also show the detailed state of network.
+
+ #. If both the network interface name and an IP address are
+ supplied as arguments, then ``ifconfig`` will set the address
+ of the Ethernet device::
+
+ ifconfig nic_name ip_address
+
+ #. Other forms *to be provided*
+
+.. note:: This commands depends upon having the *procfs* file system
+ configured into the system. The *procfs* file system must also
+ have been mounted with a command like::
+
+ nsh> mount -t procfs /proc
+
+Take a network down (ifdown)
+****************************
+
+**Command Syntax**::
+
+ ifdown <interface>
+
+**Synopsis**. Take down the interface identified by the name
+<interface>.
+
+**Example**::
+
+ ifdown eth0
+
+Bring a network up (ifup)
+*************************
+
+**Command Syntax**::
+
+ ifup <interface>
+
+**Synopsis**. Bring up down the interface identified by the name
+<interface>.
+
+**Example**::
+
+ ifup eth0
+
+Install an OS module (insmod)
+*****************************
+
+**Command Syntax**::
+
+ insmod <file-path> <module-name>
+
+**Synopsis**. Install the loadable OS module at <file-path> as
+module <module-name>.
+
+**Example**::
+
+ nsh> ls -l /mnt/romfs
+ /mnt/romfs:
+ dr-xr-xr-x 0 .
+ -r-xr-xr-x 9153 chardev
+ nsh> ls -l /dev
+ /dev:
+ crw-rw-rw- 0 console
+ crw-rw-rw- 0 null
+ brw-rw-rw- 0 ram0
+ crw-rw-rw- 0 ttyS0
+ nsh> lsmod
+ NAME INIT UNINIT ARG TEXT SIZE DATA SIZE
+ nsh> insmod /mnt/romfs/chardev mydriver
+ nsh> ls -l /dev
+ /dev:
+ crw-rw-rw- 0 chardev
+ crw-rw-rw- 0 console
+ crw-rw-rw- 0 null
+ brw-rw-rw- 0 ram0
+ crw-rw-rw- 0 ttyS0
+ nsh> lsmod
+ NAME INIT UNINIT ARG TEXT SIZE DATA SIZE
+ mydriver 20404659 20404625 0 20404580 552 204047a8 0
+
+
+Show Interrupt Status (irqinfo)
+*******************************
+
+**Command Syntax**::
+
+ irqinfo
+
+**Synopsis**. Show the current count of interrupts taken on all
+attached interrupts.
+
+**Example**::
+
+ nsh> irqinfo
+ IRQ HANDLER ARGUMENT COUNT RATE
+ 3 00001b3d 00000000 156 19.122
+ 15 0000800d 00000000 817 100.000
+ 30 00000fd5 20000018 20 2.490
+
+Send a signal to a task (kill)
+******************************
+
+**Command Syntax**::
+
+ kill -<signal> <pid>
+
+**Synopsis**. Send the <signal> to the task identified by <pid>.
+
+**Example**::
+
+ nsh> mkfifo /dev/fifo
+ nsh> cat /dev/fifo &
+ cat [2:128]
+ nsh> ps
+ PID PRI POLICY TYPE NPX STATE EVENT SIGMASK COMMAND
+ 0 0 FIFO Kthread --- Ready 00000000 Idle Task
+ 1 128 RR Task --- Running 00000000 init
+ 2 128 FIFO pthread --- Waiting Semaphore 00000000 <pthread>(51ea50)
+ nsh> kill -9 2
+ nsh> ps
+ PID PRI POLICY TYPE NPX STATE EVENT SIGMASK COMMAND
+ 0 0 FIFO Kthread --- Ready 00000000 Idle Task
+ 1 128 RR Task --- Running 00000000 init
+ nsh>
+
+.. note:: NuttX does not support a FULL POSIX signaling system. A
+ few standard signal names like ``SIGCHLD``, ``SIGUSR1``,
+ ``SIGUSR2``, ``SIGALRM``, and ``SIGPOLL`` exist in the system.
+ However, they do not have the default actions that you might
+ expect. Rather, NuttX supports only what are referred to as POSIX
+ real-time signals. These signals may be used to communicate with
+ running tasks, may be use to waiting waiting tasks, etc.
+
+ If the configuration option ``CONFIG_SIG_DEFAULT`` is enabled,
+ then default actions for the ``SIGINT`` and ``SIGKILL`` signals
+ (only) will be supported. In that case, as an example, ``kill -9``
+ (SIGKILL) will, indeed, terminate a task. Caution should be
+ exercised, however, because this is likely to cause memory leaks
+ and to strand resource since there is insufficient clean-up in
+ certain build configurations.
+
+Setup/teardown the Loop Device (losetup)
+****************************************
+
+**Command Syntax 1**::
+
+ losetup [-o <offset>] [-r] <dev-path> <file-path>
+
+**Synopsis**. Setup the loop device at <dev-path> to access the
+file at <file-path> as a block device. In the following example a
+256K file is created (``dd``) and ``losetup`` is used to make the
+file accessible as a block device. A FAT file system is created
+(``mkfatfs``) and mounted (``mount``). Files can then be managed
+on the loop-mounted file::
+
+ nsh> dd if=/dev/zero of=/tmp/image bs=512 count=512
+ nsh> ls -l /tmp
+ /tmp:
+ -rw-rw-rw- 262144 IMAGE
+ nsh> losetup /dev/loop0 /tmp/image
+ nsh> ls -l /dev
+ /dev:
+ brw-rw-rw- 0 loop0
+ nsh> mkfatfs /dev/loop0
+ nsh> mount -t vfat /dev/loop0 /mnt/example
+ nsh> ls -l /mnt
+ ls -l /mnt
+ /mnt:
+ drw-rw-rw- 0 example/
+ nsh> echo "This is a test" >/mnt/example/atest.txt
+ nsh> ls -l /mnt/example
+ /mnt/example:
+ -rw-rw-rw- 16 ATEST.TXT
+ nsh> cat /mnt/example/atest.txt
+ This is a test
+ nsh>
+
+**Command Syntax 2**::
+
+ losetup d <dev-path>
+
+**Synopsis**. Teardown the setup for the loop device at
+<dev-path>.
+
+Link to a File or Directory (ln)
+********************************
+
+**Command Syntax**::
+
+ ln [-s] <target> <link>
+
+**Synopsis**. The ``ln`` command will create a new symbolic link
+at <link> for the existing file or directory, <target>. This
+implementation is simplified for use with NuttX in these ways:
+
+ - Links may be created only within the NuttX top-level, `pseudo
+ file system <NuttxUserGuide.html#FileSystemOverview>`__. No
+ file system currently supported by NuttX provides symbolic
+ links.
+ - For the same reason, only soft links are implemented.
+ - File privileges are ignored.
+ - ``c_time`` is not updated.
+
+List Directory Contents (ls)
+****************************
+
+**Command Syntax**::
+
+ ls [-lRs] <dir-path>
+
+**Synopsis**. Show the contents of the directory at
+``<dir-path>``. NOTE: ``<dir-path>`` must refer to a directory and
+no other file system object.
+
+**Options**
+
+====== ================================
+``-R`` Show the contents of specified directory and all of its sub-directories.
+``-s`` Show the size of the files along with the filenames in the listing
+``-l`` Show size and mode information along with the filenames in the listing.
+====== ================================
+
+Show information about installed OS modules (lsmod)
+***************************************************
+
+**Command Syntax**::
+
+ lsmod
+
+**Synopsis**. Show information about the currently installed OS
+modules. This information includes:
+
+ - The module name assigned to the module when it was installed
+ (``NAME``, string).
+ - The address of the module initialization function (``INIT``,
+ hexadecimal).
+ - The address of the module un-initialization function
+ (``UNINIT``, hexadecimal).
+ - An argument that will be passed to the module un-initialization
+ function (``ARG``, hexadecimal).
+ - The start of the .text memory region (``TEXT``, hexadecimal).
+ - The size of the .text memory region size (``SIZE``, decimal).
+ - The start of the .bss/.data memory region (``DATA``,
+ hexadecimal).
+ - The size of the .bss/.data memory region size (``SIZE``,
+ decimal).
+
+**Example**::
+
+ nsh> lsmod
+ NAME INIT UNINIT ARG TEXT SIZE DATA SIZE
+ mydriver 20404659 20404625 0 20404580 552 204047a8 0
+
+Calculate MD5 (md5)
+*******************
+
+**Command Syntax**::
+
+ md5 [-f] <string or filepath>
+
+**Synopsis**. *To be provided.*
+
+Access Memory (mb, mh, and mw)
+******************************
+
+**Command Syntax**::
+
+ mb <hex-address>[=<hex-value>][ <hex-byte-count>]
+ mh <hex-address>[=<hex-value>][ <hex-byte-count>]
+ mw <hex-address>[=<hex-value>][ <hex-byte-count>]
+
+**Synopsis**. Access memory using byte size access (mb), 16-bit
+accesses (mh), or 32-bit access (mw). In each case,
+
+============================= ==============================================
+``<hex-address>`` Specifies the address to be accessed. The current
+ value at that address will always be read and displayed.
+``<hex-address>=<hex-value>`` Read the value, then write <hex-value> to the location.
+``<hex-byte-count>`` Perform the mb, mh, or mw operation on a total of
+ <hex-byte-count> bytes, increment the <hex-address>
+ appropriately after each access.
+============================= ==============================================
+
+**Example**::
+
+ nsh> mh 0 16
+ 0 = 0x0c1e
+ 2 = 0x0100
+ 4 = 0x0c1e
+ 6 = 0x0110
+ 8 = 0x0c1e
+ a = 0x0120
+ c = 0x0c1e
+ e = 0x0130
+ 10 = 0x0c1e
+ 12 = 0x0140
+ 14 = 0x0c1e
+ nsh>
+
+Show Current Tasks and Threads (ps)
+***********************************
+
+**Command Syntax**::
+
+ ps
+
+**Synopsis**. Show the currently active threads and tasks. For
+example::
+
+ nsh> ps
+ PID PRI POLICY TYPE NPX STATE EVENT SIGMASK COMMAND
+ 0 0 FIFO Kthread --- Ready 00000000 Idle Task
+ 1 128 RR Task --- Running 00000000 init
+ 2 128 FIFO Task --- Waiting Semaphore 00000000 nsh_telnetmain()
+ 3 100 RR pthread --- Waiting Semaphore 00000000 <pthread>(21)
+ nsh>
+
+NOTE: This commands depends upon having the *procfs* file system
+configured into the system. The *procfs* file system must also
+have been mounted with a command like::
+
+ nsh> mount -t procfs /proc
+
+Create a Directory (mkdir)
+**************************
+
+**Command Syntax**::
+
+ mkdir <path>
+
+**Synopsis**. Create the directory at ``<path>``. All components
+of ``<path>`` except the final directory name must exist on a
+mounted file system; the final directory must not.
+
+**Limited to Mounted File Systems**. Recall that NuttX uses a
+`pseudo file system <NuttxUserGuide.html#FileSystemOverview>`__
+for its root file system. The ``mkdir`` command can only be used
+to create directories in volumes set up with the
+```mount`` <#cmdmount>`__ command; it cannot be used to create
+directories in the *pseudo* file system.
+
+**Example**::
+
+ nsh> mkdir /mnt/fs/tmp
+ nsh> ls -l /mnt/fs
+ /mnt/fs:
+ drw-rw-rw- 0 TESTDIR/
+ drw-rw-rw- 0 TMP/
+ nsh>
+
+Create a FAT File System (mkfatfs)
+**********************************
+
+**Command Syntax**
+
+ mkfatfs [-F <fatsize>] [-r <rootdirentries>] <block-driver>
+
+**Synopsis**. Format a fat file system on the block device
+specified by ``<block-driver>`` path. The FAT size may be provided
+as an option. Without the ``<fatsize>`` option, ``mkfatfs`` will
+select either the FAT12 or FAT16 format. For historical reasons,
+if you want the FAT32 format, it must be explicitly specified on
+the command line.
+
+The ``-r`` option may be specified to select the the number of
+entries in the root directory for FAT12 and FAT16 file systems.
+Typical values for small volumes would be 112 or 224; 512 should
+be used for large volumes, such as hard disks or very large SD
+cards. The default is 512 entries in all cases.
+
+The reported number of root directory entries used with FAT32 is
+zero because the FAT32 root directory is a cluster chain.
+
+NSH provides this command to access the
+```mkfatfs()`` <mkfatfs>`__ NuttX API. This block device must
+reside in the NuttX `pseudo file
+system <NuttxUserGuide.html#FileSystemOverview>`__ and must have
+been created by some call to ``register_blockdriver()`` (see
+``include/nuttx/fs/fs.h``).
+
+Create a FIFO (mkfifo)
+**********************
+
+**Command Syntax**::
+
+ mkfifo <path>
+
+**Synopsis**. Creates a FIFO character device anywhere in the
+pseudo file system, creating whatever pseudo directories that may
+be needed to complete the ``<path>``. By convention, however,
+device drivers are place in the standard ``/dev`` directory. After
+it is created, the FIFO device may be used as any other device
+driver. NSH provides this command to access the
+```mkfifo()`` <NuttxUserGuide.html#mkfifo>`__ NuttX API.
+
+**Example**::
+
+ nsh> ls -l /dev
+ /dev:
+ crw-rw-rw- 0 console
+ crw-rw-rw- 0 null
+ brw-rw-rw- 0 ram0
+ nsh> mkfifo /dev/fifo
+ nsh> ls -l /dev
+ ls -l /dev
+ /dev:
+ crw-rw-rw- 0 console
+ crw-rw-rw- 0 fifo
+ crw-rw-rw- 0 null
+ brw-rw-rw- 0 ram0
+ nsh>
+
+Create a RAMDISK (mkrd)
+***********************
+
+**Command Syntax**::
+
+ mkrd [-m <minor>] [-s <sector-size>] <nsectors>
+
+**Synopsis**. Create a ramdisk consisting of ``<nsectors>``, each
+of size ``<sector-size>`` (or 512 bytes if ``<sector-size>`` is
+not specified. The ramdisk will be registered as
+``/dev/ram<minor>``. If ``<minor>`` is not specified, ``mkrd``
+will attempt to register the ramdisk as ``/dev/ram0``.
+
+**Example**::
+
+ nsh> ls /dev
+ /dev:
+ console
+ null
+ ttyS0
+ ttyS1
+ nsh> mkrd 1024
+ nsh> ls /dev
+ /dev:
+ console
+ null
+ ram0
+ ttyS0
+ ttyS1
+ nsh>
+
+Once the ramdisk has been created, it may be formatted using the
+``mkfatfs`` command and mounted using the ``mount`` command.
+
+**Example**::
+
+ nsh> mkrd 1024
+ nsh> mkfatfs /dev/ram0
+ nsh> mount -t vfat /dev/ram0 /tmp
+ nsh> ls /tmp
+ /tmp:
+ nsh>
+
+Mount a File System (mount)
+***************************
+
+**Command Syntax**::
+
+ mount -t <fstype> [-o <options>] <block-device> <dir-path>
+
+**Synopsis**. The ``mount`` command performs one of two different
+operations. If no parameters are provided on the command line
+after the ``mount`` command, then the ``mount`` command will
+enumerate all of the current mountpoints on the console.
+
+If the mount parameters are provided on the command after the
+``mount`` command, then the ``mount`` command will mount a file
+system in the NuttX pseudo-file system. ``mount`` performs a three
+way association, binding:
+
+ #. **File System.** The '-t ``<fstype>``' option identifies the
+ type of file system that has been formatted on the
+ ``<block-device>``. As of this writing, ``vfat`` is the only
+ supported value for ``<fstype>``
+ #. **Block Device.** The ``<block-device>`` argument is the full
+ or relative path to a block driver inode in the `pseudo file
+ system <NuttxUserGuide.html#FileSystemOverview>`__. By
+ convention, this is a name under the ``/dev`` sub-directory.
+ This ``<block-device>`` must have been previously formatted
+ with the same file system type as specified by ``<fstype>``
+ #. **Mount Point.** The mount point, ``<dir-path>``, is the
+ location in the `pseudo file
+ system <NuttxUserGuide.html#FileSystemOverview>`__ where the
+ mounted volume will appear. This mount point can only reside in
+ the NuttX `pseudo file
+ system <NuttxUserGuide.html#FileSystemOverview>`__. By
+ convention, this mount point is a subdirectory under ``/mnt``.
+ The mount command will create whatever pseudo directories that
+ may be needed to complete the full path but the full path must
+ not already exist.
+
+After the volume has been mounted in the NuttX `pseudo file
+system <NuttxUserGuide.html#FileSystemOverview>`__, it may be
+access in the same way as other objects in the file system.
+
+**Examples**:
+
+Using ``mount`` to mount a file system::
+
+ nsh> ls -l /dev
+ /dev:
+ crw-rw-rw- 0 console
+ crw-rw-rw- 0 null
+ brw-rw-rw- 0 ram0
+ nsh> ls /mnt
+ nsh: ls: no such directory: /mnt
+ nsh> mount -t vfat /dev/ram0 /mnt/fs
+ nsh> ls -l /mnt/fs/testdir
+ /mnt/fs/testdir:
+ -rw-rw-rw- 15 TESTFILE.TXT
+ nsh> echo "This is a test" >/mnt/fs/testdir/example.txt
+ nsh> ls -l /mnt/fs/testdir
+ /mnt/fs/testdir:
+ -rw-rw-rw- 15 TESTFILE.TXT
+ -rw-rw-rw- 16 EXAMPLE.TXT
+ nsh> cat /mnt/fs/testdir/example.txt
+ This is a test
+ nsh>
+
+Using ``mount`` to enumerate mounts::
+
+ nsh> mount
+ /etc type romfs
+ /mnt/fs type vfat
+ /tmp type vfat
+
+Rename a File (mv)
+******************
+
+**Command Syntax**::
+
+ mv <old-path> <new-path>
+
+**Synopsis**. Rename the file object at ``<old-path>`` to
+``<new-path>``. Both paths must reside in the same mounted file
+system.
+
+Mount an NFS file system (nfsmount)
+***********************************
+
+**Command Syntax**::
+
+ nfsmount <server-address> <mount-point> <remote-path>
+
+**Synopsis**. Mount the remote NFS server directory<remote-path>
+at <mount-point> on the target machine. <server-address> is the IP
+address of the remote server.
+
+Lookup a network address (nslookup)
+***********************************
+
+**Command Syntax**::
+
+ nslookup <host-name>
+
+**Synopsis**. Lookup and print the IP address associated with
+``<host-name>``.
+
+Change a User's Password (passwd)
+*********************************
+
+**Command Syntax**::
+
+ passwd <username> <password>
+
+**Synopsis**. Set the password for the existing user <username> to
+<password>.
+
+Manage Power Management Subsystem (pmconfig)
+********************************************
+
+**Command Syntax**::
+
+ pmconfig [stay|relax] [normal|idle|standby|sleep]
+
+**Synopsis**. Control power management subsystem.
+
+Shut the system down (poweroff)
+*******************************
+
+**Command Syntax**::
+
+ poweroff [<n>]
+
+**Synopsis**. Shutdown and power off the system immediately. This
+command depends on board-specific hardware support to power down
+the system. The optional,decimal numeric argument may be included
+to provide power off mode to board-specific power off logic.
+
+NOTE: Supporting both the ``poweroff`` and ``shutdown`` commands
+is redundant.
+
+Send File Via TFTP (put)
+************************
+
+**Command Syntax**::
+
+ put [-b|-n] [-f <remote-path>] -h <ip-address> <local-path>
+
+**Synopsis**. Copy the file at ``<local-address>`` to the host
+whose IP address is identified by ``<ip-address>``.
+
+**Other options:**
+
+==================== =============================================
+``-f <remote-path>`` The file will be saved relative with the same
+ name on the host unless <remote-path> is provided.
+``-b|-n`` Selects either binary ("octet") or text ("netascii")
+ transfer mode. Default: text.
+==================== =============================================
+
+Show Current Working Directory (pwd)
+************************************
+
+**Command Syntax**::
+
+ pwd
+
+**Synopsis**. Show the current working directory::
+
+ nsh> cd /dev
+ nsh> pwd
+ /dev
+ nsh>
+
+Same as ``echo $PWD``::
+
+ nsh> echo $PWD
+ /dev
+ nsh>
+
+Show target of a link (readlink)
+********************************
+
+**Command Syntax**::
+
+ readlink <link>
+
+**Synopsis**. Show the target of the soft link at the path
+``<link>``.
+
+Reboot the system (reboot)
+**************************
+
+**Command Syntax**::
+
+ reboot [<n>]
+
+**Synopsis**. Reset and reboot the system immediately. This
+command depends on hardware support to reset the system. The
+optional, decimal numeric argument <n> may be included to provide
+a reboot mode to board-specific reboot logic.
+
+NOTE: Supporting both the ``reboot`` and ``shutdown`` commands is
+redundant.
+
+Remove a File (rm)
+******************
+
+**Command Syntax**::
+
+ rm <file-path>
+
+**Synopsis**. Remove the specified ``<file-path>`` name from the
+mounted file system. Recall that NuttX uses a `pseudo file
+system <NuttxUserGuide.html#FileSystemOverview>`__ for its root
+file system. The ``rm`` command can only be used to remove
+(unlink) files in volumes set up with the
+```mount`` <#cmdmount>`__ command; it cannot be used to remove
+names in the *pseudo* file system.
+
+**Example**::
+
+ nsh> ls /mnt/fs/testdir
+ /mnt/fs/testdir:
+ TESTFILE.TXT
+ EXAMPLE.TXT
+ nsh> rm /mnt/fs/testdir/example.txt
+ nsh> ls /mnt/fs/testdir
+ /mnt/fs/testdir:
+ TESTFILE.TXT
+ nsh>
+
+Remove a Directory (rmdir)
+**************************
+
+**Command Syntax**::
+
+ rmdir <dir-path>
+
+**Synopsis**. Remove the specified ``<dir-path>`` directory from
+the mounted file system. Recall that NuttX uses a `pseudo file
+system <NuttxUserGuide.html#FileSystemOverview>`__ for its root
+file system. The ``rmdir`` command can only be used to remove
+directories from volumes set up with the ```mount`` <#cmdmount>`__
+command; it cannot be used to remove directories from the *pseudo*
+file system.
+
+**Example**::
+
+ nsh> mkdir /mnt/fs/tmp
+ nsh> ls -l /mnt/fs
+ /mnt/fs:
+ drw-rw-rw- 0 TESTDIR/
+ drw-rw-rw- 0 TMP/
+ nsh> rmdir /mnt/fs/tmp
+ nsh> ls -l /mnt/fs
+ /mnt/fs:
+ drw-rw-rw- 0 TESTDIR/
+ nsh>
+
+Remove on OS Module (rmmod)
+***************************
+
+**Command Syntax**::
+
+ rmmod <module-name>
+
+**Synopsis**. Remove the loadable OS module with the
+<module-name>. NOTE: An OS module can only be removed if it is not
+busy.
+
+**Example**::
+
+ nsh> lsmod
+ NAME INIT UNINIT ARG TEXT SIZE DATA SIZE
+ mydriver 20404659 20404625 0 20404580 552 204047a8 0
+ nsh> rmmod mydriver
+ nsh> lsmod
+ NAME INIT UNINIT ARG TEXT SIZE DATA SIZE
+ nsh>
+
+Show routing table (route)
+**************************
+
+**Command Syntax**::
+
+ route ipv4|ipv6
+
+**Synopsis**. Show the contents of routing table for IPv4 or IPv6.
+
+If only IPv4 or IPv6 is enabled, then the argument is optional
+but, if provided, must match the enabled internet protocol
+version.
+
+Start/Stop the OpenAMP RPC Tunnel (rptun)
+*****************************************
+
+**Command Syntax**::
+
+ rptun start|stop <dev-path>
+
+**Synopsis**. Start or stop the OpenAMP RPC tunnel device at <dev-path>.
+
+Set a Variable (set)
+********************
+
+**Command Syntax**::
+
+ set [{+|-}{e|x|xe|ex}] [<name> <value>]
+
+**Synopsis**. Set the variable ``<name>`` to the string ``<value>`` and
+or set NSH parser control options.
+
+For example, a variable may be set like this::
+
+ nsh> echo $foobar
+
+ nsh> set foobar foovalue
+ nsh> echo $foobar
+ foovalue
+ nsh>
+
+If ``CONFIG_NSH_VARS`` is selected, the effect of this ``set`` command
+is to set the local NSH variable. Otherwise, the group-wide environment
+variable will be set.
+
+If the local NSH variable has already been *promoted* to an environment
+variable via the ```export`` <#cmdexport>`__, then the ``set`` command
+will set the value of the environment variable rather than the local NSH
+variable.
+
+.. note:: The Bash shell does not work this way. Bash would set the value
+ of both the local Bash variable and the environment variable of the
+ same name to the same value.
+
+If ``CONFIG_NSH_VARS=y`` is selected and no arguments are provided, then
+the ``set`` command will list all of the local NSH variables::
+
+ nsh> set
+ foolbar=foovalue
+
+Set the *exit on error control* and/or *print a trace* of commands when
+parsing scripts in NSH. The settings are in effect from the point of
+execution, until they are changed again, or in the case of the
+initialization script, the settings are returned to the default settings
+when it exits. Included child scripts will run with the parents settings
+and changes made in the child script will effect the parent on return.
+
+ - Use ``set -e`` to enable and ``set +e`` to disable (ignore) the exit
+ condition on commands. The default is -e. Errors cause script to
+ exit.
+
+ - Use ``set -x`` to enable and ``set +x`` to disable (silence) printing
+ a trace of the script commands as they are executed. The default is
+ ``+x``: no printing of a trace of script commands as they are
+ executed.
+
+Example 1 - no exit on command not found::
+
+ set +e
+ notacommand
+
+Example 2 - will exit on command not found::
+
+ set -e
+ notacommand
+
+Example 3 - will exit on command not found, and print a trace of the
+script commands::
+
+ set -ex
+
+Example 4 - will exit on command not found, and print a trace of the
+script commands and set foobar to foovalue::
+
+ set -ex foobar foovalue
+ nsh> echo $foobar
+ foovalue
+
+Execute an NSH Script (sh)
+**************************
+
+**Command Syntax**::
+
+ sh <script-path>
+
+**Synopsis**. Execute the sequence of NSH commands in the file referred
+to by ``<script-path>``.
+
+Shut the system down (shutdown)
+*******************************
+
+**Command Syntax**::
+
+ shutdown [--reboot]
+
+**Synopsis**. Shutdown and power off the system or, optionally, reset
+and reboot the system immediately. This command depends on hardware
+support to power down or reset the system; one, both, or neither
+behavior may be supported.
+
+NOTE: The ``shutdown`` command duplicates the behavior of the
+``poweroff`` and ``eboot`` commands.
+
+Wait for Seconds (sleep)
+************************
+
+**Command Syntax**::
+
+ sleep <sec>
+
+**Synopsis**. Pause execution (sleep) for ``<sec>`` seconds.
+
+Time Start the Telnet Daemon (telnetd)
+**************************************
+
+**Command Syntax**::
+
+ telnetd
+
+**Synopsis**. Start the Telnet daemon if it is not already running.
+
+The Telnet daemon may be started either programmatically by calling
+``nsh_telnetstart()`` or it may be started from the NSH command line
+using this ``telnetd`` command.
+
+Normally this command would be suppressed with
+``CONFIG_NSH_DISABLE_TELNETD`` because the Telnet daemon is
+automatically started in ``nsh_main.c``. The exception is when
+``CONFIG_NSH_NETLOCAL`` is selected. In that case, the network is not
+enabled at initialization but rather must be enabled from the NSH
+command line or via other applications.
+
+In that case, when ``nsh_telnetstart()`` is called before the the
+network is initialized, it will fail.
+
+Time execution of another command (time)
+****************************************
+
+**Command Syntax**::
+
+ time "<command>"
+
+**Synopsis**. Perform command timing. This command will execute the
+following <command> string and then show how much time was required to
+execute the command. Time is shown with a resolution of 100 microseconds
+which may be beyond the resolution of many configurations. Note that the
+<command> must be enclosed in quotation marks if it contains spaces or
+other delimiters.
+
+**Example**::
+
+ nsh> time "sleep 2"
+
+ 2.0100 sec
+ nsh>
+
+The additional 10 milliseconds in this example is due to the way that
+the sleep command works: It always waits one system clock tick longer
+than requested and this test setup used a 10 millisecond periodic system
+timer. Sources of error could include various quantization errors,
+competing CPU usage, and the additional overhead of the time command
+execution itself which is included in the total.
+
+The reported time is the elapsed time from starting of the command to
+completion of the command. This elapsed time may not necessarily be just
+the processing time for the command. It may included interrupt level
+processing, for example. In a busy system, command processing could be
+delayed if pre-empted by other, higher priority threads competing for
+CPU time. So the reported time includes all CPU processing from the
+start of the command to its finish possibly including unrelated
+processing time during that interval.
+
+Notice that::
+
+ nsh> time "sleep 2 &"
+ sleep [3:100]
+
+ 0.0000 sec
+ nsh>
+
+Since the sleep command is executed in background, the sleep command
+completes almost immediately. As opposed to the following where the time
+command is run in background with the sleep command::
+
+ nsh> time "sleep 2" &
+ time [3:100]
+ nsh>
+ 2.0100 sec
+
+Set the Size of a File (truncate)
+*********************************
+
+**Command Syntax**::
+
+ truncate -s <length> <file-path>
+
+**Synopsis**. Shrink or extend the size of the regular file at
+<file-path> to the specified<length>.
+
+A <file-path> argument that does not exist is created. The <length>
+option is NOT optional.
+
+If a <file-path> is larger than the specified size, the extra data is
+lost. If a <file-path> is shorter, it is extended and the extended part
+reads as zero bytes.
+
+Unmount a File System (umount)
+******************************
+
+**Command Syntax**::
+
+ umount <dir-path>
+
+**Synopsis**. Un-mount the file system at mount point ``<dir-path>``.
+The ``umount`` command can only be used to un-mount volumes previously
+mounted using ```mount`` <#cmdmount>`__ command.
+
+**Example**::
+
+ nsh> ls /mnt/fs
+ /mnt/fs:
+ TESTDIR/
+ nsh> umount /mnt/fs
+ nsh> ls /mnt/fs
+ /mnt/fs:
+ nsh: ls: no such directory: /mnt/fs
+ nsh>
+
+Print system information (uname)
+********************************
+
+**Command Syntax**::
+
+ uname [-a | -imnoprsv]
+
+**Synopsis**. Print certain system information. With no options, the
+output is the same as -s.
+
+========== ========================================
+``-a`` Print all information, in the following
+ order, except omit -p and -i if unknown:
+``-s, -o`` Print the operating system name (NuttX)
+``-n`` Print the network node hostname (only available if CONFIG_NET=y)
+``-r`` Print the kernel release
+``-v`` Print the kernel version
+``-m`` Print the machine hardware name
+``-i`` Print the machine platform name
+``-p`` Print "unknown"
+========== ========================================
+
+Unset an Environment Variable (unset)
+*************************************
+
+**Command Syntax**:
+
+ unset <name>
+
+**Synopsis**. Remove the value associated with the variable ``<name>``.
+This will remove the name-value pair from both the NSH local variables
+and the group-wide environment variables. For example::
+
+ nsh> echo $foobar
+ foovalue
+ nsh> unset foobar
+ nsh> echo $foobar
+
+ nsh>
+
+URL Decode (urldecode)
+**********************
+
+**Command Syntax**::
+
+ urldecode [-f] <string or filepath>
+
+**Synopsis**. *To be provided.*
+
+URL Encode (urlencode)
+**********************
+
+**Command Syntax**::
+
+ urlencode [-f] <string or filepath>
+
+**Synopsis**. *To be provided.*
+
+Add a New User (useradd)
+************************
+
+**Command Syntax**::
+
+ useradd <username> <password>
+
+**Synopsis**. Add a new user with <username> and <password>.
+
+Delete a user (userdel)
+***********************
+
+**Command Syntax**::
+
+ userdel <username>
+
+**Synopsis**. Delete the user with the name <username>.
+
+Wait for Microseconds (usleep)
+******************************
+
+**Command Syntax**::
+
+ usleep <usec>
+
+**Synopsis**. Pause execution (sleep) of ``<usec>`` microseconds.
+
+Get File Via HTTP (wget)
+************************
+
+**Command Syntax**
+
+ wget [-o <local-path>] <url>
+
+**Synopsis**. Use HTTP to copy the file at ``<url>`` to the current
+directory.
+
+**Options**
+
+=================== =================================================
+``-o <local-path>`` The file will be saved relative to the current working
+ directory and with the same name as on the HTTP server
+ unless <local-path> is provided.
+=================== =================================================
+
+Hexadecimal Dump of Memory (xd)
+*******************************
+
+**Command Syntax**::
+
+ xd <hex-address> <byte-count>
+
+**Synopsis**. Dump ``<byte-count>`` bytes of data from address
+``<hex-address>``.
+
+**Example**::
+
+ nsh> xd 410e0 512
+ Hex dump:
+ 0000: 00 00 00 00 9c 9d 03 00 00 00 00 01 11 01 10 06 ................
+ 0010: 12 01 11 01 25 08 13 0b 03 08 1b 08 00 00 02 24 ....%..........$
+ ...
+ 01f0: 08 3a 0b 3b 0b 49 13 00 00 04 13 01 01 13 03 08 .:.;.I..........
+ nsh>
+
+Built-In Commands
+=================
+
+In addition to the commands that are part of NSH listed in the previous
+section above, there can be additional, external *built-in* applications
+that can be added to NSH. These are separately excecuble programs but
+will appear much like the commands that are a part of NSH. The primary
+difference from the user's perspective is that help information about
+the built-in applications is not available directly from NSH. Rather,
+you will need to execute the application with the ``-h`` option to get
+help about using the built-in applications.
+
+There are several built-in applications in the ``apps/`` repository. No
+attempt is made here to enumerate all of them. But a few of the more
+common, useful built-in applications are listed below.
+
+Check Network Peer (ping/ping6)
+*******************************
+
+**Command Syntax**::
+
+ ping [-c <count>] [-i <interval>] <ip-address>
+ ping6 [-c <count>] [-i <interval>] <ip-address>
+
+**Synopsis**. Test the network communication with a remote peer.
+Example::
+
+ nsh> ping 10.0.0.1
+ PING 10.0.0.1 56 bytes of data
+ 56 bytes from 10.0.0.1: icmp_seq=1 time=0 ms
+ 56 bytes from 10.0.0.1: icmp_seq=2 time=0 ms
+ 56 bytes from 10.0.0.1: icmp_seq=3 time=0 ms
+ 56 bytes from 10.0.0.1: icmp_seq=4 time=0 ms
+ 56 bytes from 10.0.0.1: icmp_seq=5 time=0 ms
+ 56 bytes from 10.0.0.1: icmp_seq=6 time=0 ms
+ 56 bytes from 10.0.0.1: icmp_seq=7 time=0 ms
+ 56 bytes from 10.0.0.1: icmp_seq=8 time=0 ms
+ 56 bytes from 10.0.0.1: icmp_seq=9 time=0 ms
+ 56 bytes from 10.0.0.1: icmp_seq=10 time=0 ms
+ 10 packets transmitted, 10 received, 0% packet loss, time 10190 ms
+ nsh>
+
+``ping6`` differs from ``ping`` in that it uses IPv6 addressing.
+
+
diff --git a/doc/components/nsh/config.rst b/doc/components/nsh/config.rst
new file mode 100644
index 0000000..e3e74d8
--- /dev/null
+++ b/doc/components/nsh/config.rst
@@ -0,0 +1,486 @@
+.. |br| raw:: html
+
+ <br/>
+
+======================
+Configuration Settings
+======================
+
+The availability of the above commands depends upon features that may or
+may not be enabled in the NuttX configuration file. The following
+`table <#cmddependencies>`__ indicates the dependency of each command on
+NuttX configuration settings. General configuration settings are
+discussed in the `NuttX Porting Guide. <NuttxPortingGuide.html>`__
+Configuration settings specific to NSH as discussed at the
+`bottom <#nshconfiguration>`__ of this document.
+
+Note that in addition to general NuttX configuration settings, each NSH
+command can be individually disabled via the settings in the rightmost
+column. All of these settings make the configuration of NSH potentially
+complex but also allow it to squeeze into very small memory footprints.
+
+Command Dependencies on Configuration Settings
+==============================================
+
+====================== =========================================== ======================
+Command Depends on Configuration Can Be Disabled with
+====================== =========================================== ======================
+``[`` ! ``CONFIG_NSH_DISABLESCRIPT`` ``CONFIG_NSH_DISABLE_TEST``
+``addroute`` ``CONFIG_NET`` && ``CONFIG_NET_ROUTE`` ``CONFIG_NSH_DISABLE_ADDROUTE``
+``arp`` ``CONFIG_NET`` && ``CONFIG_NET_ARP`` ``CONFIG_NSH_DISABLE_ARP``
+``base64dec`` ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_BASE64DEC``
+ ``CONFIG_CODECS_BASE64``
+``base64enc`` ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_BASE64ENC``
+ ``CONFIG_CODECS_BASE64``
+``basename`` . ``CONFIG_NSH_DISABLE_BASENAME``
+``break`` ! ``CONFIG_NSH_DISABLESCRIPT`` && .
+ ! ``CONFIG_NSH_DISABLE_LOOPS``
+``cat`` ``CONFIG_NSH_DISABLE_CAT`` .
+``cd`` ! ``CONFIG_DISABLE_ENVIRON`` ``CONFIG_NSH_DISABLE_CD``
+``cmp`` ``CONFIG_NSH_DISABLE_CMP`` .
+``cp`` ``CONFIG_NSH_DISABLE_CP`` .
+``date`` ``CONFIG_NSH_DISABLE_DATE`` .
+``dd`` ``CONFIG_NSH_DISABLE_DD`` .
+``delroute`` ``CONFIG_NET`` && ``CONFIG_NET_ROUTE`` ``CONFIG_NSH_DISABLE_DELROUTE``
+``df`` ! ``CONFIG_DISABLE_MOUNTPOINT`` ``CONFIG_NSH_DISABLE_DF``
+``dirname`` ``CONFIG_NSH_DISABLE_DIRNAME`` .
+``dmesg`` ``CONFIG_RAMLOG_SYSLOG`` ``CONFIG_NSH_DISABLE_DMESG``
+``echo`` ``CONFIG_NSH_DISABLE_ECHO`` .
+``env`` ``CONFIG_FS_PROCFS`` && ``CONFIG_NSH_DISABLE_ENV``
+ ! ``CONFIG_DISABLE_ENVIRON`` && |br|
+ ! ``CONFIG_PROCFS_EXCLUDE_ENVIRON``
+``exec`` ``CONFIG_NSH_DISABLE_EXEC`` .
+``exit`` ``CONFIG_NSH_DISABLE_EXIT`` .
+``export`` ``CONFIG_NSH_VARS`` &&
+ ! ``CONFIG_DISABLE_ENVIRON`` ``CONFIG_NSH_DISABLE_EXPORT``
+``free`` ``CONFIG_NSH_DISABLE_FREE`` .
+``get`` ``CONFIG_NET`` && ``CONFIG_NET_UDP`` && ``CONFIG_NSH_DISABLE_GET``
+ *MTU* >= 58\ [#1]_
+``help`` [#3]_ ``CONFIG_NSH_DISABLE_HELP`` .
+``hexdump`` ``CONFIG_NSH_DISABLE_HEXDUMP`` .
+``ifconfig`` ``CONFIG_NET`` && ``CONFIG_FS_PROCFS`` && ``CONFIG_NSH_DISABLE_IFCONFIG``
+ ! ``CONFIG_FS_PROCFS_EXCLUDE_NET``
+``ifdown`` ``CONFIG_NET`` && ``CONFIG_FS_PROCFS`` && ``CONFIG_NSH_DISABLE_IFUPDOWN``
+ ! ``CONFIG_FS_PROCFS_EXCLUDE_NET``
+``ifup`` ``CONFIG_NET`` && ``CONFIG_FS_PROCFS`` &&
+ ! ``CONFIG_FS_PROCFS_EXCLUDE_NET`` ``CONFIG_NSH_DISABLE_IFUPDOWN``
+``insmod`` ``CONFIG_MODULE`` ``CONFIG_NSH_DISABLE_MODCMDS``
+``irqinfo`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && .
+ ``CONFIG_FS_PROCFS`` && |br|
+ ``CONFIG_SCHED_IRQMONITOR``
+``kill`` ``CONFIG_NSH_DISABLE_KILL`` .
+``losetup`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_LOSETUP``
+ ``CONFIG_DEV_LOOP``
+``ln`` ``CONFIG_PSEUDOFS_SOFTLINKS`` ``CONFIG_NSH_DISABLE_LN``
+``ls`` ``CONFIG_NSH_DISABLE_LS`` .
+``lsmod`` ``CONFIG_MODULE`` && ``CONFIG_FS_PROCFS`` ``CONFIG_NSH_DISABLE_MODCMDS``
+ && |br|
+ ! ``CONFIG_FS_PROCFS_EXCLUDE_MODULE``
+``md5`` ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_MD5``
+ ``CONFIG_CODECS_HASH_MD5``
+``mb,mh,mw`` . ``CONFIG_NSH_DISABLE_MB``, |br|
+ ``CONFIG_NSH_DISABLE_MH``, |br|
+ ``CONFIG_NSH_DISABLE_MW``
+``mkdir`` (! ``CONFIG_DISABLE_MOUNTPOINT`` \|\| ``CONFIG_NSH_DISABLE_MKDIR``
+ ! ``CONFIG_DISABLE_PSEUDOFS_OPERATIONS``)
+``mkfatfs`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_MKFATFS``
+ ``CONFIG_FSUTILS_MKFATFS``
+``mkfifo`` ``CONFIG_PIPES`` && ``CONFIG_NSH_DISABLE_MKFIFO``
+ ``CONFIG_DEV_FIFO_SIZE`` > 0
+``mkrd`` ! ``CONFIG_DISABLE_MOUNTPOINT`` ``CONFIG_NSH_DISABLE_MKRD``
+``mount`` ! ``CONFIG_DISABLE_MOUNTPOINT`` ``CONFIG_NSH_DISABLE_MOUNT``
+``mv`` ! ``CONFIG_DISABLE_MOUNTPOINT`` \|\| ``CONFIG_NSH_DISABLE_MV``
+ ! ``CONFIG_DISABLE_PSEUDOFS_OPERATIONS``
+``nfsmount`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_NFSMOUNT``
+ ``CONFIG_NET`` && ``CONFIG_NFS``
+``nslookup`` ``CONFIG_LIBC_NETDB`` && ``CONFIG_NSH_DISABLE_NSLOOKUP``
+ ``CONFIG_NETDB_DNSCLIENT``
+``passwd`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_PASSWD``
+ ``CONFIG_NSH_LOGIN_PASSWD``
+``pmconfig`` ``CONFIG_PM`` ``CONFIG_NSH_DISABLE_PMCONFIG``
+``poweroff`` ``CONFIG_BOARDCTL_POWEROFF`` ``CONFIG_NSH_DISABLE_POWEROFF``
+``ps`` ``CONFIG_FS_PROCFS`` && ``CONFIG_NSH_DISABLE_PS``
+ ! ``CONFIG_FS_PROCFS_EXCLUDE_PROC``
+``put`` ``CONFIG_NET`` && ``CONFIG_NET_UDP`` && ``CONFIG_NSH_DISABLE_PUT``
+ ``MTU >= 558`` [#1]_, [#2]_
+``pwd`` ! ``CONFIG_DISABLE_ENVIRON`` ``CONFIG_NSH_DISABLE_PWD``
+``readlink`` ``CONFIG_PSEUDOFS_SOFTLINKS`` ``CONFIG_NSH_DISABLE_READLINK``
+``reboot`` ``CONFIG_BOARD_RESET`` ``CONFIG_NSH_DISABLE_REBOOT``
+``rm`` ! ``CONFIG_DISABLE_MOUNTPOINT`` \|\| ``CONFIG_NSH_DISABLE_RM``
+ ! ``CONFIG_DISABLE_PSEUDOFS_OPERATIONS``
+``rmdir`` ! ``CONFIG_DISABLE_MOUNTPOINT`` \|\
+ ! ``CONFIG_DISABLE_PSEUDOFS_OPERATIONS`` ``CONFIG_NSH_DISABLE_RMDIR``
+``rmmod`` ``CONFIG_MODULE`` ``CONFIG_NSH_DISABLE_MODCMDS``
+``route`` ``CONFIG_FS_PROCFS`` && ``CONFIG_NSH_DISABLE_ROUTE``
+ ``CONFIG_FS_PROCFS_EXCLUDE_NET`` && |br|
+ ! ``CONFIG_FS_PROCFS_EXCLUDE_ROUTE`` &&
+ ``CONFIG_NET_ROUTE`` && |br|
+ ! ``CONFIG_NSH_DISABLE_ROUTE`` && |br|
+ (``CONFIG_NET_IPv4`` \|\
+ ``CONFIG_NET_IPv6``)
+``rptun`` ``CONFIG_RPTUN`` ``CONFIG_NSH_DISABLE_RPTUN``
+``set`` ``CONFIG_NSH_VARS`` \|\| ``CONFIG_NSH_DISABLE_SET``
+ ! ``CONFIG_DISABLE_ENVIRON``
+``shutdown`` ``CONFIG_BOARDCTL_POWEROFF`` \|\| ``CONFIG_NSH_DISABLE_SHUTDOWN``
+ ``CONFIG_BOARD_RESET``
+``sleep`` . ``CONFIG_NSH_DISABLE_SLEEP``
+``source`` ``CONFIG_NFILE_STREAMS > 0`` && ``CONFIG_NSH_DISABLE_SOURCE``
+ ! ``CONFIG_NSH_DISABLESCRIPT``
+``telnetd`` ``CONFIG_NSH_TELNET`` ``CONFIG_NSH_DISABLE_TELNETD``
+``test`` ! ``CONFIG_NSH_DISABLESCRIPT`` ``CONFIG_NSH_DISABLE_TEST``
+``time`` . ``CONFIG_NSH_DISABLE_TIME``
+``truncate`` ! ``CONFIG_DISABLE_MOUNTPOINT`` ``CONFIG_NSH_DISABLE_TRUNCATE``
+``umount`` ! ``CONFIG_DISABLE_MOUNTPOINT`` ``CONFIG_NSH_DISABLE_UMOUNT``
+``uname`` . ``CONFIG_NSH_DISABLE_UNAME``
+``unset`` ``CONFIG_NSH_VARS`` \|\| ``CONFIG_NSH_DISABLE_UNSET``
+ ! ``CONFIG_DISABLE_ENVIRON``
+``urldecode`` ! ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_URLDECODE``
+ ``CONFIG_CODECS_URLCODE``
+``urlencode`` ! ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_URLENCODE``
+ ``CONFIG_CODECS_URLCODE``
+``useradd`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_USERADD``
+ ``CONFIG_NSH_LOGIN_PASSWD``
+``userdel`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_USERDEL``
+ ``CONFIG_NSH_LOGIN_PASSWD``
+``usleep`` . ``CONFIG_NSH_DISABLE_USLEEP``
+``wget`` ``CONFIG_NET`` && ``CONFIG_NET_TCP`` ``CONFIG_NSH_DISABLE_WGET``
+``xd`` . ``CONFIG_NSH_DISABLE_XD``
+====================== =========================================== ======================
+
+.. [#1] Because of hardware padding, the actual required packet size may be larger
+.. [#2] Special TFTP server start-up options will probably be required to permit creation of files for the correct operation of the ``put`` command.
+.. [#3] Verbose help output can be suppressed by defining ``CONFIG_NSH_HELP_TERSE``. In that case, the help command is still available but will be slightly smaller.
+
+Built-In Command Dependencies on Configuration Settings
+=======================================================
+
+All built-in applications require that support for NSH built-in
+applications has been enabled. This support is enabled with
+``CONFIG_BUILTIN=y`` and ``CONFIG_NSH_BUILTIN_APPS=y``.
+
+============= ==================================================================================================
+Command Depends on Configuration
+============= ==================================================================================================
+``ping`` ``CONFIG_NET`` && ``CONFIG_NET_ICMP`` && ``CONFIG_NET_ICMP_SOCKET`` && ``CONFIG_SYSTEM_PING``
+``ping6`` ``CONFIG_NET`` && ``CONFIG_NET_ICMPv6`` && ``CONFIG_NET_ICMPv6_SOCKET`` && ``CONFIG_SYSTEM_PING6``
+============= ==================================================================================================
+
+NSH-Specific Configuration Settings
+===================================
+
+The behavior of NSH can be modified with the following settings in the
+``boards/<arch>/<chip>/<board>/defconfig`` file:
+
+=================================== ==================================
+Configuration Description
+=================================== ==================================
+ ``CONFIG_NSH_READLINE`` Selects the minimal implementation of ``readline()``.
+ This minimal implementation provides on backspace for command
+ line editing. It expects some minimal VT100 command support from the terminal.
+
+ ``CONFIG_NSH_CLE`` Selects the more extensive, EMACS-like command line editor.
+ Select this option only if (1) you don't mind a modest increase
+ in the FLASH footprint, and (2) you work with a terminal that
+ supports extensive VT100 editing commands. Selecting this option
+ will add probably 1.5-2KB to the FLASH footprint.
+
+ ``CONFIG_NSH_BUILTIN_APPS`` Support external registered, "builtin" applications that can
+ be executed from the NSH command line (see apps/README.txt for
+ more information). This required ``CONFIG_BUILTIN`` to enable
+ NuttX support for "builtin" applications.
+
+ ``CONFIG_NSH_FILEIOSIZE`` Size of a static I/O buffer used for file access (ignored if there
+ is no file system). Default is 1024.
+
+ ``CONFIG_NSH_STRERROR`` ``strerror(errno)`` makes more readable output but
+ ``strerror()`` is very large and will not be used unless this
+ setting is *y*. This setting depends upon the ``strerror()``
+ having been enabled with ``CONFIG_LIBC_STRERROR``.
+
+ ``CONFIG_NSH_LINELEN`` The maximum length of one command line and of one output line.
+ Default: 80
+
+ ``CONFIG_NSH_DISABLE_SEMICOLON`` By default, you can enter multiple NSH commands on a line
+ with each command separated by a semicolon. You can disable this
+ feature to save a little memory on FLASH challenged platforms.
+ Default: n
+
+ ``CONFIG_NSH_CMDPARMS`` If selected, then the output from commands, from file applications,
+ and from NSH built-in commands can be used as arguments to other
+ commands. The entity to be executed is identified by
+ enclosing the command line in back quotes. For example::
+
+ set FOO `myprogram $BAR`
+
+ will execute the program named ``myprogram`` passing it the
+ value of the environment variable ``BAR``. The value of the
+ environment variable ``FOO`` is then set output of ``myprogram``
+ on ``stdout``. Because this feature commits significant
+ resources, it is disabled by default. The ``CONFIG_NSH_CMDPARMS`` interim
+ output will be retained in a temporary file. Full path to a
+ directory where temporary files can be created is taken from
+ ``CONFIG_LIBC_TMPDIR`` and it defaults to ``/tmp`` if
+ ``CONFIG_LIBC_TMPDIR`` is not set.
+
+ ``CONFIG_NSH_MAXARGUMENTS`` The maximum number of NSH command arguments. Default: 6
+
+ ``CONFIG_NSH_ARGCAT`` Support concatenation of strings with environment variables or
+ command output. For example::
+
+ set FOO XYZ
+ set BAR 123
+ set FOOBAR ABC_${FOO}_${BAR}
+
+ would set the environment variable ``FOO`` to ``XYZ``,
+ ``BAR`` to ``123`` and ``FOOBAR`` to ``ABC_XYZ_123``. If
+ ``CONFIG_NSH_ARGCAT`` is not selected, then a slightly small
+ FLASH footprint results but then also only simple environment
+ variables like ``$FOO`` can be used on the command line.
+
+ ``CONFIG_NSH_VARS`` By default, there are no internal NSH variables. NSH will use OS
+ environment variables for all variable storage. If this option,
+ NSH will also support local NSH variables. These variables are,
+ for the most part, transparent and work just like the OS
+ environment variables. The difference is that when you
+ create new tasks, all of environment variables are
+ inherited by the created tasks. NSH local variables are not.
+ If this option is enabled (and ``CONFIG_DISABLE_ENVIRON`` is not),
+ then a new command called 'export' is enabled. The export
+ command works very must like the set command except that is
+ operates on environment variables. When CONFIG_NSH_VARS
+ is enabled, there are changes in the behavior of certain commands.
+ See table :ref:`_nsh_vars_table`.
+
+ ``CONFIG_NSH_QUOTE`` Enables back-slash quoting of certain characters within the
+ command. This option is useful for the case where an NSH script
+ is used to dynamically generate a new NSH script. In that case,
+ commands must be treated as simple text strings without
+ interpretation of any special characters. Special characters
+ such as ``$``, :literal:`\``, ``"``, and others must be
+ retained intact as part of the test string. This option is
+ currently only available is ``CONFIG_NSH_ARGCAT`` is also
+ selected.
+
+ ``CONFIG_NSH_NESTDEPTH`` The maximum number of nested ``if-then[-else]-fi`` <#conditional>`__
+ sequences that are permissible. Default: 3
+
+ ``CONFIG_NSH_DISABLESCRIPT`` This can be set to *y* to suppress support for scripting.
+ This setting disables the ```sh`` <#cmdsh>`__,
+ ```test`` <#cmdtest>`__, and ```[`` <#cmtest>`__ commands and
+ the ```if-then[-else]-fi`` <#conditional>`__
+ construct. This would only be set on systems where a minimal
+ footprint is a necessity and scripting is not.
+
+ ``CONFIG_NSH_DISABLE_ITEF`` If scripting is enabled, then then this option can be selected
+ to suppress support for ``if-then-else-fi`` sequences in
+ scripts. This would only be set on systems where some minimal
+ scripting is required but ``if-then-else-fi`` is not.
+
+ ``CONFIG_NSH_DISABLE_LOOPS`` If scripting is enabled, then then this option can be selected
+ suppress support ``for while-do-done`` and
+ ``until-do-done`` sequences in scripts. This would only be set
+ on systems where some minimal scripting is required but looping
+ is not.
+
+ ``CONFIG_NSH_DISABLEBG`` This can be set to *y* to suppress support for background
+ commands. This setting disables the ```nice`` <#cmdoverview>`__
+ command prefix and the ```&`` <#cmdoverview>`__ command
+ suffix. This would only be set on systems where a minimal footprint
+ is a necessity and background command execution is not.
+
+ ``CONFIG_NSH_MMCSDMINOR`` If the architecture supports an MMC/SD slot and if the NSH
+ architecture specific logic is present, this option will provide
+ the MMC/SD minor number, i.e., the MMC/SD block driver will be
+ registered as ``/dev/mmcsd``\ *N* where *N* is the minor number.
+ Default is zero.
+
+ ``CONFIG_NSH_ROMFSETC`` Mount a ROMFS file system at ``/etc`` and provide a startup
+ script at ``/etc/init.d/rcS``.
+ The default startup script will mount a FAT FS RAMDISK at
+ ``/tmp`` but the logic is `easily extensible <#startupscript>`__.
+
+ ``CONFIG_NSH_CONSOLE`` If ``CONFIG_NSH_CONSOLE`` is set to *y*, then a serial console
+ front-end is selected.
+
+ Normally, the serial console device is a UART and RS-232
+ interface. However, if ``CONFIG_USBDEV`` is defined,
+ then a USB serial device may, instead, be used if the one of
+ the following are defined:
+
+ - ``CONFIG_PL2303`` and ``CONFIG_PL2303_CONSOLE``.
+ Sets up the Prolifics PL2303 emulation as a console device
+ at ``/dev/console``.
+ - ``CONFIG_CDCACM`` and ``CONFIG_CDCACM_CONSOLE``.
+ Sets up the CDC/ACM serial device as a console device at
+ ``/dev/console``.
+ - ``CONFIG_NSH_USBCONSOLE``. If defined, then an arbitrary USB
+ device may be used to as the NSH console. In this case,
+ ``CONFIG_NSH_USBCONDEV`` must be defined to indicate which
+ USB device to use as the console. The advantage of
+ using a device other that ``/dev/console`` is that
+ normal debug output can then use ``/dev/console`` while NSH
+ uses ``CONFIG_NSH_USBCONDEV``.
+
+ ``CONFIG_NSH_USBCONDEV``. If ``CONFIG_NSH_USBCONSOLE`` is
+ set to 'y', then ``CONFIG_NSH_USBCONDEV`` must also be set to select the USB
+ device used to support the NSH console. This should be set to
+ the quoted name of a readable/write-able USB driver
+ such as: ``CONFIG_NSH_USBCONDEV="/dev/ttyACM0"``.
+
+ If there are more than one USB slots, then a USB device minor
+ number may also need to be provided:
+
+ - ``CONFIG_NSH_UBSDEV_MINOR``: The minor device number of the USB device. Default: 0
+
+ If USB tracing is enabled (``CONFIG_USBDEV_TRACE``), then
+ NSH will initialize USB tracing as requested by the following.
+ Default: Only USB errors are traced.
+
+ - ``CONFIG_NSH_USBDEV_TRACEINIT``: Show initialization events
+ - ``CONFIG_NSH_USBDEV_TRACECLASS``: Show class driver events
+ - ``CONFIG_NSH_USBDEV_TRACETRANSFERS``: Show data transfer events
+ - ``CONFIG_NSH_USBDEV_TRACECONTROLLER``: Show controller events
+ - ``CONFIG_NSH_USBDEV_TRACEINTERRUPTS``: Show interrupt-related events.
+
+ ``CONFIG_NSH_ALTCONDEV`` and If ``CONFIG_NSH_CONSOLE`` is set ``CONFIG_NSH_CONDEV``
+ to *y*, then ``CONFIG_NSH_ALTCONDEV`` may also
+ be selected to enable use of an alternate character device to
+ support the NSH console. If ``CONFIG_NSH_ALTCONDEV`` is
+ selected, then ``CONFIG_NSH_CONDEV`` holds the
+ quoted name of a readable/write-able character
+ driver such as: ``CONFIG_NSH_CONDEV="/dev/ttyS1"``.
+ This is useful, for example, to separate the NSH command line
+ from the system console when the system console is used to provide
+ debug output. Default: ``stdin`` and ``stdout`` (probably
+ "``/dev/console``")
+
+ - **NOTE 1:** When any other device other than
+ ``/dev/console`` is used for a user interface, (1) linefeeds
+ (``\n``) will not be expanded to carriage return / linefeeds
+ (``\r\n``). You will need to configure your terminal
+ program to account for this.
+ And (2) input is not automatically echoed so you
+ will have to turn local echo on.
+ - **NOTE 2:** This option forces the console of all sessions to
+ use NSH_CONDEV. Hence, this option only makes sense for a
+ system that supports only a single session. This option
+ is, in particular, incompatible with Telnet
+ sessions because each Telnet session must use a different
+ console device.
+
+ ``CONFIG_NSH_TELNET`` If ``CONFIG_NSH_TELNET`` is set to *y*, then a TELNET server
+ front-end is selected. When this option is provided, you may log
+ into NuttX remotely using telnet in order to access NSH.
+
+ ``CONFIG_NSH_ARCHINIT`` Set ``CONFIG_NSH_ARCHINIT`` if your board provides architecture
+ specific initialization via the board-specific function
+ ``board_app_initialize()``. This function will be called early in
+ NSH initialization to allow board logic to do such things as
+ configure MMC/SD slots.
+=================================== ==================================
+
+.. _nsh_vars_table:
+
+================== =================================== =============================================
+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
+ ``export``, in which case the env ironment variable of the same name is set to <b>).
+``set`` Causes an error. Lists all NSH variables.
+``unset <a>`` Unsets environment variable <a> Unsets both environment variable *and* NSH variable with and name <a>
+``export <a> <b>`` Causes an error, Unsets NSH variable <a>. Sets environment variable <a> to <b>.
+``export <a>`` Causes an error. Sets environment variable <a> to the value of NSH variable <a> (or "" if the
+ NSH variable has not been set). Unsets NSH local variable <a>.
+``env`` Lists all environment variables Lists all environment variables (*only*)
+================== =================================== =============================================
+
+
+If Telnet is selected for the NSH console, then we must configure the
+resources used by the Telnet daemon and by the Telnet clients.
+
+====================================== ================================
+Configuration Description
+====================================== ================================
+``CONFIG_NSH_TELNETD_PORT`` The telnet daemon will listen on this TCP port number for connections. Default: 23
+``CONFIG_NSH_TELNETD_DAEMONPRIO`` Priority of the Telnet daemon. Default: ``SCHED_PRIORITY_DEFAULT``
+``CONFIG_NSH_TELNETD_DAEMONSTACKSIZE`` Stack size allocated for the Telnet daemon. Default: 2048
+``CONFIG_NSH_TELNETD_CLIENTPRIO`` Priority of the Telnet client. Default: ``SCHED_PRIORITY_DEFAULT``
+``CONFIG_NSH_TELNETD_CLIENTSTACKSIZE`` Stack size allocated for the Telnet client. Default: 2048
+====================================== ================================
+
+One or both of ``CONFIG_NSH_CONSOLE`` and ``CONFIG_NSH_TELNET`` must be
+defined. If ``CONFIG_NSH_TELNET`` is selected, then there some other
+configuration settings that apply:
+
+====================================== ================================
+Configuration Description
+====================================== ================================
+``CONFIG_NET=y`` Of course, networking must be enabled.
+``CONFIG_NSOCKET_DESCRIPTORS`` And, of course, you must allocate some socket descriptors.
+``CONFIG_NET_TCP=y`` TCP/IP support is required for telnet (as well as various other
+ TCP-related configuration settings).
+``CONFIG_NSH_IOBUFFER_SIZE`` Determines the size of the I/O buffer to use for sending/ receiving
+ TELNET commands/responses
+``CONFIG_NSH_DHCPC`` Obtain the IP address via DHCP.
+``CONFIG_NSH_IPADDR`` If ``CONFIG_NSH_DHCPC`` is NOT set, then the static IP address must be
+ provided.
+``CONFIG_NSH_DRIPADDR`` Default router IP address
+``CONFIG_NSH_NETMASK`` Network mask
+``CONFIG_NSH_NOMAC`` Set if your Ethernet hardware has no built-in MAC address. If set, a
+ bogus MAC will be assigned.
+``CONFIG_NSH_MAX_ROUNDTRIP`` This is the maximum round trip for a response to a ICMP ECHO request. It
+ is in units of deciseconds. The default is 20 (2 seconds).
+====================================== ================================
+
+If you use DHCPC, then some special configuration network options are
+required. These include:
+
+============================================== ============================================================
+Configuration Description
+============================================== ============================================================
+``CONFIG_NET=y`` Of course, networking must be enabled.
+``CONFIG_NSOCKET_DESCRIPTORS`` And, of course, you must allocate some socket descriptors.
+``CONFIG_NET_UDP=y`` UDP support is required for DHCP (as well as various other
+ UDP-related configuration settings).
+``CONFIG_NET_BROADCAST=y`` UDP broadcast support is needed.
+``CONFIG_NET_ETH_PKTSIZE=650`` (or larger) Per RFC2131 (p. 9), the DHCP client must be prepared to receive
+ DHCP messages of up to 576 bytes (excluding Ethernet, IP, or
+ UDP headers and FCS). NOTE: Note that the actual MTU setting
+ will depend upon the specific link protocol. Here Ethernet
+ is indicated.
+============================================== ============================================================
+
+If ``CONFIG_NSH_ROMFSETC`` is selected, then the following additional
+configuration setting apply:
+
+============================== ==============================================================
+Configuration Description
+============================== ==============================================================
+``CONFIG_NSH_ARCHROMFS`` May be defined to specify an alternative ROMFS image
+ that can be found at ``boards/<arch>/<chip>/<board>/include/nsh_romfsimg.h``.
+``CONFIG_NSH_ROMFSMOUNTPT`` The default mountpoint for the ROMFS volume is ``"/etc"``,
+ but that can be changed with this setting. This must be a
+ absolute path beginning with '``/``' and enclosed in quotes.
+``CONFIG_NSH_INITSCRIPT`` This is the relative path to the startup script within the
+ mountpoint. The default is ``"init.d/rcS"``. This is a relative
+ path and must not start with '``/``' but must be enclosed in quotes.
+``CONFIG_NSH_ROMFSDEVNO`` This is the minor number of the ROMFS block device.
+ The default is '``0``' corresponding to ``/dev/ram0``.
+``CONFIG_NSH_ROMFSSECTSIZE`` This is the sector size to use with the ROMFS volume. Since the
+ default volume is very small, this defaults to 64 but should
+ be increased if the ROMFS volume were to be become large.
+ Any value selected must be a power of 2.
+============================== ==============================================================
+
+When the default ``rcS`` file used when ``CONFIG_NSH_ROMFSETC`` is
+selected, it will mount a FAT FS under ``/tmp``. The following
+selections describe that FAT FS.
+
+============================== =======================================================
+Configuration Description
+============================== =======================================================
+``CONFIG_NSH_FATDEVNO`` This is the minor number of the FAT FS block device.
+ The default is '``1``' corresponding to ``/dev/ram1``.
+``CONFIG_NSH_FATSECTSIZE`` This is the sector size use with the FAT FS. Default is 512.
+============================== =======================================================
+
diff --git a/doc/components/nsh/customizing.rst b/doc/components/nsh/customizing.rst
new file mode 100644
index 0000000..fcd293b
--- /dev/null
+++ b/doc/components/nsh/customizing.rst
@@ -0,0 +1,213 @@
+*************************
+Customizing the NuttShell
+*************************
+
+**Overview.** The NuttShell (NSH) is a simple shell application that may
+be used with NuttX. It supports a variety of commands and is (very)
+loosely based on the Bash shell and the common utilities used with Bash
+shell programming. The paragraphs in this appendix will focus on
+customizing NSH: Adding new commands, changing the initialization
+sequence, etc.
+
+The NSH Library and NSH Initialization
+**************************************
+
+**Overview.** NSH is implemented as a library that can be found at
+``apps/nshlib``. As a library, it can be custom built into any
+application that follows the NSH initialization sequence described
+below. As an example, the code at ``apps/examples/nsh/nsh_main.c``
+illustrates how to start NSH and the logic there was intended to be
+incorporated into your own custom code. Although code was generated
+simply as an example, in the end most people just use this example code
+as their application ``main()`` function. That initialization performed
+by that example is discussed in the following paragraphs.
+
+NSH Initialization sequence
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The NSH start-up sequence is very simple. As an example, the code at
+``apps/system/nsh/nsh_main.c`` illustrates how to start NSH. It simple
+does the following:
+
+ #. This function calls ``nsh_initialize()`` which initializes the NSH
+ library. ``nsh_initialize()`` is described in more detail below.
+
+ #. If the Telnetconsole is enabled, it calls ``nsh_telnetstart()`` which
+ resides in the NSH library. ``nsh_telnetstart()`` will start the
+ Telnet daemon that will listen for Telnet connections and start
+ remote NSH sessions.
+
+ #. If a local console is enabled (probably on a serial port), then
+ ``nsh_consolemain()`` is called. ``nsh_consolemain()`` also resides
+ in the NSH library. ``nsh_consolemain()`` does not return so that
+ finished the entire NSH initialization sequence.
+
+``nsh_initialize()``
+~~~~~~~~~~~~~~~~~~~~
+
+The NSH initialization function, ``nsh_initialize()``, be found in
+``apps/nshlib/nsh_init.c``. It does only three things:
+
+ #. ``nsh_romfsetc()``: If so configured, it executes an NSH start-up
+ script that can be found at ``/etc/init.d/rcS`` in the target file
+ system. The ``nsh_romfsetc()`` function can be found in
+ ``apps/nshlib/nsh_romfsetc.c``. This function will (1) register a
+ ROMFS file system, then (2) mount the ROMFS file system. ``/etc`` is
+ the default location where a read-only, ROMFS file system is mounted
+ by ``nsh_romfsetc()``.
+
+ The ROMFS image is, itself, just built into the firmware. By default,
+ this ``rcS`` start-up script contains the following logic::
+
+ # Create a RAMDISK and mount it at XXXRDMOUNTPOINTXXX
+
+ mkrd -m XXXMKRDMINORXXX -s XXMKRDSECTORSIZEXXX XXMKRDBLOCKSXXX
+ mkfatfs /dev/ramXXXMKRDMINORXXX
+ mount -t vfat /dev/ramXXXMKRDMINORXXX XXXRDMOUNTPOINTXXX
+
+ Where the ``XXXX*XXXX`` strings get replaced in the template when the
+ ROMFS image is created:
+
+ - ``XXXMKRDMINORXXX`` will become the RAM device minor number.
+ Default: 0
+
+ - ``XXMKRDSECTORSIZEXXX`` will become the RAM device sector size
+
+ - ``XXMKRDBLOCKSXXX`` will become the number of sectors in the
+ device.
+
+ - ``XXXRDMOUNTPOINTXXX`` will become the configured mount point.
+ Default: ``/etc``
+
+ By default, the substituted values would yield an ``rcS`` file like::
+
+ # Create a RAMDISK and mount it at /tmp
+
+ mkrd -m 1 -s 512 1024
+ mkfatfs /dev/ram1
+ mount -t vfat /dev/ram1 /tmp
+
+ This script will, then:
+
+ - Create a RAMDISK of size 512*1024 bytes at ``/dev/ram1``,
+
+ - Format a FAT file system on the RAM disk at ``/dev/ram1``, and
+ then
+
+ - Mount the FAT file system at a configured mountpoint, ``/tmp``.
+
+ This ``rcS`` template file can be found at
+ ``apps/nshlib/rcS.template``. The resulting ROMFS file system can be
+ found in ``apps/nshlib/nsh_romfsimg.h``.
+
+ #. ``board_app_initialize()``: Next any architecture-specific NSH
+ initialization will be performed (if any). For the STM3240G-EVAL,
+ this architecture specific initialization can be found at
+ ``boards/arm/stm32/stm3240g-eval/src/stm32_appinit.c``. This it does
+ things like: (1) Initialize SPI devices, (2) Initialize SDIO, and (3)
+ mount any SD cards that may be inserted.
+
+ #. ``nsh_netinit()``: The ``nsh_netinit()`` function can be found in
+ ``apps/nshlib/nsh_netinit.c``.
+
+NSH Commands
+************
+
+**Overview.** NSH supports a variety of commands as part of the NSH
+program. All of the NSH commands are listed in the NSH documentation
+`above <#cmdoverview>`__. Not all of these commands may be available at
+any time, however. Many commands depend upon certain NuttX configuration
+options. You can enter the help command at the NSH prompt to see the
+commands actual available:
+
+For example, if network support is disabled, then all network-related
+commands will be missing from the list of commands presented by
+'``nsh> help``'. You can see the specific command dependencies in the
+table `above <#cmddependencies>`__.
+
+Adding New NSH Commands
+~~~~~~~~~~~~~~~~~~~~~~~
+
+New commands can be added to the NSH very easily. You simply need to add
+two things:
+
+ #. The implementation of your command, and
+
+ #. A new entry in the NSH command table
+
+**Implementation of Your Command.** For example, if you want to add a
+new a new command called ``mycmd`` to NSH, you would first implement the
+``mycmd`` code in a function with this prototype:
+
+.. code-block:: c
+
+ int cmd_mycmd(FAR struct nsh_vtbl_s *vtbl, int argc, char **argv);
+
+The ``argc`` and ``argv`` are used to pass command line arguments to the
+NSH command. Command line parameters are passed in a very standard way:
+``argv[0]`` will be the name of the command, and ``argv[1]`` through
+``argv[argc-1]`` are the additional arguments provided on the NSH
+command line.
+
+The first parameter, ``vtbl``, is special. This is a pointer to
+session-specific state information. You don't need to know the contents
+of the state information, but you do need to pass this ``vtbl`` argument
+when you interact with the NSH logic. The only use you will need to make
+of the ``vtbl`` argument will be for outputting data to the console. You
+don't use ``printf()`` within NSH commands. Instead you would use:
+
+.. code-block:: c
+
+ void nsh_output(FAR struct nsh_vtbl_s *vtbl, const char *fmt, ...);
+
+So if you only wanted to output "Hello, World!" on the console, then
+your whole command implementation might be:
+
+.. code-block:: c
+
+ int cmd_mycmd(FAR struct nsh_vtbl_s *vtbl, int argc, char **argv)
+ {
+ nsh_output(vtbl, "Hello, World!");
+ return 0;
+ }
+
+The prototype for the new command should be placed in
+``apps/examples/nshlib/nsh.h``.
+
+**Adding You Command to the NSH Command Table**. All of the commands
+support by NSH appear in a single table called:
+
+.. code-block:: c
+
+ const struct cmdmap_s g_cmdmap[]
+
+That table can be found in the file
+``apps/examples/nshlib/nsh_parse.c``. The structure ``cmdmap_s`` is also
+defined in ``apps/nshlib/nsh_parse.c``:
+
+.. code-block:: c
+
+ struct cmdmap_s
+ {
+ const char *cmd; /* Name of the command */
+ cmd_t handler; /* Function that handles the command */
+ uint8_t minargs; /* Minimum number of arguments (including command) */
+ uint8_t maxargs; /* Maximum number of arguments (including command) */
+ const char *usage; /* Usage instructions for 'help' command */
+ };
+
+This structure provides everything that you need to describe your
+command: Its name (``cmd``), the function that handles the command
+(``cmd_mycmd()``), the minimum and maximum number of arguments needed by
+the command, and a string describing the command line arguments. That
+last string is what is printed when enter "``nsh> help``".
+
+So, for you sample command, you would add the following the to the
+``g_cmdmap[]`` table:
+
+.. code-block:: c
+
+ { "mycmd", cmd_mycmd, 1, 1, NULL },
+
+This entry is particularly simply because ``mycmd`` is so simple. Look
+at the other commands in ``g_cmdmap[]`` for more complex examples.
diff --git a/doc/components/nsh/index.rst b/doc/components/nsh/index.rst
new file mode 100644
index 0000000..a1a6044
--- /dev/null
+++ b/doc/components/nsh/index.rst
@@ -0,0 +1,18 @@
+===============
+NuttShell (NSH)
+===============
+
+.. warning::
+ This document is being migrated from previous documentation format,
+ it is a work in progress.
+
+.. toctree::
+ :maxdepth: 2
+
+ nsh.rst
+ commands.rst
+ config.rst
+ customizing.rst
+ builtin.rst
+ installation.rst
+ login.rst
diff --git a/doc/components/nsh/installation.rst b/doc/components/nsh/installation.rst
new file mode 100644
index 0000000..60ed8e6
--- /dev/null
+++ b/doc/components/nsh/installation.rst
@@ -0,0 +1,187 @@
+******************************
+Customizing NSH Initialization
+******************************
+
+**Ways to Customize NSH Initialization**. There are three ways to
+customize the NSH start-up behavior. Here they are presented in order of
+increasing difficulty:
+
+ #. You can extend the initialization logic in
+ ``boards/arm/stm32/stm3240g-eval/src/stm32_appinit.c``. The logic
+ there is called each time that NSH is started and is good place in
+ particular for any device-related initialization.
+
+ #. You replace the sample code at ``apps/examples/nsh/nsh_main.c`` with
+ whatever start-up logic that you want. NSH is a library at
+ ``apps/nshlib``. ``apps.examples/nsh`` is just a tiny, example
+ start-up function (``CONFIG_USER_ENTRYPOINT``\ ()) that that runs
+ immediately and illustrates how to start NSH If you want something
+ else to run immediately then you can write your write your own custom
+ ``CONFIG_USER_ENTRYPOINT``\ () function and then start other tasks
+ from your custom ``CONFIG_USER_ENTRYPOINT``\ ().
+
+ #. NSH also supports a start-up script that executed when NSH first
+ runs. This mechanism has the advantage that the start-up script can
+ contain any NSH commands and so can do a lot of work with very little
+ coding. The disadvantage is that is is considerably more complex to
+ create the start-up script. It is sufficiently complex that is
+ deserves its own paragraph
+
+NuttShell Start up Scripts
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+First of all you should look at `NSH Start-Up Script <#startupscript>`__
+paragraph. Most everything you need to know can be found there. That
+information will be repeated and extended here for completeness.
+
+**NSH Start-Up Script**. NSH supports options to provide a start up
+script for NSH. The start-up script contains any command support by NSH
+(i.e., that you see when you enter 'nsh> help'). In general this
+capability is enabled with ``CONFIG_NSH_ROMFSETC=y``, but has several
+other related configuration options as described with the `NSH-specific
+configuration settings <#nshconfiguration>`__ paragraph. This capability
+also depends on:
+
+ - ``CONFIG_DISABLE_MOUNTPOINT=n``. If mount point support is disabled,
+ then you cannot mount *any* file systems.
+
+ - ``CONFIG_NFILE_DESCRIPTORS > 4``. Of course you have to have file
+ descriptions to use any thing in the file system.
+
+ - ``CONFIG_FS_ROMFS`` enabled. This option enables ROMFS file system
+ support.
+
+**Default Start-Up Behavior**. The implementation that is provided is
+intended to provide great flexibility for the use of Start-Up files.
+This paragraph will discuss the general behavior when all of the
+configuration options are set to the default values.
+
+In this default case, enabling ``CONFIG_NSH_ROMFSETC`` will cause NSH to
+behave as follows at NSH start-up time:
+
+ - NSH will create a read-only RAM disk (a ROM disk), containing a tiny
+ ROMFS file system containing the following::
+
+ `--init.d/
+ `-- rcS
+
+ Where ``rcS`` is the NSH start-up script.
+
+ - NSH will then mount the ROMFS file system at ``/etc``, resulting in::
+
+ |--dev/
+ | `-- ram0
+ `--etc/
+ `--init.d/
+ `-- rcS
+
+ - By default, the contents of ``rcS`` script are::
+
+ # Create a RAMDISK and mount it at /tmp
+
+ mkrd -m 1 -s 512 1024
+ mkfatfs /dev/ram1
+ mount -t vfat /dev/ram1 /tmp
+
+ - NSH will execute the script at ``/etc/init.d/rcS`` at start-up
+ (before the first NSH prompt). After execution of the script, the
+ root FS will look like::
+
+ |--dev/
+ | |-- ram0
+ | `-- ram1
+ |--etc/
+ | `--init.d/
+ | `-- rcS
+ `--tmp/
+
+**Example Configurations**. Here are some configurations that have
+``CONFIG_NSH_ROMFSETC=y`` in the NuttX configuration file. They might
+provide useful examples:
+
+ - ``boards/arm/stm32/hymini-stm32v/nsh2``
+ - ``boards/arm/dm320/ntosd-dm320/nsh``
+ - ``boards/sim/sim/sim/nsh``
+ - ``boards/sim/sim/sim/nsh2``
+ - ``boards/sim/sim/sim/nx``
+ - ``boards/sim/sim/sim/nx11``
+ - ``boards/sim/sim/sim/touchscreen``
+
+In most of these cases, the configuration sets up the *default*
+``/etc/init.d/rcS`` script. The default script is here:
+``apps/nshlib/rcS.template``. (The funny values in the template like
+``XXXMKRDMINORXXX`` get replaced via ``sed`` at build time). This
+default configuration creates a ramdisk and mounts it at ``/tmp`` as
+discussed above.
+
+If that default behavior is not what you want, then you can provide your
+own custom ``rcS`` script by defining ``CONFIG_NSH_ARCHROMFS=y`` in the
+configuration file.
+
+**Modifying the ROMFS Image**. The contents of the ``/etc`` directory
+are retained in the file ``apps/nshlib/nsh_romfsimg.h`` OR, if
+``CONFIG_NSH_ARCHROMFS`` is defined,
+``include/arch/board/nsh_romfsimg.h``. In order to modify the start-up
+behavior, there are three things to study:
+
+ #. **Configuration Options.** The additional ``CONFIG_NSH_ROMFSETC``
+ configuration options discussed with the other `NSH-specific
+ configuration settings <#nshconfiguration>`__.
+
+ #. ``tools/mkromfsimg.sh`` **Script**. The script
+ ``tools/mkromfsimg.sh`` creates ``nsh_romfsimg.h``. It is not
+ automatically executed. If you want to change the configuration
+ settings associated with creating and mounting the ``/tmp``
+ directory, then it will be necessary to re-generate this header file
+ using the ``tools/mkromfsimg.sh`` script.
+
+ The behavior of this script depends upon several things:
+
+ #. The configuration settings then installed configuration.
+
+ #. The ``genromfs`` tool(available from
+ `http://romfs.sourceforge.net <http://romfs.sourceforge.net/>`__)
+ or included within the NuttX buildroot toolchain. There is also a
+ snapshot available in the NuttX tools repository
+ `here <https://bitbucket.org/nuttx/tools/src/master/genromfs-0.5.2.tar.gz>`__.
+
+ #. The ``xxd`` tool that is used to generate the C header files (xxd
+ is a normal part of a complete Linux or Cygwin installation,
+ usually as part of the ``vi`` package).
+
+ #. The file ``apps/nshlib/rcS.template`` (OR, if
+ ``CONFIG_NSH_ARCHROMFS`` is defined
+ ``include/arch/board/rcs.template``.
+
+ #. ``rcS.template``. The file ``apps/nshlib/rcS.template`` contains the
+ general form of the ``rcS`` file; configured values are plugged into
+ this template file to produce the final ``rcS`` file.
+
+ To generate a custom ``rcS`` file a copy of ``rcS.template`` needs to
+ be placed at ``tools/`` and changed according to the desired start-up
+ behaviour. Running ``tools/mkromfsimg.h`` creates ``nsh_romfsimg.h``
+ which needs to be copied to ``apps/nshlib`` OR if
+ ``CONFIG_NSH_ARCHROMFS`` is defined to
+ ``boards/<arch>/<chip>/<board>/include``.
+
+``rcS.template``. The default ``rcS.template``,
+``apps/nshlib/rcS.template``, generates the standard, default
+``apps/nshlib/nsh_romfsimg.h`` file.
+
+If ``CONFIG_NSH_ARCHROMFS`` is defined in the NuttX configuration file,
+then a custom, board-specific ``nsh_romfsimg.h`` file residing in
+``boards/<arch>/<chip>/<board>/include``\ will be used. NOTE when the OS
+is configured, ``include/arch/board`` will be linked to
+``boards/<arch>/<chip>/<board>/include``.
+
+All of the startup-behavior is contained in ``rcS.template``. The role
+of ``mkromfsimg.sh`` script is to (1) apply the specific configuration
+settings to ``rcS.template`` to create the final ``rcS``, and (2) to
+generate the header file ``nsh_romfsimg.h`` containing the ROMFS file
+system image. To do this, ``mkromfsimg.sh`` uses two tools that must be
+installed in your system:
+
+ #. The ``genromfs`` tool that is used to generate the ROMFS file system
+ image.
+
+ #. The ``xxd`` tool that is used to create the C header file.
diff --git a/doc/components/nsh/login.rst b/doc/components/nsh/login.rst
new file mode 100644
index 0000000..76b2390
--- /dev/null
+++ b/doc/components/nsh/login.rst
@@ -0,0 +1,261 @@
+***********
+Shell Login
+***********
+
+Enabling Shell Logins
+*********************
+
+NuttShell sessions can be protected by requiring that the user supply
+username and password credentials at the beginning of the session.
+Logins can be enabled for standard USB or serial consoles with::
+
+ CONFIG_NSH_CONSOLE_LOGIN=y
+
+Logins for Telnet sessions can be enabled separately with::
+
+ CONFIG_NSH_TELNET_LOGIN=y
+
+Logins can be enabled for either or both session types. On a successful
+login, the user will have access to the NSH session::
+
+ login: admin
+ password:
+ User Logged-in!
+
+ NuttShell (NSH)
+ nsh>
+
+After each failed login attempt, a delay can be set up. The purpose of
+this delay is to discourage attempts to crack the password by brute
+force. That delay is configured with::
+
+ CONFIG_NSH_LOGIN_FAILDELAY=0
+
+This setting provides the login failure delay in units of milliseconds.
+The system will pause this amount of time after each failed login
+attempt. After a certain number of failed login attempts, the session
+will be closed. That number is controlled by::
+
+ CONFIG_NSH_LOGIN_FAILCOUNT=3
+
+Verification of Credentials
+***************************
+
+There are three ways that NSH can be configured to verify user
+credentials at login time:
+
+ #. The simplest implementation simply uses fixed login credentials and
+ is selected with::
+
+ CONFIG_NSH_LOGIN_FIXED=y
+
+ The fixed login credentials are selected via::
+
+ CONFIG_NSH_LOGIN_USERNAME=admin
+ CONFIG_NSH_LOGIN_PASSWORD="Administrator"
+
+ This is not very flexible since there can be only one user and the
+ password is fixed in the FLASH image. This option is also not very
+ secure because a malicious user could get the password by just
+ looking at the ``.text`` stings in the flash image.
+
+ #. NSH can also be configured to defer the entire user credential
+ verification to platform-specific logic with this setting::
+
+ CONFIG_NSH_LOGIN_PLATFORM=y
+
+ In this case, NSH will call a platform-specific function to perform
+ the verification of user credentials. The platform-specific logic
+ must provide a function with the following prototype:
+
+ .. code-block:: c
+
+ int platform_user_verify(FAR const char *username, FAR const char *password);
+
+ which is prototyped an described in ``apps/include/nsh.h`` and which
+ may be included like:
+
+ .. code-block:: c
+
+ #include <apps/nsh.h>
+
+ An appropriate place to implement this function might be in the
+ directory ``apps/platform/<board>``.
+
+ #. A final option is to use a password file contained encrypted password
+ information. This final option is selected with the following and
+ described in more detail in the following paragraph::
+
+ CONFIG_NSH_LOGIN_PASSWD=y
+
+Password Files
+**************
+
+NuttX can also be configured to support a password file, by default at
+``/etc/passwd``. This option enables support for a password file::
+
+ CONFIG_NSH_LOGIN_PASSWD=y
+
+This options requires that you have selected ``CONFIG_FSUTILS_PASSWD=y``
+to enable the access methods of ``apps/fsutils/passwd``::
+
+ CONFIG_FSUTILS_PASSWD=y
+
+And this determines the location of the password file in a mounted
+volume::
+
+ CONFIG_FSUTILS_PASSWD_PATH="/etc/passwd"
+
+``/etc/passwd`` is a *standard* location, but you will need to locate
+the password where ever you have a mounted volume.
+
+The password file can be a fixed list of users in a ROMFS file system or
+a modifiable list maintained in a file in some writable file system. If
+the password file lies in a read-only file system like ROMFS, then you
+should also indicate that the password file is read-only.
+
+ CONFIG_FSUTILS_PASSWD_READONLY=y
+
+If the password file is writable, then additional NSH commands will be
+enabled to modify the password file: ```useradd`` <#cmduseradd>`__,
+```userdel`` <#cmduserdel>`__, and ```passwd`` <#cmdpasswd>`__. If you
+do not wish you have these commands available, then they should be
+specifically disabled.
+
+The password file logic requires a few additional settings:
+
+ #. The size of dynamically allocated and freed buffer that is used for
+ file access::
+
+ CONFIG_FSUTILS_PASSWD_IOBUFFER_SIZE=512
+
+ #. And the 128-bit encryption key. The password file currently uses the
+ Tiny Encryption Algorithm (TEA), but could be extended to use
+ something more powerful.
+
+ CONFIG_FSUTILS_PASSWD_KEY1=0x12345678
+ CONFIG_FSUTILS_PASSWD_KEY2=0x9abcdef0
+ CONFIG_FSUTILS_PASSWD_KEY3=0x12345678
+ CONFIG_FSUTILS_PASSWD_KEY4=0x9abcdef0
+
+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
+symbolic information, that would be a difficult job since the TEA KEY is
+binary data and not distinguishable from other binary data in the FLASH
+image.
+
+If the password file is enabled (``CONFIG_NSH_LOGIN_PASSWD=y``), then
+the fixed user credentials will not be used for the NSH session login.
+Instead, the password file will be consulted to verify the user
+credentials.
+
+Creating a Password File for a ROMFS File System
+************************************************
+
+What we want to accomplish is a ROMFS file system, mounted at ``/etc``
+and containing the password file, ``passwd`` like::
+
+ NuttShell (NSH)
+ nsh> ls -Rl /etc
+ /etc:
+ dr-xr-xr-x 0 .
+ dr-xr-xr-x 0 init.d/
+ -r--r--r-- 39 passwd
+ /etc/init.d:
+ dr-xr-xr-x 0 ..
+ -r--r--r-- 110 rcS
+ nsh>
+
+Where ``/etc/init.d/rcS`` is the start-up script; ``/etc/passwd`` is a
+the password file. Note that here we assume that you are already using a
+start-up script. We can then piggyback the passwd file into the ``/etc``
+file system already mounted for the NSH start up file as described above
+`above <#custinit>`__.
+
+I use the sim/nsh configuration to create a new password file, but other
+configurations could also be used. That configuration already supports a
+ROMFS file system, passwords, and login prompts. First, I make these
+changes to that configuration.
+
+ #. Disable logins:
+
+ .. code-block:: diff
+
+ - CONFIG_NSH_CONSOLE_LOGIN=y
+ + # CONFIG_NSH_CONSOLE_LOGIN is not set
+ # CONFIG_NSH_TELNET_LOGIN is not set
+
+ #. Move the password file to a write-able file system:
+
+ .. code-block:: diff
+
+ - CONFIG_FSUTILS_PASSWD_PATH="/etc/passwd"
+ + CONFIG_FSUTILS_PASSWD_PATH="/tmp/passwd"
+
+ #. Make the password file modifiable
+
+ .. code-block:: diff
+
+ - CONFIG_FSUTILS_PASSWD_READONLY=y
+ # CONFIG_FSUTILS_PASSWD_READONLY is not set
+
+Now rebuild the simulation. No login should be required to enter the
+shell and you should find the ```useradd`` <#cmduseradd>`__,
+```userdel`` <#cmduserdel>`__, and ```passwd`` <#cmdpasswd>`__ commands
+available in the help summary, provided that they are enabled. Make
+certain that the ``useradd`` command is not disabled::
+
+ # CONFIG_NSH_DISABLE_USERADD is not set
+
+Use the NSH ```useradd`` <#cmduseradd>`__ command to add new uses with
+new user passwords like::
+
+ nsh> useradd <username> <password>
+
+Do this as many times as you would like. Each time that you do this a
+new entry with an encrypted password will be added to the ``passwd``
+file at ``/tmp/passwd``. You can see the content of the password file
+like::
+
+ nsh> cat /tmp/passwd
+
+When you are finished, you can simply copy the ``/tmp/passwd`` content
+from the ``cat`` command and paste it into an editor. Make sure to
+remove any carriage returns that may have ended up on the file if you
+are using Windows.
+
+Then create/re-create the ``nsh_romfsimg.h`` file as described below.
+
+ #. The content on the ``nsh_romfsimg.h`` header file is generated from a
+ template directory structure. Create the directory structure::
+
+ mkdir etc
+ mkdir etc/init.d
+
+ And copy your existing startup script into ``etc/init.c`` as ``rcS``.
+
+ #. Save your new password file in the ``etc/`` directory as ``passwd``.
+
+ #. Create the new ROMFS image::
+
+ genromfs -f romfs_img -d etc -V MyVolName
+
+ #. Convert the ROMFS image to a C header file::
+
+ xxd -i romfs_img >nsh_romfsimg.h
+
+ #. Edit ``nsh_romfsimg.h``: Mark both data definitions as ``const`` so
+ that the data will be stored in FLASH.
+
+ #. Edit nsh_romfsimg.h, mark both data definitions as ``const`` so that
+ that will be stored in FLASH.
+
+There is a good example of how to do this in the NSH simulation
+configuration at
+`boards/sim/sim/sim/configs/nsh <https://bitbucket.org/nuttx/nuttx/src/master/boards/sim/sim/sim/configs/nsh/>`__.
+The ROMFS support files are provided at
+`boards/sim/include <https://bitbucket.org/nuttx/nuttx/boards/src/master/sim/sim/sim/include/>`__
+and the
+`README.txt <https://bitbucket.org/nuttx/nuttx/src/master/boards/sim/sim/sim/include/README.txt>`__
+file at the location provides detailed information about creating and
+modifying the ROMFS file system.
diff --git a/doc/components/nsh/nsh.rst b/doc/components/nsh/nsh.rst
new file mode 100644
index 0000000..8984192
--- /dev/null
+++ b/doc/components/nsh/nsh.rst
@@ -0,0 +1,361 @@
+.. include:: /substitutions.rst
+
+********
+Overview
+********
+
+**The NSH Library**. The ``apps/nshlib`` sub-directory contains the
+NuttShell (NSH) library. This library can easily to linked to
+produce a NSH application (See as an example
+``apps/examples/nsh``). The NSH Library provides a simple shell
+application for NuttX.
+
+Console/NSH Front End
+*********************
+
+**NSH Consoles**. Using settings in the configuration file, NSH may be
+configured to use (1) the serial stdin/out, (2) a USB serial
+device (such as CDC/ACM), or (3) a telnet connection as the
+console. Or, perhaps even all at once since or BOTH. An indefinite
+number of telnet sessions are supported.
+
+**Start-Up prompt**. When NSH is started, you will see the a welcome
+message such the following on the selected console:
+
+.. code-block::
+
+ NuttShell (NSH)
+ nsh>
+
+The greeting may also include NuttX versioning information if you
+are using a versioned copy of NuttX. ``nsh>`` is the NSH prompt
+and indicates that you may enter a command from the console.
+
+**USB console startup**. When using a USB console, the start-up
+sequence differs a little: In this case, you are required to press
+*ENTER* three times. Then NSH prompt will appear as described
+above. This is required for the following reasons:
+
+ #. This assures that the USB connection is stable. The USB
+ connection may be made, broken, and re-established a few times
+ if the USB cable is not yet fully seated. Waiting for *ENTER*
+ to be pressed three times assures that the connection is
+ stable.
+ #. The establishment of the connection is two step process: First,
+ the USB serial connection is made with the host PC. Then the
+ application that uses the serial interface is started on the
+ host. When the serial connection is established on the host,
+ the host operating system may send several *AT* modem commands
+ to the host depending upon how the host serial port is
+ configured. By waiting for *ENTER* to be pressed three
+ consecutive times, all of these modem commands will go to the
+ bit-bucket and will not be interpreted as NSH command input.
+ #. Similarly, in the second step when the applications is started,
+ there may be additional *AT* modem commands sent out the serial
+ port. Most serial terminal programs will do this unless they
+ are specifically configured to suppress the modem command
+ output. Waiting for the *ENTER* input eliminates the invalid
+ command errors from both (2) and (3).
+ #. Finally, if NSH did not wait for some positive indication that
+ the serial terminal program is up and running, then the output
+ of the NSH greeting and initial NSH prompt would be lost.
+
+**Extended Command Line Editing**. By default, NuttX uses a simple
+command line editor that allows command entry after the ``nsh>``
+and supports only the *backspace* key for editing. However, a more
+complete command line editor can be selected by setting
+``CONFIG_NSH_CLE=y`` in the NuttX configuration file. When that
+option is selected, the following EMACS-like line editing commands
+are supported:
+
+===================== ================================================
+Key Binding Editor Action
+===================== ================================================
+``^A`` Move cursor to start of the line
+``^B`` Move left one character
+``^D`` or *Del* Delete a single character at the cursor position
+``^E`` Move cursor to end of current line
+``^F`` Move right one character
+``^H`` or *Backspace* Delete character, left (backspace)
+``^K`` Delete to the end of the line
+``^U`` Delete the entire line
+===================== ================================================
+
+Command Overview
+****************
+
+**Simple, Re-directed, and Background Commands**. The NuttShell
+(NSH) is a simple shell application. NSH supports the following
+commands forms:
+
+=============================== ======================================
+Simple command ``<cmd>``
+Command with re-directed output ``<cmd> > <file> <cmd> >> <file>``
+Background command ``<cmd> &``
+Re-directed background command ``<cmd> > <file> & <cmd> >> <file> &``
+=============================== ======================================
+
+Where:
+
+ * ``<cmd>`` is any one of the simple commands listed later.
+ * ``<file>`` is the full or relative path to any writable object in the file system name space (file or character driver). Such objects will be referred to simply as files throughout this document.
+
+``nice`` **'d Background Commands**. NSH executes at the
+mid-priority (128). Backgrounded commands can be made to execute
+at higher or lower priorities using ``nice``::
+
+ [nice [-d <niceness>>]] <cmd> [> <file>|>> <file>] [&]
+
+Where ``<niceness>`` is any value between -20 and 19 where lower
+(more negative values) correspond to higher priorities. The
+default niceness is 10.
+
+**Multiple commands per line**. NSH will accept multiple commands
+per command line with each command separated with the semi-colon
+character (;).
+
+**Optional Syntax Extensions** Because these features commit
+significant resources, they are disabled by default.
+
+ - ``CONFIG_NSH_CMDPARMS``: If selected, then the output from
+ commands, from file applications, and from NSH built-in
+ commands can be used as arguments to other commands. The entity
+ to be executed is identified by enclosing the command line in
+ back quotes. For example,
+
+ .. code-block:: bash
+
+ set FOO myprogram $BAR
+
+ Will execute the program named ``myprogram`` passing it the
+ value of the environment variable ``BAR``. The value of the
+ environment variable ``FOO`` is then set output of
+ ``myprogram`` on ``stdout``.
+
+ - ``CONFIG_NSH_ARGCAT``: Support concatenation of strings
+ with environment variables or command output. For example:
+
+ .. code-block:: bash
+
+ set FOO XYZ
+ set BAR 123
+ set FOOBAR ABC_${FOO}_${BAR}
+
+ would set the environment variable ``FOO`` to ``XYZ``, ``BAR``
+ to ``123`` and ``FOOBAR`` to ``ABC_XYZ_123``. If
+ ``CONFIG_NSH_ARGCAT`` is not selected, then a slightly smaller
+ FLASH footprint results but then also only simple environment
+ variables like ``$FOO`` can be used on the command line.
+
+ - ``CONFIG_NSH_QUOTE``: Enables back-slash quoting of certain
+ characters within the command. This option is useful for the
+ case where an NSH script is used to dynamically generate a new
+ NSH script. In that case, commands must be treated as simple
+ text strings without interpretation of any special characters.
+ Special characters such as ``$``, :literal:`\``, ``"``, and
+ others must be retained intact as part of the test string. This
+ option is currently only available is ``CONFIG_NSH_ARGCAT`` is
+ also selected.
+
+Conditional Command Execution
+*****************************
+
+An ``if-then[-else]-fi`` construct is also supported in order to
+support conditional execution of commands. This works from the
+command line but is primarily intended for use within NSH scripts
+(see the ```sh`` <#cmdsh>`__ command). The syntax is as follows:
+
+.. code-block:: bash
+
+ if [!] <cmd>
+ then
+ [sequence of <cmd>]
+ else
+ [sequence of <cmd>]
+ fi
+
+Where ``<cmd>`` is a `simple command <#cmdoverview>`__. The
+command success value of zero is treated true; a non-zero command
+failure value is treated false. The ```test`` <#cmdtest>`__
+command is frequently used for comparisons.
+
+Looping
+*******
+
+**Looping Constructs**. ``while-do-done`` and ``until-do-done``
+looping constructs are also supported. These work from the command
+line but are primarily intended for use within NSH scripts (see
+the ```sh`` <#cmdsh>`__ command).
+
+ - ``while-do-done``: Execute ``[sequence of <cmd>]`` as long
+ as ``<cmd>`` has an exit status of zero. The syntax is as
+ follows:
+
+ .. code-block:: bash
+
+ while <cmd>
+ do
+ [sequence of <cmd>]
+ done
+
+ - ``until-do-done``: Execute ``[sequence of <cmd>]`` as long
+ as ``<cmd>`` has a non-zero exit status. The syntax is as
+ follows:
+
+ .. code-block::
+
+ until <cmd>
+ do
+ [sequence of <cmd>]
+ done
+
+Where ``<cmd>`` is a `simple command <#cmdoverview>`__. The
+command success value of zero is treated true; a non-zero command
+failure value is treated false. The ```test`` <#cmdtest>`__
+command is frequently used for comparisons.
+
+**The** ``break`` **Command**. A ``break`` command is also supported.
+The ``break`` command is only meaningful within the body of the a
+``while`` or ``until`` loop, between the ``do`` and ``done`` tokens.
+If the ``break`` command is executed within the body of a loop,
+the loop will immediately terminate and execution will continue
+with the next command immediately following the ``done`` token.
+
+Built-In Variables
+******************
+
+====== ====================================================
+``$?`` The result of the last simple command execution. |br|
+ On backgrounded commands, this variable holds only |br|
+ the result of spawning the background command.
+====== ====================================================
+
+Current Working Directory
+*************************
+
+``cd`` **and** ``pwd``. All path arguments to commands may be
+either an absolute path or a path relative to the current working
+directory. The current working directory is set using the
+``cd`` command and can be queried either by using the
+``pwd`` command or by using the ``echo $PWD`` command.
+
+Environment Variables
+*********************
+
+========== ================================================
+``PATH`` The default path in the file systems to look |br|
+ for executable, binary programs working directory
+``PWD`` The current working directory
+``OLDPWD`` The previous working directory
+========== ================================================
+
+NSH Start-Up Script
+*******************
+
+**NSH Start-Up Script**. NSH supports options to provide a start
+up script for NSH. In general this capability is enabled with
+``CONFIG_NSH_ROMFSETC``, but has several other related
+configuration options as described with the `NSH-specific
+configuration settings <#nshconfiguration>`__. This capability
+also depends on:
+
+ - ``CONFIG_DISABLE_MOUNTPOINT`` not set
+ - ``CONFIG_NFILE_DESCRIPTORS`` > 4
+ - ``CONFIG_FS_ROMFS`` enabled
+
+**Default Start-Up Behavior**. The implementation that is provided
+is intended to provide great flexibility for the use of Start-Up
+files. This paragraph will discuss the general behavior when all
+of the configuration options are set to the default values.
+
+In this default case, enabling ``CONFIG_NSH_ROMFSETC`` will cause
+NSH to behave as follows at NSH startup time:
+
+ - NSH will create a read-only RAM disk (a ROM disk), containing a
+ tiny ROMFS file system containing the following::
+
+ `--init.d/
+ `-- rcS
+
+ Where rcS is the NSH start-up script.
+
+ - NSH will then mount the ROMFS file system at ``/etc``,
+ resulting in::
+
+ |--dev/
+ | `-- ram0
+ `--etc/
+ `--init.d/
+ `-- rcS
+
+ - By default, the contents of rcS script are::
+
+ # Create a RAMDISK and mount it at XXXRDMOUNTPOINTXXX
+
+ mkrd -m 1 -s 512 1024
+ mkfatfs /dev/ram1
+ mount -t vfat /dev/ram1 /tmp
+
+ - NSH will execute the script at ``/etc/init.d/rcS`` at start-up
+ (before the first NSH prompt). After execution of the script,
+ the root FS will look like::
+
+ |--dev/
+ | |-- ram0
+ | `-- ram1
+ |--etc/
+ | `--init.d/
+ | `-- rcS
+ `--tmp/
+
+**Modifying the ROMFS Image**. The contents of the ``/etc``
+directory are retained in the file ``apps/nshlib/nsh_romfsimg.h``
+OR, if ``CONFIG_NSH_ARCHROMFS`` is defined,
+``include/arch/board/rcs.template``). In order to modify the
+start-up behavior, there are three things to study:
+
+ #. **Configuration Options.** The additional
+ ``CONFIG_NSH_ROMFSETC`` configuration options discussed with
+ the other `NSH-specific configuration
+ settings <#nshconfiguration>`__.
+ #. `tools/mkromfsimg.sh`` **Script**. The script
+ ``tools/mkromfsimg.sh`` creates ``nsh_romfsimg.h``. It is not
+ automatically executed. If you want to change the configuration
+ settings associated with creating and mounting the ``/tmp``
+ directory, then it will be necessary to re-generate this header
+ file using the ``tools/mkromfsimg.sh`` script.
+
+ The behavior of this script depends upon three things:
+
+ - The configuration settings then installed configuration.
+ - The ``genromfs`` tool (available from
+ http://romfs.sourceforge.net).
+ - The file ``apps/nshlib/rcS.template`` (OR, if
+ ``CONFIG_NSH_ARCHROMFS`` is defined
+ ``include/arch/board/rcs.template``.
+
+ #. ``rcS.template``: The file ``apps/nshlib/rcS.template``
+ contains the general form of the ``rcS`` file; configured
+ values are plugged into this template file to produce the final
+ ``rcS`` file.
+
+.. note::
+ ``apps/nshlib/rcS.template`` generates the standard,
+ default ``nsh_romfsimg.h`` file. If ``CONFIG_NSH_ARCHROMFS`` is
+ defined in the NuttX configuration file, then a custom,
+ board-specific ``nsh_romfsimg.h`` file residing in the
+ ``boards/<arch>/<chip>/<board>/include`` directory will be used.
+ NOTE when the OS is configured, ``include/arch/board`` will be
+ linked to ``boards/<arch>/<chip>/<board>/include``.
+
+All of the startup-behavior is contained in ``rcS.template``. The
+role of ``mkromfsimg.sh`` is to (1) apply the specific
+configuration settings to ``rcS.template`` to create the final
+``rcS``, and (2) to generate the header file ``nsh_romfsimg.h``
+containing the ROMFS file system image.
+
+**Further Information**. See the section on `Customizing the
+NuttShell <#customizingnsh>`__ for additional, more detailed
+information about the NSH start-up script and how to modify it.
+
+
diff --git a/doc/components/nxflat.rst b/doc/components/nxflat.rst
new file mode 100644
index 0000000..0a494e9
--- /dev/null
+++ b/doc/components/nxflat.rst
@@ -0,0 +1,469 @@
+======
+NXFLAT
+======
+
+Overview
+========
+
+Functionality
+-------------
+
+NXFLAT is a customized and simplified version of binary format
+implemented a few years ago called
+`XFLAT <http://xflat.sourceforge.net/>`__ With the NXFLAT binary format
+you will be able to do the following:
+
+ - Place separately linked programs in a file system, and
+ - Execute those programs by dynamically linking them to the base NuttX
+ code.
+
+This allows you to extend the NuttX base code after it has been written
+into FLASH. One motivation for implementing NXFLAT is support clean CGI
+under an HTTPD server.
+
+This feature is especially attractive when combined with the NuttX ROMFS
+support: ROMFS allows you to execute programs in place (XIP) in flash
+without copying anything other than the .data section to RAM. In fact,
+the initial NXFLAT release only worked on ROMFS. Later extensions also
+support execution NXFLAT binaries from an SRAM copy as well.
+
+This NuttX feature includes:
+
+ - A dynamic loader that is built into the NuttX core (See
+ `GIT <https://bitbucket.org/nuttx/nuttx/src/master/binfmt/>`__).
+ - Minor changes to RTOS to support position independent code, and
+ - A linker to bind ELF binaries to produce the NXFLAT binary format
+ (See GIT).
+
+Background
+----------
+
+NXFLAT is derived from `XFLAT <http://xflat.sourceforge.net/>`__. XFLAT
+is a toolchain add that provides full shared library and XIP executable
+support for processors that have no Memory Management Unit
+(MMU:sup:`1`). NXFLAT is greatly simplified for the deeply embedded
+environment targeted by Nuttx:
+
+ - NXFLAT does not support shared libraries, because
+ - NXFLAT does not support *exportation* of symbol values from a module
+
+Rather, the NXFLAT module only *imports* symbol values. In the NXFLAT
+model, the (PIC:sup:`2`) NXFLAT module resides in a FLASH file system
+and when it is loaded at run time, it is dynamically linked only to the
+(non-PIC) base NuttX code: The base NuttX *exports* a symbol table; the
+NXFLAT module *imports* those symbol value to dynamically bind the
+module to the base code.
+
+Limitations
+-----------
+
+ - **ROMFS (or RAM mapping) Only**:
+ The current NXFLAT release will work only with either (1) NXFLAT
+ executable modules residing on a ROMFS file system, or (2) executables
+ residing on other file systems provided that CONFIG_FS_RAMMAP is
+ defined. This limitation is because the loader depends on the capability
+ to mmap() the code segment. See the NuttX User Guide for further information.
+
+ NUTTX does not provide any general kind of file mapping capability.
+ In fact, true file mapping is only possible with MCUs that provide an MMU1.
+ Without an MMU, file system may support eXecution In Place (XIP) to mimic
+ file mapping. Only the ROMFS file system supports that kind of XIP execution
+ need by NXFLAT.
+
+ It is also possible to simulate file mapping by allocating memory, copying
+ the NXFLAT binary file into memory, and executing from the copy of the
+ executable file in RAM. That capability can be enabled with the CONFIG_FS_RAMMAP
+ configuration option. With that option enabled, NXFLAT will work that kind
+ of file system but will require copying of all NXFLAT executables to RAM.
+
+ - **GCC/ARM/Cortex-M3/4 Only**:
+ At present, the NXFLAT toolchain is only available for ARM and Cortex-M3/4 (thumb2) targets.
+
+ - **Read-Only Data in RAM**:
+ With older GCC compilers (at least up to 4.3.3), read-only data must
+ reside in RAM. In code generated by GCC, all data references are
+ indexed by the PIC2 base register (that is usually R10 or sl for the
+ ARM processors). The includes read-only data (.rodata). Embedded
+ firmware developers normally like to keep .rodata in FLASH with
+ the code sections. But because all data is referenced with the
+ PIC base register, all of that data must lie in RAM. A NXFLAT
+ change to work around this is under investigation3.
+
+ Newer GCC compilers (at least from 4.6.3), read-only data is
+ no long GOT-relative, but is now accessed PC-relative.
+ With PC relative addressing, read-only data must reside in the I-Space.
+
+ - **Globally Scoped Function Function Pointers**:
+ If a function pointer is taken to a statically defined function,
+ then (at least for ARM) GCC will generate a relocation that NXFLAT
+ cannot handle. The workaround is make all such functions global in
+ scope. A fix would involve a change to the GCC compiler as described
+ in Appendix B.
+
+ - **Special Handling of Callbacks**:
+ Callbacks through function pointers must be avoided or, when
+ then cannot be avoided, handled very specially. The reason
+ for this is that the PIC module requires setting of a special
+ value in a PIC register. If the callback does not set the PIC
+ register, then the called back function will fail because it
+ will be unable to correctly access data memory. Special logic
+ is in place to handle some NuttX callbacks: Signal callbacks
+ and watchdog timer callbacks. But other callbacks (like those
+ used with qsort() must be avoided in an NXFLAT module.
+
+Supported Processors
+--------------------
+
+As mentioned `above <#limitations>`__, the NXFLAT toolchain is only
+available for ARM and Cortex-M3 (thumb2) targets. Furthermore, NXFLAT
+has only been tested on the Eagle-100 LMS6918 Cortex-M3 board.
+
+Development Status
+------------------
+
+The initial release of NXFLAT was made in NuttX version 0.4.9. Testing
+is limited to the tests found under ``apps/examples/nxflat`` in the
+source tree. Some known problems exist (see the
+`TODO <https://bitbucket.org/nuttx/nuttx/src/master/TODO>`__ list). As
+such, NXFLAT is currently in an early alpha phase.
+
+NXFLAT Toolchain
+================
+
+Building the NXFLAT Toolchain
+-----------------------------
+
+In order to use NXFLAT, you must use special NXFLAT tools to create the
+binary module in FLASH. To do this, you will need to download the
+buildroot package and build it on your Linux or Cygwin machine. The
+buildroot can be downloaded from
+`Bitbucket.org <https://bitbucket.org/nuttx/buildroot/downloads>`__. You
+will need version 0.1.7 or later.
+
+Here are some general build instructions:
+
+- You must have already configured Nuttx in ``<some-dir>/nuttx``
+- Download the buildroot package ``buildroot-0.x.y`` into
+ ``<some-dir>``
+- Unpack ``<some-dir>/buildroot-0.x.y.tar.gz`` using a command like ``tar zxf buildroot-0.x.y``. This will result in a new directory like ``<some-dir>/buildroot-0.x.y``
+- Move this into position:
+ ``mv <some-dir>/buildroot-0.x.y``\ <some-dir>/buildroot
+- ``cd``\ <some-dir>/buildroot
+- Copy a configuration file into the top buildroot directory:
+ ``cp boards/abc-defconfig-x.y.z .config``.
+- Enable building of the NXFLAT tools by ``make menuconfig``. Select to
+ build the NXFLAT toolchain with GCC (you can also select omit
+ building GCC with and only build the NXFLAT toolchain for use with
+ your own GCC toolchain).
+- Make the toolchain: ``make``. When the make completes, the tool
+ binaries will be available under
+ ``<some-dir>/buildroot/build_abc/staging_dir/bin``
+
+mknxflat
+--------
+
+``mknxflat`` is used to build a *thunk* file. See below
+for usage::
+
+ Usage: mknxflat [options] <bfd-filename>
+
+ Where options are one or more of the following. Note
+ that a space is always required between the option and
+ any following arguments.
+
+ -d Use dynamic symbol table. [symtab]
+ -f <cmd-filename>
+ Take next commands from <cmd-filename> [cmd-line]
+ -o <out-filename>
+ Output to [stdout]
+ -v Verbose output [no output]
+ -w Import weakly declared functions, i.e., weakly
+ declared functions are expected to be provided at
+ load-time [not imported]
+
+ldnxflat
+--------
+
+``ldnxflat`` is use to link your object files along with the *thunk*
+file generated by ``mknxflat`` to produce the NXFLAT
+binary module. See below for usage::
+
+ Usage: ldnxflat [options] <bfd-filename>
+
+ Where options are one or more of the following. Note
+ that a space is always required between the option and
+ any following arguments.
+
+ -d Use dynamic symbol table [Default: symtab]
+ -e <entry-point>
+ Entry point to module [Default: _start]
+ -o <out-filename>
+ Output to <out-filename> [Default: <bfd-filename>.nxf]
+ -s <stack-size>
+ Set stack size to <stack-size> [Default: 4096]
+ -v Verbose output. If -v is applied twice, additional
+ debug output is enabled [Default: no verbose output].
+
+mksymtab
+--------
+
+There is a small helper program available in ``nuttx/tools`` call
+``mksymtab``. ``mksymtab`` can be sued to generate symbol tables for the
+NuttX base code that would be usable by the typical NXFLAT application.
+``mksymtab`` builds symbol tables from common-separated value (CSV)
+files. In particular, the CSV files:
+
+ #. ``nuttx/syscall/syscall.csv`` that describes the NuttX RTOS
+ interface, and
+ #. ``nuttx/libc/libc.csv`` that describes the NuttX C library interface.
+ #. ``nuttx/libc/math.cvs`` that descirbes any math library.
+
+::
+
+ USAGE: ./mksymtab <cvs-file> <symtab-file>
+
+ Where:
+
+ <cvs-file> : The path to the input CSV file
+ <symtab-file>: The path to the output symbol table file
+ -d : Enable debug output
+
+For example,
+
+::
+
+ cd nuttx/tools
+ cat ../syscall/syscall.csv ../libc/libc.csv | sort >tmp.csv
+ ./mksymtab.exe tmp.csv tmp.c
+
+Making an NXFLAT module
+-----------------------
+
+Below is a snippet from an NXFLAT make file (simplified from NuttX
+`Hello,
+World! <https://bitbucket.org/nuttx/apps/src/master/apps/examples/nxflat/tests/hello/Makefile>`__
+example).
+
+* Target 1:
+
+ .. code-block:: makefile
+
+ hello.r1: hello.o
+ abc-nuttx-elf-ld -r -d -warn-common -o $@ $^
+
+* Target 2:
+
+ .. code-block:: makefile
+
+ hello-thunk.S: hello.r1
+ mknxflat -o $@ $^
+
+* Target 3:
+
+ .. code-block:: makefile
+
+ hello.r2: hello-thunk.S
+ abc-nuttx-elf-ld -r -d -warn-common -T binfmt/libnxflat/gnu-nxflat-gotoff.ld -no-check-sections -o $@ hello.o hello-thunk.o
+
+* Target 4:
+
+ .. code-block:: makefile
+
+ hello: hello.r2
+ ldnxflat -e main -s 2048 -o $@ $^
+
+**Target 1**. This target links all of the module's object files
+together into one relocatable object. Two relocatable objects will be
+generated; this is the first one (hence, the suffic ``.r1``). In this
+"Hello, World!" case, there is only a single object file, ``hello.o``,
+that is linked to produce the ``hello.r1`` object.
+
+When the module's object files are compiled, some special compiler
+CFLAGS must be provided. First, the option ``-fpic`` is required to tell
+the compiler to generate position independent code (other GCC options,
+like ``-fno-jump-tables`` might also be desirable). For ARM compilers,
+two additional compilation options are required: ``-msingle-pic-base``
+and ``-mpic-register=r10``.
+
+**Target 2**. Given the ``hello.r1`` relocatable object, this target
+will invoke ```mknxflat`` <#mknxflat>`__ to make the *thunk* file,
+``hello-thunk.S``. This *thunk* file contains all of the information
+needed to create the imported function list.
+
+**Target 3** This target is similar to **Target 1**. In this case, it
+will link together the module's object files (only ``hello.o`` here)
+along with the assembled *thunk* file, ``hello-thunk.o`` to create the
+second relocatable object, ``hello.r2``. The linker script,
+``gnu-nxflat-gotoff.ld`` is required at this point to correctly position
+the sections. This linker script produces two segments: An *I-Space*
+(Instruction Space) segment containing mostly ``.text`` and a *D-Space*
+(Data Space) segment containing ``.got``, ``.data``, and ``.bss``
+sections. The I-Space section must be origined at address 0 (so that the
+segment's addresses are really offsets into the I-Space segment) and the
+D-Space section must also be origined at address 0 (so that segment's
+addresses are really offsets into the I-Space segment). The option
+``-no-check-sections`` is required to prevent the linker from failing
+because these segments overlap.
+
+**NOTE:** There are two linker scripts located at ``binfmt/libnxflat/``.
+
+ #. ``binfmt/libnxflat/gnu-nxflat-gotoff.ld``. Older versions of GCC
+ (at least up to GCC 4.3.3), use GOT-relative addressing to access RO
+ data. In that case, read-only data (.rodata) must reside in D-Space
+ and this linker script should be used.
+ #. ``binfmt/libnxflat/gnu-nxflat-pcrel.ld``. Newer versions of GCC
+ (at least as of GCC 4.6.3), use PC-relative addressing to access RO
+ data. In that case, read-only data (.rodata) must reside in I-Space
+ and this linker script should be used.
+
+**Target 4**. Finally, this target will use the ``hello.r2`` relocatable
+object to create the final, NXFLAT module ``hello`` by executing
+``ldnxflat``.
+
+Binary Loader APIs
+==================
+
+**Relevant Header Files:**
+
+ - The interface to the binary loader is described in the header file
+ ```include/nuttx/binfmt/binfmt.h``.
+ A brief summary of the APIs prototyped in that header file are listed
+ below.
+ - NXFLAT APIs needed to register NXFLAT as a binary loader appear in
+ the header file
+ ``include/nuttx/binfmt/nxflat.h``.
+ - The format of an NXFLAT object itself is described in the header
+ file:
+ ``include/nuttx/binfmt/nxflat.h``.
+
+**binfmt Registration** These first interfaces are used only by a binary
+loader module, such as NXFLAT itself. NXFLAT (or any future binary
+loader) calls ``register_binfmt()`` to incorporate itself into the
+system. In this way, the binary loader logic is dynamically extensible
+to support any kind of loader. Normal application code should not be
+concerned with these interfaces.
+
+.. c:function:: int register_binfmt(FAR struct binfmt_s *binfmt)
+
+ Register a loader for a binary format
+
+ :return: This is a NuttX internal function so it follows the
+ convention that 0 (``OK``) is returned on success and a
+ negated errno is returned on failure.
+
+.. c:function:: int unregister_binfmt(FAR struct binfmt_s *binfmt)
+
+ Register a loader for a binary format
+
+ :return: This is a NuttX internal function so it follows the
+ convention that 0 (``OK``) is returned on success and a
+ negated errno is returned on failure.
+
+**Binary Loader Interfaces**. The remaining APIs are called by user
+applications to maintain modules in the file system.
+
+.. c:function:: int load_module(FAR struct binary_s *bin)
+
+ Load a module into memory, bind it to an exported symbol take,
+ and prep the module for execution.
+
+ :return: This is a NuttX internal function so it follows the
+ convention that 0 (``OK``) is returned on success and a
+ negated errno is returned on failure.
+
+.. c:function:: int unload_module(FAR struct binary_s *bin)
+
+ Unload a (non-executing) module from memory. If the module
+ has been started (via :c:func:`exec_module`), calling this
+ will be fatal.
+
+ :return: This is a NuttX internal function so it follows the
+ convention that 0 (``OK``) is returned on success and a
+ negated errno is returned on failure.
+
+.. c:function:: int exec_module(FAR const struct binary_s *bin)
+
+ Execute a module that has been loaded into memory by
+ :c:func:`load_module`.
+
+ :return: This is a NuttX internal function so it follows the
+ convention that 0 (``OK``) is returned on success and a
+ negated errno is returned on failure.
+
+Appendix A: No GOT Operation
+============================
+
+When GCC generate position independent code, new code sections will
+appear in your programs. One of these is the GOT (Global Offset Table)
+and, in ELF environments, another is the PLT (Procedure Lookup Table.
+For example, if your C code generated (ARM) assembly language like this
+without PIC:
+
+.. code-block:: c-objdump
+
+ ldr r1, .L0 /* Fetch the offset to 'x' */
+ ldr r0, [r10, r1] /* Load the value of 'x' with PIC offset */
+ /* ... */
+ .L0: .word x /* Offset to 'x' */
+
+Then when PIC is enabled (say with the -fpic compiler option), it will
+generate code like this:
+
+.. code-block:: c-objdump
+
+ ldr r1, .L0 /* Fetch the offset to the GOT entry */
+ ldr r1, [r10, r1] /* Fetch the (relocated) address of 'x' from the GOT */
+ ldr r0, [r1, #0] /* Fetch the value of 'x' */
+ /* ... */
+ .L1 .word x(GOT) /* Offset to entry in the GOT */
+
+See
+`reference <http://xflat.sourceforge.net/NoMMUSharedLibs.html#shlibsgot>`__
+
+Notice that the generates an extra level of indirection through the GOT.
+This indirection is not needed by NXFLAT and only adds more RAM usage
+and execution time.
+
+NXFLAT (like `XFLAT <http://xflat.sourceforge.net/>`__) can work even
+better without the GOT. Patches against older version of GCC exist to
+eliminate the GOT indirections. Several are available
+`here <http://xflat.cvs.sourceforge.net/viewvc/xflat/xflat/gcc/>`__ if
+you are inspired to port them to a new GCC version.
+
+Appendix B: PIC Text Workaround
+===============================
+
+There is a problem with the memory model in GCC that prevents it from
+being used as you need to use it in the NXFLAT context. The problem is
+that GCC PIC model assumes that the executable lies in a flat,
+contiguous (virtual) address space like::
+
+ Virtual
+ .text
+ .got
+ .data
+ .bss
+
+It assumes that the PIC base register (usually r10 for ARM) points to
+the base of ``.text`` so that any address in ``.text``, ``.got``,
+``.data``, ``.bss`` can be found with an offset from the same base
+address. But that is not the memory arrangement that we need in the XIP
+embedded environment. We need two memory regions, one in FLASH
+containing shared code and on per task in RAM containing task-specific
+data::
+
+ Flash RAM
+ .text .got
+ .data
+ .bss
+
+The PIC base register needs to point to the base of the ``.got`` and
+only addresses in the ``.got``, ``.data``, and ``.bss`` sections can be
+accessed as an offset from the PIC base register. See also this `XFLAT
+discussion <http://xflat.cvs.sourceforge.net/viewvc/*checkout*/xflat/xflat/gcc/README?revision=1.1.1.1>`__.
+
+Patches against older version of GCC exist to correct this GCC behavior.
+Several are available
+`here <http://xflat.cvs.sourceforge.net/viewvc/xflat/xflat/gcc/>`__ if
+you are inspired to port them to a new GCC version.
+
diff --git a/Documentation/NXOrganization.gif b/doc/components/nxgraphics/NXOrganization.gif
similarity index 100%
rename from Documentation/NXOrganization.gif
rename to doc/components/nxgraphics/NXOrganization.gif
diff --git a/Documentation/NuttXScreenShot.jpg b/doc/components/nxgraphics/NuttXScreenShot.jpg
similarity index 100%
rename from Documentation/NuttXScreenShot.jpg
rename to doc/components/nxgraphics/NuttXScreenShot.jpg
diff --git a/doc/components/nxgraphics/appendix.rst b/doc/components/nxgraphics/appendix.rst
new file mode 100644
index 0000000..4d51083
--- /dev/null
+++ b/doc/components/nxgraphics/appendix.rst
@@ -0,0 +1,657 @@
+========
+Appendix
+========
+
+``graphics/`` Directory Structure
+=================================
+
+The graphics capability consist both of components internal to the RTOS
+and of user-callable interfaces. In the NuttX kernel mode build there
+are some components of the graphics subsystem are callable in user mode
+and other components that are internal to the RTOS. The directory
+``nuttx/graphics`` contains only those components that are internal to
+the RTOS. User callable functions must be part of a library that can be
+linked against user applications. This user callable interfaces are
+provided in sub-directories under ``nuttx/libnx``.
+
+``libnx/nx``
+ Common callable interfaces that are, logically, part of both nxmu and
+ nxsu.
+``graphics/nxglib`` and ``libnx/nxglib``
+ The NuttX tiny graphics library. The directory contains generic
+ utilities support operations on primitive graphics objects and logic
+ to rasterize directly into a framebuffer or through an LCD driver
+ interface. It has no concept of windows (other than the one,
+ framebuffer or LCD window).
+``graphics/nxbe``
+ This is the *back-end* of a tiny windowing system. It can be used
+ with either of two front-ends to complete a windowing system (see
+ ``nxmu`` and ``nxsu`` below). It contains most of the important
+ window management logic: clipping, window controls, window drawing,
+ etc.
+``graphics/nxmu`` and ``libnx/nxmu``
+ This is the NX multi user *front end*. When combined with the generic
+ *back-end* (``nxbe``), it implements a multi-threaded, multi-user
+ windowing system. The files in this directory present the window APIs
+ described in ``include/nuttx/nx/nx.h``. The multi-user front end
+ includes a graphics server that executes on its own thread; multiple
+ graphics clients then communicate with the server via a POSIX message
+ queue to serialize window operations from many threads.
+``libnx/nxfonts``
+ This is where the NXFONTS implementation resides. This is a
+ relatively low-level set of charset set/glyph management APIs. See
+ ``include/nuttx/nx/nxfonts.h``.
+``libnx/nxtk``
+ This is where the NXTOOLKIT implementation resides. This toolkit is
+ built on top of NX and works with the multi-user NX front-end. See
+ ``include/nuttx/nx/nxtk.h``.
+``apps/graphics/NxWidgets``
+ The `NxWidgets <NxWidgets.html>`__ code is provided as a separate
+ package provided in the ``apps/`` repository.
+``graphics/nxterm``
+ The NxTerm driver is built on top of NX and works with the multi-user
+ NX front-end. See ``include/nuttx/nx/nxterm.h``.
+
+NX Configuration Options
+========================
+
+General Configuration Settings
+------------------------------
+
+``CONFIG_NX``
+ Enables overall support for graphics library and NX
+``CONFIG_NX_RAMBACKED``
+ Enables RAM backed window support. If this option is selected, then
+ windows may be optionally created with a RAM framebuffer backing up
+ the window content. Rending into the window will result in rending
+ into the backup framebuffer, then updating the physical display from
+ the framebuffer.
+
+ The advantage of this option is that the application that manages
+ window will no longer receive redraw() callbacks. Those calls
+ normally occur, for example, when a window "above" moves exposing a
+ portion of the window below. If this option is selected, then the
+ system will redraw the exposed portion of the window from the backup
+ framebuffer without intervention of the window applications. This
+ greatly reduces the complexity of the application and performance of
+ the window at the expense of increased memory usage.
+
+ An exception is the case when the window is resized to a wider and/or
+ taller size. In that case, the redraw callback will till occur. It is
+ necessary in that case to provide new graphic content for the
+ extended window area.
+
+ Redraw requests in other cases are also suppressed: Changes to window
+ position, size, etc.
+
+NXGL Configuration Settings
+---------------------------
+
+``CONFIG_NX_NPLANES``:
+ Some YUV color formats requires support for multiple planes, one for
+ each color component. Unless you have such special hardware, this
+ value should be undefined or set to 1.
+``CONFIG_NX_DISABLE_1BPP``, ``CONFIG_NX_DISABLE_2BPP``, ``CONFIG_NX_DISABLE_4BPP``, ``CONFIG_NX_DISABLE_8BPP`` ``CONFIG_NX_DISABLE_16BPP``, ``CONFIG_NX_DISABLE_24BPP``, and ``CONFIG_NX_DISABLE_32BPP``:
+ NX supports a variety of pixel depths. You can save some memory by
+ disabling support for unused color depths.
+``CONFIG_NX_PACKEDMSFIRST``:
+ If a pixel depth of less than 8-bits is used, then NX needs to know
+ if the pixels pack from the MS to LS or from LS to MS
+``CONFIG_NX_LCDDRIVER``:
+ By default, NX builds to use a framebuffer driver (see
+ ``include/nuttx/video/fb.h``). If this option is defined, NX will
+ build to use an LCD driver (see ``include/nuttx/lcd/lcd.h``).
+``CONFIG_NX_ANTIALIASING``:
+ Enable support for anti-aliasing when rendering lines as various
+ orientations. This option is only available for use with frame buffer
+ drivers and only with 16-, 24-, or 32-bit RGB color formats.
+
+Configuration Settings
+----------------------
+
+``CONFIG_NX_XYINPUT``:
+ Build in support for an X/Y input such as a mouse or a touscreen.
+``CONFIG_NX_KBD``:
+ Build in support of keypad/keyboard input.
+``CONFIG_NX_WRITEONLY``:
+ Define if the underlying graphics device does not support read
+ operations. Automatically defined if ``CONFIG_NX_LCDDRIVER`` and
+ ``CONFIG_LCD_NOGETRUN`` are defined.
+
+NX Server Configuration Settings
+--------------------------------
+
+``CONFIG_NX_BLOCKING``
+ Open the client message queues in blocking mode. In this case,
+ ``nx_eventhandler()`` will not return until a message is received and
+ processed.
+``CONFIG_NX_MXSERVERMSGS`` and ``CONFIG_NX_MXCLIENTMSGS``
+ Specifies the maximum number of messages that can fit in the message
+ queues. No additional resources are allocated, but this can be set to
+ prevent flooding of the client or server with too many messages
+ (``CONFIG_PREALLOC_MQ_MSGS`` controls how many messages are
+ pre-allocated).
+
+NXTK Configuration Settings
+---------------------------
+
+``CONFIG_NXTK_BORDERWIDTH``:
+ Specifies the width of the border (in pixels) used with framed
+ windows. The default is 4.
+``CONFIG_NXTK_BORDERCOLOR1``, ``CONFIG_NXTK_BORDERCOLOR2``, and ``CONFIG_NXTK_BORDERCOLOR3``:
+ Specify the colors of the border used with framed windows.
+``CONFIG_NXTK_BORDERCOLOR2``
+ The shadow side color and so is normally darker.
+``CONFIG_NXTK_BORDERCOLOR3``
+ The shiny side color and so is normally brighter. The default is
+ medium, dark, and light grey, respectively
+``CONFIG_NXTK_AUTORAISE``:
+ If set, a window will be raised to the top if the mouse position is
+ over a visible portion of the window. Default: A mouse button must be
+ clicked over a visible portion of the window.
+
+NXFONTS Configuration Settings
+------------------------------
+
+``CONFIG_NXFONTS_CHARBITS``:
+ The number of bits in the character set. Current options are only 7
+ and 8. The default is 7.
+``CONFIG_NXFONT_SANS17X22``:
+ This option enables support for a tiny, 17x22 san serif font (font
+ ``ID FONTID_SANS17X22`` == 14).
+``CONFIG_NXFONT_SANS20X26``:
+ This option enables support for a tiny, 20x26 san serif font (font
+ ``ID FONTID_SANS20X26`` == 15).
+``CONFIG_NXFONT_SANS23X27``:
+ This option enables support for a tiny, 23x27 san serif font (font
+ ``ID FONTID_SANS23X27`` == 1).
+``CONFIG_NXFONT_SANS22X29``:
+ This option enables support for a small, 22x29 san serif font (font
+ ``ID FONTID_SANS22X29`` == 2).
+``CONFIG_NXFONT_SANS28X37``:
+ This option enables support for a medium, 28x37 san serif font (font
+ ``ID FONTID_SANS28X37`` == 3).
+``CONFIG_NXFONT_SANS39X48``:
+ This option enables support for a large, 39x48 san serif font (font
+ ``ID FONTID_SANS39X48`` == 4).
+``CONFIG_NXFONT_SANS17X23B``:
+ This option enables support for a tiny, 17x23 san serif bold font
+ (font ``ID FONTID_SANS17X23B`` == 16).
+``CONFIG_NXFONT_SANS20X27B``:
+ This option enables support for a tiny, 20x27 san serif bold font
+ (font ``ID FONTID_SANS20X27B`` == 17).
+``CONFIG_NXFONT_SANS22X29B``:
+ This option enables support for a small, 22x29 san serif bold font
+ (font ID ``FONTID_SANS22X29B`` == 5).
+``CONFIG_NXFONT_SANS28X37B``:
+ This option enables support for a medium, 28x37 san serif bold font
+ (font ID ``FONTID_SANS28X37B`` == 6).
+``CONFIG_NXFONT_SANS40X49B``:
+ This option enables support for a large, 40x49 san serif bold font
+ (font ID ``FONTID_SANS40X49B`` == 7).
+``CONFIG_NXFONT_SERIF22X29``:
+ This option enables support for a small, 22x29 font (with serifs)
+ (font ID ``FONTID_SERIF22X29`` == 8).
+``CONFIG_NXFONT_SERIF29X37``:
+ This option enables support for a medium, 29x37 font (with serifs)
+ (font ID ``FONTID_SERIF29X37`` == 9).
+``CONFIG_NXFONT_SERIF38X48``:
+ This option enables support for a large, 38x48 font (with serifs)
+ (font ID ``FONTID_SERIF38X48`` == 10).
+``CONFIG_NXFONT_SERIF22X28B``:
+ This option enables support for a small, 27x38 bold font (with
+ serifs) (font ID ``FONTID_SERIF22X28B`` == 11).
+``CONFIG_NXFONT_SERIF27X38B``:
+ This option enables support for a medium, 27x38 bold font (with
+ serifs) (font ID ``FONTID_SERIF27X38B`` == 12).
+``CONFIG_NXFONT_SERIF38X49B``:
+ This option enables support for a large, 38x49 bold font (with
+ serifs) (font ID ``FONTID_SERIF38X49B`` == 13).
+
+NxTerm Configuration Settings
+-----------------------------
+
+General NxTerm settings.
+
... 21838 lines suppressed ...
[incubator-nuttx] 12/17: add basic support for multiple versions
Posted by bt...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
btashton pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
commit d9be1dffab66256cd198f804a1c7188d6a4c0d00
Author: Matias N <ma...@protobits.dev>
AuthorDate: Sat Aug 15 23:10:44 2020 -0300
add basic support for multiple versions
---
Documentation/_static/custom.css | 7 +++++++
Documentation/_templates/layout.html | 30 ++++++++++++++++++++++++++++++
Documentation/conf.py | 7 +++++++
3 files changed, 44 insertions(+)
diff --git a/Documentation/_static/custom.css b/Documentation/_static/custom.css
index 058bf37..6f470e3 100644
--- a/Documentation/_static/custom.css
+++ b/Documentation/_static/custom.css
@@ -23,3 +23,10 @@
overflow: visible !important;
}
}
+
+
+.wy-nav-side
+{
+ padding-bottom: 0em !important;
+}
+
diff --git a/Documentation/_templates/layout.html b/Documentation/_templates/layout.html
new file mode 100644
index 0000000..43342ff
--- /dev/null
+++ b/Documentation/_templates/layout.html
@@ -0,0 +1,30 @@
+{% extends "!layout.html" %}
+{% block sidebartitle %}
+ {% if logo and theme_logo_only %}
+ <a href="{{ pathto(master_doc) }}">
+ {% else %}
+ <a href="{{ pathto(master_doc) }}" class="icon icon-home"> {{ project }}
+ {% endif %}
+
+ {% if logo %}
+ {# Not strictly valid HTML, but it's the only way to display/scale
+ it properly, without weird scripting or heaps of work
+ #}
+ <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="{{ _('Logo') }}"/>
+ {% endif %}
+ </a>
+
+ <!-- this version selector is quite ugly, should be probably replaced by something
+ more modern -->
+
+ <div class="version-selector">
+ <select>
+ {% for nuttx_version in nuttx_versions %}
+ <option value="{{ nuttx_version }}" {% if nuttx_version == version %}selected="selected"{% endif %}>{{ nuttx_version }}</option>
+ {% endfor %}
+ </select>
+ </div>
+
+ {% include "searchbox.html" %}
+{% endblock %}
+
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 243fbbf..ab828e6 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -51,6 +51,13 @@ templates_path = ['_templates']
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+# list of documentation versions to offer (besides latest)
+
+html_context = dict()
+html_context['nuttx_versions'] = ['latest']
+
+# TODO: append other options using releases detected from git (or maybe just
+# a few hand-selected ones, or maybe just a "stable" option)
# -- Options for HTML output -------------------------------------------------
[incubator-nuttx] 09/17: fix link
Posted by bt...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
btashton pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
commit b3a269b957bb87988beae76e293290ff203829ae
Author: Matias N <ma...@protobits.dev>
AuthorDate: Sat Aug 15 18:18:57 2020 -0300
fix link
---
Documentation/components/nsh/config.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/components/nsh/config.rst b/Documentation/components/nsh/config.rst
index e3e74d8..563f460 100644
--- a/Documentation/components/nsh/config.rst
+++ b/Documentation/components/nsh/config.rst
@@ -249,7 +249,7 @@ Configuration Description
command works very must like the set command except that is
operates on environment variables. When CONFIG_NSH_VARS
is enabled, there are changes in the behavior of certain commands.
- See table :ref:`_nsh_vars_table`.
+ See following :ref:`table <nsh_vars_table>`.
``CONFIG_NSH_QUOTE`` Enables back-slash quoting of certain characters within the
command. This option is useful for the case where an NSH script
[incubator-nuttx] 08/17: convert TODOs to actual TODO banner and
improve general presentation of different sections
Posted by bt...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
btashton pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
commit 4a38a15332f80840315b15161e5f000ad5858373
Author: Matias N <ma...@protobits.dev>
AuthorDate: Sat Aug 15 18:10:25 2020 -0300
convert TODOs to actual TODO banner and improve general presentation of different sections
---
Documentation/applications/index.rst | 8 +-
Documentation/boards/index.rst | 14 +-
Documentation/components/index.rst | 3 +-
Documentation/components/nsh/index.rst | 7 +-
Documentation/components/socketcan.rst | 8 +-
Documentation/conf.py | 5 +-
Documentation/contributing/workflow.rst | 43 +++-
Documentation/guides/index.rst | 5 +-
Documentation/index.rst | 19 +-
Documentation/introduction/about.rst | 14 +-
Documentation/introduction/detailed_support.rst | 9 +-
.../introduction/development_environments.rst | 2 +
Documentation/introduction/index.rst | 2 +-
Documentation/introduction/licensing.rst | 8 +-
Documentation/introduction/supported_platforms.rst | 262 ++++++++++-----------
Documentation/introduction/trademarks.rst | 2 +
Documentation/quickstart/index.rst | 11 +-
Documentation/reference/index.rst | 8 +-
18 files changed, 248 insertions(+), 182 deletions(-)
diff --git a/Documentation/applications/index.rst b/Documentation/applications/index.rst
index 489d45d..a718161 100644
--- a/Documentation/applications/index.rst
+++ b/Documentation/applications/index.rst
@@ -1,6 +1,10 @@
+.. todo::
+ Applications included in ``apps`` repo should be documented here. This should also include information
+ on how to create a given application.
+
Applications
============
-.. note:: This is to be used to describe how applications work in NuttX as well as to ducment
- existing ones.
+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.
+
diff --git a/Documentation/boards/index.rst b/Documentation/boards/index.rst
index 6e96a41..fa73bd1 100644
--- a/Documentation/boards/index.rst
+++ b/Documentation/boards/index.rst
@@ -1,8 +1,14 @@
-Supported Boards
-================
-
-.. note::
+.. todo::
Include a full list of supported boards, organized by architecture / family / vendor.
Each board should have its own entry, a photo, brief hardware specifications, features
supported (currently working in NuttX), how to flash, special toolchains required, etc.
+ This will involve migrating most of the content existing currently in board README files
+ to RST documents here.
+
+Supported Boards
+================
+
+NuttX supports a large number of boards (see :doc:`here </introduction/supported_platforms>`).
+At the moment, the documentation available is in the form of README files inside each subdirectory
+of ``boards`` directory of main NuttX repository.
diff --git a/Documentation/components/index.rst b/Documentation/components/index.rst
index b2ba8e6..57ac542 100644
--- a/Documentation/components/index.rst
+++ b/Documentation/components/index.rst
@@ -1,8 +1,7 @@
OS Components
=============
-.. note::
- TODO: add brief intro
+NuttX is very feature-rich RTOS and is thus composed of various different subsystems. The following sections explain how each of these main RTOS components work and can be used. For detailed documentation on the specific API used in this case, you can head to the :doc:`reference <../reference/index>`.
.. toctree::
:maxdepth: 2
diff --git a/Documentation/components/nsh/index.rst b/Documentation/components/nsh/index.rst
index a1a6044..7f7a4ef 100644
--- a/Documentation/components/nsh/index.rst
+++ b/Documentation/components/nsh/index.rst
@@ -2,12 +2,13 @@
NuttShell (NSH)
===============
-.. warning::
- This document is being migrated from previous documentation format,
- it is a work in progress.
+The NuttShell is a very complete shell system to be used in NuttX, similar to bash and other similar options. It supports a rich set of included commands, scripting and the ability to run your own applications as "builtin" (part of the same NuttX binary). NSH is implemented as an application where most of the functionality is part of the library called `nshlib`.
+
+As such, NSH is completely optional and can be disabled so that NuttX directly starts a given task instead of the main ``nsh`` application.
.. toctree::
:maxdepth: 2
+ :caption: Contents
nsh.rst
commands.rst
diff --git a/Documentation/components/socketcan.rst b/Documentation/components/socketcan.rst
index f8323a2..9c3b71b 100644
--- a/Documentation/components/socketcan.rst
+++ b/Documentation/components/socketcan.rst
@@ -2,18 +2,18 @@
SocketCAN Device Drivers
========================
- - **``include/nuttx/net/netdev.h``**. All structures and APIs
+ - ``include/nuttx/net/netdev.h``. All structures and APIs
needed to work with drivers are provided in this header file.
The structure struct net_driver_s defines the interface and is
passed to the network via netdev_register().
- - **``include/nuttx/can.h``**. CAN & CAN FD frame data
+ - ``include/nuttx/can.h``. CAN & CAN FD frame data
structures.
- - **``int netdev_register(FAR struct net_driver_s *dev, enum net_lltype_e lltype)'``**.
+ - ``int netdev_register(FAR struct net_driver_s *dev, enum net_lltype_e lltype)'``.
Each driver registers itself by calling netdev_register().
- - **``Include/nuttx/net/can.h``**. contains lookup tables for CAN
+ - ``Include/nuttx/net/can.h``. contains lookup tables for CAN
dlc to CAN FD len sizes named
.. code-block:: c
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 054f25a..243fbbf 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -31,9 +31,12 @@ version = release = 'latest'
extensions = [
"sphinx_rtd_theme",
"recommonmark",
- 'sphinx.ext.autosectionlabel'
+ 'sphinx.ext.autosectionlabel',
+ 'sphinx.ext.todo'
]
+todo_include_todos = True
+
autosectionlabel_prefix_document = True
# do not set Python as primary domain for code blocks
diff --git a/Documentation/contributing/workflow.rst b/Documentation/contributing/workflow.rst
index 60579ff..c90d16a 100644
--- a/Documentation/contributing/workflow.rst
+++ b/Documentation/contributing/workflow.rst
@@ -1,7 +1,42 @@
+.. todo:: update when workflow is settled
+
Development Workflow
====================
-.. note::
- This document should describe how a proper contribution should be made, and what is the
- NuttX development workflow (PR based, CI checks). Could be divided into sections oriented
- towards new users as well as others intending to participate in NuttX as commiter/PMC.
+NuttX development workflow is based around contributions submitted in the form of GitHub Pull Requests (PR). This is true both for external contributors and NuttX maintainers, as direct pushes to the repository are not allowed as a general rule. Once submitted, your PR
+will be reviewed and checked using Continuous Integration (CI) practices.
+
+You should be aware of the following:
+
+ - All contributions must adhere to the :doc:`Coding Standard <coding_style>`. You can check your files using ``nxstyle``
+ or complete patchsets using ``checkpath`` script (both found in ``tools`` subdirectory of NuttX repository). This check will also run
+ automatically during CI to ensure conformance.
+
+ Note that not all existing files in the repository are already adapted to conform to the standard as this is an ongoing effort. Thus,
+ if you're submitting a patch to an existing file you may have to make the file conform to the standard, even if you are not reponsible
+ for those standard violations.
+
+ It is also appreciated that you separate any styling fixes in a separate commit from the functional changes so that these are more
+ easily readable during review.
+
+ - Before starting work on any given non trivial contribution, do subscribe to the mailing list and ask about your idea to avoid
+ wasted effort by going the wrong-route.
+
+ - If you are submitting an original contribution (you wrote the code yourself from scratch) it will have to be submitted under
+ the terms of the Apache 2.0 License using the corresponding :ref:`header <contributing/coding_style:Appendix>`.
+
+ Note that if you are working as an employee in a company, usually copyright belongs to the company and thus this means the company
+ will have to authorize this and submit the appropriate license agreements.
+
+ - If you are submitting third-party code:
+
+ - Code from actively developed projects is not accepted to be included in NuttX (i.e.: creating a fork). It is expected that
+ changes required in third-party code for NuttX support are to be implemented in these projects. As an intermediate solution,
+ it is acceptable to include a patch to be applied to this third-party code, which will be pulled during built.
+
+ - If this is from an inactive project, it may be considered for inclusion in NuttX, provided that licensing terms allow to do so
+ and it is deemed of sufficient value to be included, considering that this code will have to be maintained in NuttX afterwards.
+
+ Note that it is undesireable to included non Apache 2.0 Licensed code inside the repository, even if the license itself allows it
+ (for example BSD License).
+
diff --git a/Documentation/guides/index.rst b/Documentation/guides/index.rst
index 0744df5..c592db1 100644
--- a/Documentation/guides/index.rst
+++ b/Documentation/guides/index.rst
@@ -1,8 +1,9 @@
+.. todo::
+ Create "tutorial" type documentation for specific subjects not to be covered in more general terms.
+
Guides
======
-.. note:: This would contain "tutorial" type documentation for specific subjects not to be covered in more general terms.
-
.. toctree::
nfs.rst
usbtrace.rst
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 4b04390..65dd9ad 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -1,28 +1,31 @@
+.. note::
+ The present documentation is a recent addition to NuttX and was migrated from previous
+ documentation content. For this reason, it is possible you may find broken links or
+ formatting errors. You can help contribute fixes or improvements to this documentation
+ by following these :doc:`instructions <contributing/documentation>`.
+
+.. tip::
+ You can find the old documentation `here <https://cwiki.apache.org/confluence/display/NUTTX/Documentation>`_.
+
===================
NuttX Documentation
===================
NuttX is a real-time operating system (RTOS) with an emphasis on standards compliance and small footprint. Scalable from 8-bit to 32-bit microcontroller environments, the primary governing standards in NuttX are Posix and ANSI standards. Additional standard APIs from Unix and other common RTOS’s (such as VxWorks) are adopted for functionality not available under these standards, or for functionality that is not appropriate for deeply-embedded environments (such as fork()).
-.. warning::
- These pages are meant to be an experiment in replacing the `Apache NuttX Documentation <https://cwiki.apache.org/confluence/display/NUTTX/Nuttx>`_
- with something easier to navigate, extend, and modify.
- This is a work in progress, some formatting issues may still be present and are being worked on. Also, some links may be broken. Please
- refer to :doc:`contributing documentation<contributing/documentation>` to propose fixes/improvements.
-
Last Updated: |today|
.. toctree::
- :caption: Contents:
+ :caption: Table of Contents
:maxdepth: 2
Home <self>
introduction/index.rst
quickstart/index.rst
- reference/index.rst
components/index.rst
applications/index.rst
boards/index.rst
+ reference/index.rst
guides/index.rst
releases/index.rst
contributing/index.rst
diff --git a/Documentation/introduction/about.rst b/Documentation/introduction/about.rst
index 2ac3235..0bfa233 100644
--- a/Documentation/introduction/about.rst
+++ b/Documentation/introduction/about.rst
@@ -2,7 +2,10 @@
About NuttX
===========
-**Goals**. NuttX is a real time embedded operating system (RTOS). Its goals are:
+Goals
+=====
+
+NuttX is a real time embedded operating system (RTOS). Its goals are:
* **Small Footprint**
Usable in all but the tightest micro-controller environments, the focus is on the
@@ -41,8 +44,10 @@ About NuttX
Compatible GNU toolchains based on `buildroot <http://buildroot.uclibc.org/>`__ available for `download <https://bitbucket.org/nuttx/buildroot/downloads/>`__
to provide a complete development environment for many architectures.
+Feature Set
+===========
-**Feature Set**. Key features of NuttX include:
+Key features of NuttX include:
* **Standards Compliant Core Task Management**
@@ -222,7 +227,10 @@ About NuttX
* **BAS 2.4**
Seamless integration of Michael Haardt's BAS 2.4: "Bas is an interpreter for the classic dialect of the programming language BASIC. It is pretty compatible to typical BASIC interpreters of the 1980s, unlike some other UNIX BASIC interpreters, that implement a different syntax, breaking compatibility to existing programs. Bas offers many ANSI BASIC statements for structured programming, such as procedures, local variables and various loop types. Further there are matrix operations, au [...]
-**Look at all those files and features... How can it be a tiny OS?**. The NuttX feature list (above) is fairly long and if you
+Look at all those files and features... How can it be a tiny OS?
+================================================================
+
+The NuttX feature list (above) is fairly long and if you
look at the NuttX source tree, you will see that there are hundreds of source files comprising NuttX. How can NuttX be a tiny
OS with all of that?
diff --git a/Documentation/introduction/detailed_support.rst b/Documentation/introduction/detailed_support.rst
index 75c6b8a..a005d2d 100644
--- a/Documentation/introduction/detailed_support.rst
+++ b/Documentation/introduction/detailed_support.rst
@@ -1,12 +1,11 @@
+.. todo::
+ Migration is not yet completed from previous documentation. You can find the original list here:
+ `here <https://cwiki.apache.org/confluence/display/NUTTX/About>`__
+
=========================
Detailed Platform Support
=========================
-.. note:: This is a work in progress, the details of each board is not completely migrated as it is possible that this information will be moved to the "supported boards" section and improved.
-
-.. warning:: The following list is not yet completely migrated, in the meantime
- you can see this `here <https://cwiki.apache.org/confluence/display/NUTTX/About>`__
-
**Details**. The details, caveats and fine print follow. For even more
information see the *README* files that can be found
`here <README.html>`__.
diff --git a/Documentation/introduction/development_environments.rst b/Documentation/introduction/development_environments.rst
index 116c302..bc43616 100644
--- a/Documentation/introduction/development_environments.rst
+++ b/Documentation/introduction/development_environments.rst
@@ -1,3 +1,5 @@
+.. todo:: revise and update links
+
========================
Development Environments
========================
diff --git a/Documentation/introduction/index.rst b/Documentation/introduction/index.rst
index 4579abf..2122d87 100644
--- a/Documentation/introduction/index.rst
+++ b/Documentation/introduction/index.rst
@@ -1,7 +1,7 @@
Introduction
============
-.. note:: This section should probably not remain empty. Some content of the "about" document could be placed here (a brief description). Also, it would be good to have a graphic showing the layers of NuttX (I would use this as a base: https://nuttx_projects.gitlab.io/nuttx_book/nuttx-architecture.html)
+In the following sections you will find basic information introducing main NuttX features.
.. toctree::
:maxdepth: 1
diff --git a/Documentation/introduction/licensing.rst b/Documentation/introduction/licensing.rst
index 3a996fb..9b8c903 100644
--- a/Documentation/introduction/licensing.rst
+++ b/Documentation/introduction/licensing.rst
@@ -2,8 +2,10 @@
Licensing
=========
-.. warning:: update to Apache!
+NuttX is available under the Apache 2.0 License. You can find more information about the terms `here <https://www.apache.org/foundation/license-faq.html>`_.
-NuttX is available under the highly permissive BSD license. Other than some fine print that
-you agree to respect the copyright you should feel absolutely free to use NuttX in any environment and without any concern for jeopardizing any proprietary software that you may link with it.
+License terms
+=============
+.. include:: ../../LICENSE
+ :literal:
diff --git a/Documentation/introduction/supported_platforms.rst b/Documentation/introduction/supported_platforms.rst
index 2fefadd..ac2dd0e 100644
--- a/Documentation/introduction/supported_platforms.rst
+++ b/Documentation/introduction/supported_platforms.rst
@@ -130,7 +130,7 @@ MCU. Follow the links for the details:
- `PIC32MX2xx Family <#pic32mx2xx>`__ (MIPS32 M4K)
- `PIC32MX4xx Family <#pic32mx4xx>`__ (MIPS32 M4K)
- `PIC32MX7xx Family <#pic32mx7xx>`__ (MIPS32 M4K)
- - `PIC32MZEC Family <#pic32mzec>`__ (MIPS32 |br|
+ - `PIC32MZEC Family <#pic32mzec>`__ (MIPS32
microAptiv)
- `PIC32MZEF Family <#pic32mzef>`__ (MIPS32 M5150)
@@ -139,7 +139,7 @@ MCU. Follow the links for the details:
- `AVR ATMega128 <#avratmega128>`__ (8-bit AVR)
- `AVR ATMega1284p <#avratmega1284p>`__ (8-bit AVR)
- `AVR ATMega2560 <#avratmega2560>`__ (8-bit AVR)
- - `AVR AT90USB64x and AT90USB6128x <#avrat90usbxxx>`__ |br|
+ - `AVR AT90USB64x and AT90USB6128x <#avrat90usbxxx>`__
(8-bit AVR)
- `AVR32 AT32UC3BXXX <#at32uc3bxxx>`__ (32-bit AVR32)
- `Atmel SAMD20 <#at91samd20>`__ (ARM Cortex-M0+)
@@ -173,52 +173,52 @@ MCU. Follow the links for the details:
- NXP/Freescale
- `M68HCS12 <#m68hcs12>`__
- - `NXP/Freescale i.MX1 <#freescaleimx1>`__ |br|
+ - `NXP/Freescale i.MX1 <#freescaleimx1>`__
(ARM920-T)
- - `NXP/Freescale i.MX6 <#freescaleimx6>`__ |br|
+ - `NXP/Freescale i.MX6 <#freescaleimx6>`__
(ARM Cortex-A9)
- - `NXP/Freescale i.MX RT <#freescaleimxrt>`__ |br|
+ - `NXP/Freescale i.MX RT <#freescaleimxrt>`__
(ARM Cortex-M7)
- - `NXP/FreeScale KL25Z <#freescalekl25z>`__ |br|
+ - `NXP/FreeScale KL25Z <#freescalekl25z>`__
(ARM Cortex-M0+)
- - `NXP/FreeScale KL26Z <#freescalekl26z>`__ |br|
+ - `NXP/FreeScale KL26Z <#freescalekl26z>`__
(ARM Cortex-M0+)
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
- NXP/Freescale (Continued)
- - `NXP/FreeScale Kinetis K20 <#kinetisk20>`__ (ARM |br|
+ - `NXP/FreeScale Kinetis K20 <#kinetisk20>`__ (ARM
Cortex-M4)
- - `NXP/FreeScale Kinetis K28 <#kinetisk28>`__ (ARM |br|
+ - `NXP/FreeScale Kinetis K28 <#kinetisk28>`__ (ARM
Cortex-M4)
- - `NXP/FreeScale Kinetis K40 <#kinetisk40>`__ (ARM |br|
+ - `NXP/FreeScale Kinetis K40 <#kinetisk40>`__ (ARM
Cortex-M4)
- - `NXP/FreeScale Kinetis K60 <#kinetisk60>`__ (ARM |br|
+ - `NXP/FreeScale Kinetis K60 <#kinetisk60>`__ (ARM
Cortex-M4)
- - `NXP/FreeScale Kinetis K64 <#kinetisk64>`__ (ARM |br|
+ - `NXP/FreeScale Kinetis K64 <#kinetisk64>`__ (ARM
Cortex-M4)
- - `NXP/FreeScale Kinetis K66 <#kinetisk66>`__ (ARM |br|
+ - `NXP/FreeScale Kinetis K66 <#kinetisk66>`__ (ARM
Cortex-M4)
- `NXP LPC11xx <#nxplpc11xx>`__ (Cortex-M0)
@@ -257,167 +257,167 @@ MCU. Follow the links for the details:
- STMicroelectronics
- `STMicro STR71x <#str71x>`__ (ARM7TDMI)
- - `STMicro STM32F0xx <#stm32f0xx>`__ (STM32 F0, |br|
+ - `STMicro STM32F0xx <#stm32f0xx>`__ (STM32 F0,
ARM Cortex-M0)
- - `STMicro STM32L0xx <#stm32l0xx>`__ (STM32 L0, |br|
+ - `STMicro STM32L0xx <#stm32l0xx>`__ (STM32 L0,
ARM Cortex-M0)
- - `STMicro STM32G0xx <#stm32g0xx>`__ (STM32 G0 |br|
+ - `STMicro STM32G0xx <#stm32g0xx>`__ (STM32 G0
ARM Cortex-M0+)
- - `STMicro STM32L152 <#stm32l152>`__ (STM32 L1 |br|
+ - `STMicro STM32L152 <#stm32l152>`__ (STM32 L1
"EnergyLite" Line, ARM Cortex-M3)
- - `STMicro STM32L162 <#stm32l162>`__ (STM32 L1 |br|
- "EnergyLite" Medium+ Density, |br|
+ - `STMicro STM32L162 <#stm32l162>`__ (STM32 L1
+ "EnergyLite" Medium+ Density,
ARM Cortex-M3)
- - `STMicro STM32F100x <#stm32f100x>`__ (STM32 F1 |br|
+ - `STMicro STM32F100x <#stm32f100x>`__ (STM32 F1
"Value Line" Family, ARM Cortex-M3)
- - `STMicro STM32F102x <#stm32f102x>`__ (STM32 F1 |br|
+ - `STMicro STM32F102x <#stm32f102x>`__ (STM32 F1
family, ARM Cortex-M3)
- - `STMicro STM32F103C4/C8 <#stm32f103cx>`__ (STM32 F1 |br|
- "Low- and Medium-Density Line" |br|
+ - `STMicro STM32F103C4/C8 <#stm32f103cx>`__ (STM32 F1
+ "Low- and Medium-Density Line"
Family, ARM Cortex-M3)
- - `STMicro STM32F103x <#stm32f103x>`__ (STM32 F1 |br|
+ - `STMicro STM32F103x <#stm32f103x>`__ (STM32 F1
family, ARM Cortex-M3)
- `STMicro STM32F105x <#stm32f105x>`__ (ARM Cortex-M3)
- - `STMicro STM32F107x <#stm32f107x>`__ (STM32 F1 |br|
- family, "Connectivity Line" |br|
+ - `STMicro STM32F107x <#stm32f107x>`__ (STM32 F1
+ family, "Connectivity Line"
ARM Cortex-M3)
- - `STMicro STM32F205x <#stm32f205x>`__ (STM32 F2 |br|
+ - `STMicro STM32F205x <#stm32f205x>`__ (STM32 F2
family, ARM Cortex-M3)
- - `STMicro STM32F207x <#stm32f207x>`__ (STM32 F2 |br|
+ - `STMicro STM32F207x <#stm32f207x>`__ (STM32 F2
family, ARM Cortex-M3)
- - `STMicro STM32F302x <#stm32f302x>`__ (STM32 F3 |br|
+ - `STMicro STM32F302x <#stm32f302x>`__ (STM32 F3
family, ARM Cortex-M4)
- - `STMicro STM32F303x <#stm32f303x>`__ (STM32 F3 |br|
+ - `STMicro STM32F303x <#stm32f303x>`__ (STM32 F3
family, ARM Cortex-M4)
- - `STMicro STM32F334 <#stm32f334x>`__ (STM32 F3 |br|
+ - `STMicro STM32F334 <#stm32f334x>`__ (STM32 F3
family, ARM Cortex-M4)
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
- |br|
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
- STMicroelectronics (Continued)
- - `STMicro STM32 F372/F373 <#stm32f372x>`__ |br|
+ - `STMicro STM32 F372/F373 <#stm32f372x>`__
(ARM Cortex-M4)
- - `STMicro STM32F4x1 <#stm32f4x1>`__ |br|
- (STM32 F4 family, ARM |br|
+ - `STMicro STM32F4x1 <#stm32f4x1>`__
+ (STM32 F4 family, ARM
Cortex-M4)
- - `STMicro STM32F410 <#stm32f410>`__ |br|
- (STM32 F4 family, ARM |br|
+ - `STMicro STM32F410 <#stm32f410>`__
+ (STM32 F4 family, ARM
Cortex-M4)
- - `STMicro STM32F405x/407x <#stm32f407x>`__ |br|
- (STM32 F4 family, ARM |br|
+ - `STMicro STM32F405x/407x <#stm32f407x>`__
+ (STM32 F4 family, ARM
Cortex-M4)
- - `STMicro STM32 F427/F437 <#stm32f427x>`__ |br|
- (STM32 F4 family, ARM |br|
+ - `STMicro STM32 F427/F437 <#stm32f427x>`__
+ (STM32 F4 family, ARM
Cortex-M4)
- - `STMicro STM32 F429 <#stm32f429x>`__ |br|
- (STM32 FB family, ARM |br|
+ - `STMicro STM32 F429 <#stm32f429x>`__
+ (STM32 FB family, ARM
Cortex-M4)
- - `STMicro STM32 F433 <#stm32f433x>`__ |br|
- (STM32 F4 family, ARM |br|
+ - `STMicro STM32 F433 <#stm32f433x>`__
+ (STM32 F4 family, ARM
Cortex-M4)
- - `STMicro STM32 F446 <#stm32f446x>`__ |br|
- (STM32 F4 family, ARM |br|
+ - `STMicro STM32 F446 <#stm32f446x>`__
+ (STM32 F4 family, ARM
Cortex-M4)
- - `STMicro STM32 F46xx <#stm32f46xxx>`__ |br|
- (STM32 F4 family, ARM |br|
+ - `STMicro STM32 F46xx <#stm32f46xxx>`__
+ (STM32 F4 family, ARM
Cortex-M4)
- - `STMicro STM32 G474x <#stm32g474x>`__ |br|
- (STM32 G4 family, ARM |br|
+ - `STMicro STM32 G474x <#stm32g474x>`__
+ (STM32 G4 family, ARM
Cortex-M4)
- - `STMicro STM32 L4x2 <#stm32l4x2>`__ |br|
- (STM32 L4 family, ARM |br|
+ - `STMicro STM32 L4x2 <#stm32l4x2>`__
+ (STM32 L4 family, ARM
Cortex-M4)
- - `STMicro STM32 L475 <#stm32l475>`__ |br|
- (STM32 L4 family, ARM |br|
+ - `STMicro STM32 L475 <#stm32l475>`__
+ (STM32 L4 family, ARM
Cortex-M4)
- - `STMicro STM32 L476 <#stm32l476>`__ |br|
- (STM32 L4 family, ARM |br|
+ - `STMicro STM32 L476 <#stm32l476>`__
+ (STM32 L4 family, ARM
Cortex-M4)
- - `STMicro STM32 L496 <#stm32l496>`__ |br|
- (STM32 L4 family, ARM |br|
+ - `STMicro STM32 L496 <#stm32l496>`__
+ (STM32 L4 family, ARM
Cortex-M4)
- - `STMicro STM32 L4Rx <#stm32l4rx>`__ |br|
- (STM32 LB family, ARM |br|
+ - `STMicro STM32 L4Rx <#stm32l4rx>`__
+ (STM32 LB family, ARM
Cortex-M4)
- - `STMicro STM32 F72x/F73x <#stm32f72x3x>`__ |br|
- (STM32 F7 family, ARM |br|
+ - `STMicro STM32 F72x/F73x <#stm32f72x3x>`__
+ (STM32 F7 family, ARM
Cortex-M7)
- - `STMicro STM32 F745/F746 <#stm32f74x>`__ |br|
- (STM32 F7 family, ARM |br|
+ - `STMicro STM32 F745/F746 <#stm32f74x>`__
+ (STM32 F7 family, ARM
Cortex-M7)
- - `STMicro STM32 F756 <#stm32f75x>`__ |br|
- (STM32 F7 family, ARM |br|
+ - `STMicro STM32 F756 <#stm32f75x>`__
+ (STM32 F7 family, ARM
Cortex-M7)
- - `STMicro STM32 F76xx/F77xx <#stm32f76xx77xx>`__ |br|
- (STM32 F7 family, ARM |br|
+ - `STMicro STM32 F76xx/F77xx <#stm32f76xx77xx>`__
+ (STM32 F7 family, ARM
Cortex-M7)
- - `STMicro STM32 H7x3 <#stm32h7x3>`__ |br|
- (STM32 H7 family, ARM |br|
+ - `STMicro STM32 H7x3 <#stm32h7x3>`__
+ (STM32 H7 family, ARM
Cortex-M7)
- Texas Instruments
- (some formerly Luminary)
- - `TI TMS320-C5471 <#tms320c5471>`__ |br|
+ - `TI TMS320-C5471 <#tms320c5471>`__
(ARM7TDMI)
- - `TI TMS320-DM320 <#titms320dm320>`__ |br|
+ - `TI TMS320-DM320 <#titms320dm320>`__
(ARM9E6JS)
- - `TI/Stellaris LM3S6432 <#tilms6432>`__ |br|
+ - `TI/Stellaris LM3S6432 <#tilms6432>`__
(ARM Cortex-M3)
- - `TI/Stellaris LM3S6432S2E <#tilm3s6432s2e>`__ |br|
+ - `TI/Stellaris LM3S6432S2E <#tilm3s6432s2e>`__
(ARM Cortex-M3)
- - `TI/Stellaris LM3S6918 <#tilms6918>`__ |br|
+ - `TI/Stellaris LM3S6918 <#tilms6918>`__
(ARM Cortex-M3)
- - `TI/Stellaris LM3S6965 <#tilms6965>`__ |br|
+ - `TI/Stellaris LM3S6965 <#tilms6965>`__
(ARM Cortex-M3)
- - `TI/Stellaris LM3S8962 <#tilms8962>`__ |br|
+ - `TI/Stellaris LM3S8962 <#tilms8962>`__
(ARM Cortex-M3)
- - `TI/Stellaris LM3S9B92 <#tilms9b92>`__ |br|
+ - `TI/Stellaris LM3S9B92 <#tilms9b92>`__
(ARM Cortex-M3)
- - `TI/Stellaris LM3S9B96 <#tilms9b96>`__ |br|
+ - `TI/Stellaris LM3S9B96 <#tilms9b96>`__
(ARM Cortex-M3)
- - `TI/SimpleLink CC13x0 <#tilcc13x0>`__ |br|
+ - `TI/SimpleLink CC13x0 <#tilcc13x0>`__
(ARM Cortex-M3)
- - `TI/Stellaris LM4F120x <#tilm4f120x>`__ |br|
+ - `TI/Stellaris LM4F120x <#tilm4f120x>`__
(ARM Cortex-M4)
- - `TI/Tiva TM4C123G <#titm4c123g>`__ |br|
+ - `TI/Tiva TM4C123G <#titm4c123g>`__
(ARM Cortex-M4)
- - `TI/Tiva TM4C1294 <#titm4c1294>`__ |br|
+ - `TI/Tiva TM4C1294 <#titm4c1294>`__
(ARM Cortex-M4)
- - `TI/Tiva TM4C129X <#titm4c129x>`__ |br|
+ - `TI/Tiva TM4C129X <#titm4c129x>`__
(ARM Cortex-M4)
- - `TI/SimpleLink CC13x2 <#tilcc13x2>`__ |br|
+ - `TI/SimpleLink CC13x2 <#tilcc13x2>`__
(ARM Cortex-M4)
- - `TI/Hercules TMS570LS04xx <#tms570ls04x>`__ |br|
+ - `TI/Hercules TMS570LS04xx <#tms570ls04x>`__
(ARM Cortex-R4)
- - `TI/Hercules TMS570LS31xx <#tms570ls31x>`__ |br|
+ - `TI/Hercules TMS570LS31xx <#tms570ls31x>`__
(ARM Cortex-R4)
- - `TI/Sitara AM335x <#tiam355x>`__ |br|
+ - `TI/Sitara AM335x <#tiam355x>`__
(Cortex-A8)
- ZiLOG
diff --git a/Documentation/introduction/trademarks.rst b/Documentation/introduction/trademarks.rst
index 20c9e8b..3698a0d 100644
--- a/Documentation/introduction/trademarks.rst
+++ b/Documentation/introduction/trademarks.rst
@@ -1,3 +1,5 @@
+.. todo:: Revise status of NuttX trademark
+
==========
Trademarks
==========
diff --git a/Documentation/quickstart/index.rst b/Documentation/quickstart/index.rst
index 13a8e3a..70423f9 100644
--- a/Documentation/quickstart/index.rst
+++ b/Documentation/quickstart/index.rst
@@ -1,12 +1,13 @@
+.. todo::
+ This should be a brief introduction to how NuttX works and how to get it running. A widely used board could be targeted to create a brief demonstration on how to clone, configure, build, flash and run NuttX.
+ For now, the content that is here presented is what remains of the old Porting Guide which is not already in another section of this documentation.
+
==========
Quickstart
==========
-.. note::
- This should be a brief introduction to how NuttX works and how to get it running. A widely used board could be targeted to create a brief demonstration on how to clone, configure, build, flash and run NuttX.
- For now, I've included the parts of the old porting guide which seemed more relevant for this section, but should be revised and made
- (new) user friendly.
-
+The present Quickstart guide is a work in progress and only contains some basic information. In the meantime you can look at NuttX main `README <https://github.com/apache/incubator-nuttx/blob/master/README.md>`_ file which contains some information that will help you get started.
+
.. toctree::
:maxdepth: 1
diff --git a/Documentation/reference/index.rst b/Documentation/reference/index.rst
index 646d461..f033f68 100644
--- a/Documentation/reference/index.rst
+++ b/Documentation/reference/index.rst
@@ -1,11 +1,11 @@
+.. todo::
+ Add brief intro, distinguishing the arch and user facing APIs. Otherwise there could simply be
+ a top-level document for each API
+
=============
API Reference
=============
-.. note::
- TODO: add brief intro, distinguishing the arch and user facing APIs. Otherwise there could simply be
- a top-level document for each API
-
.. toctree::
:caption: Contents:
:maxdepth: 1
[incubator-nuttx] 06/17: backport watchdog API changes to new
documentation (PRs: #1534 #1545 and #1565)
Posted by bt...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
btashton pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
commit 6bcbbc3b286f3e90f699f4f262aa62467bbcaeee
Author: Matias N <ma...@protobits.dev>
AuthorDate: Fri Aug 14 17:25:53 2020 -0300
backport watchdog API changes to new documentation (PRs: #1534 #1545 and #1565)
---
Documentation/reference/os/time_clock.rst | 89 ++++-------------------------
Documentation/reference/user/structures.rst | 1 -
2 files changed, 11 insertions(+), 79 deletions(-)
diff --git a/Documentation/reference/os/time_clock.rst b/Documentation/reference/os/time_clock.rst
index dc9f187..3892825 100644
--- a/Documentation/reference/os/time_clock.rst
+++ b/Documentation/reference/os/time_clock.rst
@@ -484,78 +484,13 @@ watchdog timer function. However, the watchdog timer function may
use ``mq_send()``, ``sigqueue()``, or ``kill()`` to communicate
with NuttX tasks.
-- :c:func:`wd_create`/:c:func:`wd_static`
-- :c:func:`wd_delete`
- :c:func:`wd_start`
- :c:func:`wd_cancel`
- :c:func:`wd_gettime`
- Watchdog Timer Callback
-.. c:function:: WDOG_ID wd_create(void)
-
- The ``wd_create()`` function will create a timer
- by allocating the appropriate resources for the watchdog. The
- ``wd_create()`` function returns a pointer to a fully initialized,
- dynamically allocated ``struct wdog_s`` instance (which is
- ``typedef``'ed as ``WDOG_ID``);
-
- :return: Pointer to watchdog that may be used as a handle in subsequent
- NuttX calls (i.e., the watchdog ID), or NULL if insufficient
- resources are available to create the watchdogs.
-
-.. c:function:: void wd_static(FAR struct wdog_s *wdog)
-
- Performs the equivalent initialization of a
- statically allocated ``struct wdog_s`` instance. No allocation is
- performed in this case. The initializer definition,
- ``WDOG_INITIALIZER`` is also available for initialization of
- static instances of ``struct wdog_s``. NOTE: ``wd_static()`` is
- also implemented as a macro definition.
-
- **POSIX Compatibility:** This is a NON-POSIX interface. VxWorks
- provides the following comparable interface:
-
- .. code-block:: c
-
- WDOG_ID wdCreate (void);
-
- Differences from the VxWorks interface include:
-
- - The number of available watchdogs is fixed (configured at
- initialization time).
-
-.. c:function:: int wd_delete(WDOG_ID wdog)
-
- Deallocate a watchdog
- timer previously allocated via ``wd_create()``. The watchdog timer
- will be removed from the timer queue if has been started.
-
- This function need not be called for statically allocated timers
- (but it is not harmful to do so).
-
- :param wdog: The watchdog ID to delete. This is actually a pointer
- to a watchdog structure.
-
- :return: Zero (``OK``) is returned on success; a negated ``errno`` value
- is return to indicate the nature of any failure.
-
- **Assumptions/Limitations:** It is the responsibility of the
- caller to assure that the watchdog is inactive before deleting it.
-
- **POSIX Compatibility:** This is a NON-POSIX interface. VxWorks
- provides the following comparable interface:
-
- .. code-block:: c
-
- STATUS wdDelete (WDOG_ID wdog);
-
- Differences from the VxWorks interface include:
-
- - Does not make any checks to see if the watchdog is being used
- before deallocating it (i.e., never returns ERROR).
-
-.. c:function:: int wd_start(WDOG_ID wdog, int delay, wdentry_t wdentry, \
- int argc, ...);
+.. c:function:: int wd_start(FAR struct wdog_s *wdog, int delay, \
+ wdentry_t wdentry, wdparm_t arg)
This function adds a watchdog to the timer queue.
The specified watchdog function will be called from the interrupt
@@ -574,10 +509,9 @@ with NuttX tasks.
:param wdog: Watchdog ID
:param delay: Delay count in clock ticks
:param wdentry: Function to call on timeout
- :param argc: The number of uint32_t parameters to pass to wdentry.
- :param ...: ``uint32_t`` size parameters to pass to ``wdentry``
+ :param arg: The parameter to pass to wdentry.
- **NOTE**: All parameters must be of type ``wdparm_t``.
+ **NOTE**: The parameter must be of type ``wdparm_t``.
:return: Zero (``OK``) is returned on success; a negated ``errno`` value
is return to indicate the nature of any failure.
@@ -599,7 +533,7 @@ with NuttX tasks.
to wdentry; VxWorks supports only a single parameter. The
maximum number of parameters is determined by
-.. c:function:: int wd_cancel(WDOG_ID wdog)
+.. c:function:: int wd_cancel(FAR struct wdog_s *wdog)
This function cancels a currently running
watchdog timer. Watchdog timers may be canceled from the interrupt
@@ -617,7 +551,7 @@ with NuttX tasks.
STATUS wdCancel (WDOG_ID wdog);
-.. c:function:: int wd_gettime(WDOG_ID wdog)
+.. c:function:: int wd_gettime(FAR struct wdog_s *wdog)
Returns the time remaining before
the specified watchdog expires.
@@ -628,19 +562,18 @@ with NuttX tasks.
watchdog time expires. Zero means either that wdog is not valid or
that the wdog has already expired.
-.. c:type:: void (*wdentry_t)(int argc, ...)
+.. c:type:: void (*wdentry_t)(wdparm_t arg)
**Watchdog Timer Callback**: when a watchdog expires,
the callback function with this type is
- called, where ``argc`` is the number of
- ``wdparm_t`` type arguments that follow.
-
- The arguments are passed as scalar ``wdparm_t`` values. For
+ called.
+
+ The argument is passed as scalar ``wdparm_t`` values. For
systems where the ``sizeof(pointer) < sizeof(uint32_t)``, the
following union defines the alignment of the pointer within the
``uint32_t``. For example, the SDCC MCS51 general pointer is
24-bits, but ``uint32_t`` is 32-bits (of course).
-
+
We always have ``sizeof(pointer) <= sizeof(uintptr_t)`` by
definition.
diff --git a/Documentation/reference/user/structures.rst b/Documentation/reference/user/structures.rst
index 4552a13..375b2e3 100644
--- a/Documentation/reference/user/structures.rst
+++ b/Documentation/reference/user/structures.rst
@@ -26,7 +26,6 @@ structures include:
.. c:struct:: tcb_s
.. c:type:: mqd_t
.. c:type:: sem_t
-.. c:type:: WDOG_ID
.. c:type:: pthread_key_t
In order to maintain portability, applications should not reference
[incubator-nuttx] 07/17: backport SocketCAN documentation to new
docs (PR #1533)
Posted by bt...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
btashton pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
commit 2fb9910b017649c2c64295cb948d56e7403e367d
Author: Matias N <ma...@protobits.dev>
AuthorDate: Fri Aug 14 17:31:06 2020 -0300
backport SocketCAN documentation to new docs (PR #1533)
---
Documentation/components/index.rst | 1 +
Documentation/components/socketcan.rst | 66 ++++++++++++++++++++++++++++++++++
2 files changed, 67 insertions(+)
diff --git a/Documentation/components/index.rst b/Documentation/components/index.rst
index aa34634..b2ba8e6 100644
--- a/Documentation/components/index.rst
+++ b/Documentation/components/index.rst
@@ -10,6 +10,7 @@ OS Components
nsh/index.rst
power.rst
+ socketcan.rst
syslog.rst
binfmt.rst
drivers/index.rst
diff --git a/Documentation/components/socketcan.rst b/Documentation/components/socketcan.rst
new file mode 100644
index 0000000..f8323a2
--- /dev/null
+++ b/Documentation/components/socketcan.rst
@@ -0,0 +1,66 @@
+========================
+SocketCAN Device Drivers
+========================
+
+ - **``include/nuttx/net/netdev.h``**. All structures and APIs
+ needed to work with drivers are provided in this header file.
+ The structure struct net_driver_s defines the interface and is
+ passed to the network via netdev_register().
+
+ - **``include/nuttx/can.h``**. CAN & CAN FD frame data
+ structures.
+
+ - **``int netdev_register(FAR struct net_driver_s *dev, enum net_lltype_e lltype)'``**.
+ Each driver registers itself by calling netdev_register().
+
+ - **``Include/nuttx/net/can.h``**. contains lookup tables for CAN
+ dlc to CAN FD len sizes named
+
+ .. code-block:: c
+
+ extern const uint8_t can_dlc_to_len[16];
+ extern const uint8_t len_to_can_dlc[65];
+
+ - **Initialization sequence is as follows**.
+
+ #. up_netinitialize(void) is called on startup of NuttX in this
+ function you call your own init function to initialize your
+ CAN driver
+ #. In your own init function you create the net_driver_s
+ structure set required init values and register the required
+ callbacks for SocketCAN
+ #. Then you ensure that the CAN interface is in down mode
+ (usually done by calling the d_ifdown function)
+ #. Register the net_driver_s using netdev_register
+
+ - **Receive sequence is as follows**.
+
+ #. Device generates interrupt
+ #. Process this interrupt in your interrupt handler
+ #. When a new CAN frame has been received you process this
+ frame
+ #. When the CAN frame is a normal CAN frame you allocate the
+ can_frame struct, when it's a CAN FD frame you allocate a
+ canfd_frame struct (note you can of course preallocate and
+ just use the pointer).
+ #. Copy the frame from the driver to the struct you've
+ allocated in the previous step.
+ #. Point the net_driver_s d_buf pointer to the allocated
+ can_frame
+ #. Call the ``can_input(FAR struct net_driver_s *dev)``
+ function ``include/nuttx/net/can.h``
+
+ - **Transmit sequence is as follows**.
+
+ #. Socket layer executes d_txavail callback
+ #. An example of the txavail function can be found in
+ ``arch/arm/src/s32k1xx/s32k1xx_flexcan.c``
+ #. An example of the txpoll function can be found in
+ ``arch/arm/src/s32k1xx/s32k1xx_flexcan.c``
+ #. In your ``transmit(struct driver_s *priv)`` function you
+ check the length of ``net_driver_s.d_len`` whether it
+ matches the size of a ``struct can_frame`` or
+ ``struct canfd_frame`` then you cast the content of the
+ ``net_driver_s.d_buf`` pointer to the correct CAN frame
+ struct
+
[incubator-nuttx] 05/17: rename doc/ -> Documentation/
Posted by bt...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
btashton pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
commit 4276d6254a2dcaec0d152c4f222f2f3a1d9548e5
Author: Matias N <ma...@protobits.dev>
AuthorDate: Fri Aug 14 17:01:22 2020 -0300
rename doc/ -> Documentation/
---
.github/workflows/build.yml | 4 +-
.github/workflows/check.yml | 2 +-
.github/workflows/doc.yml | 30 ++++-------
.github/workflows/sphinx-docs.yml | 56 ---------------------
{doc => Documentation}/.gitignore | 0
{doc => Documentation}/Makefile | 0
{doc => Documentation}/Pipfile | 0
{doc => Documentation}/Pipfile.lock | 0
{doc => Documentation}/_static/NuttX.png | Bin
{doc => Documentation}/_static/NuttX320.png | Bin
{doc => Documentation}/_static/custom.css | 0
Documentation/_static/favicon.ico | Bin 0 -> 4286 bytes
{doc => Documentation}/applications/index.rst | 0
{doc => Documentation}/boards/index.rst | 0
{doc => Documentation}/components/binfmt.rst | 0
.../components/drivers/index.rst | 0
{doc => Documentation}/components/filesystem.rst | 0
{doc => Documentation}/components/index.rst | 0
{doc => Documentation}/components/nsh/builtin.rst | 0
{doc => Documentation}/components/nsh/commands.rst | 0
{doc => Documentation}/components/nsh/config.rst | 0
.../components/nsh/customizing.rst | 0
{doc => Documentation}/components/nsh/index.rst | 0
.../components/nsh/installation.rst | 0
{doc => Documentation}/components/nsh/login.rst | 0
{doc => Documentation}/components/nsh/nsh.rst | 0
{doc => Documentation}/components/nxflat.rst | 0
.../components/nxgraphics/NXOrganization.gif | Bin
.../components/nxgraphics/NuttXScreenShot.jpg | Bin
.../components/nxgraphics/appendix.rst | 0
.../components/nxgraphics/index.rst | 0
.../components/nxgraphics/nx.rst | 0
.../components/nxgraphics/nxcursor.rst | 0
.../components/nxgraphics/nxfonts.rst | 0
.../components/nxgraphics/nxgl.rst | 0
.../components/nxgraphics/nxtk.rst | 0
.../components/nxgraphics/sample.rst | 0
{doc => Documentation}/components/nxwidgets.rst | 0
{doc => Documentation}/components/paging.rst | 0
{doc => Documentation}/components/pm.png | Bin
{doc => Documentation}/components/power.rst | 0
{doc => Documentation}/components/syslog.rst | 0
{doc => Documentation}/conf.py | 2 +-
.../contributing/coding_style.rst | 0
.../contributing/documentation.rst | 0
{doc => Documentation}/contributing/index.rst | 0
{doc => Documentation}/contributing/workflow.rst | 0
{doc => Documentation}/glossary.rst | 0
{doc => Documentation}/guides/index.rst | 0
{doc => Documentation}/guides/nfs.rst | 0
{doc => Documentation}/guides/usbtrace.rst | 0
{doc => Documentation}/index.rst | 0
{doc => Documentation}/introduction/about.rst | 0
.../introduction/detailed_support.rst | 0
.../introduction/development_environments.rst | 0
{doc => Documentation}/introduction/index.rst | 0
{doc => Documentation}/introduction/licensing.rst | 0
{doc => Documentation}/introduction/resources.rst | 0
.../introduction/supported_platforms.rst | 0
{doc => Documentation}/introduction/trademarks.rst | 0
{doc => Documentation}/make.bat | 0
{doc => Documentation}/quickstart/config_build.rst | 0
{doc => Documentation}/quickstart/index.rst | 0
{doc => Documentation}/quickstart/organization.rst | 0
{doc => Documentation}/reference/index.rst | 0
{doc => Documentation}/reference/os/addrenv.rst | 0
{doc => Documentation}/reference/os/app_vs_os.rst | 0
{doc => Documentation}/reference/os/arch.rst | 0
{doc => Documentation}/reference/os/board.rst | 0
{doc => Documentation}/reference/os/boardctl.rst | 0
.../reference/os/conventions.rst | 0
{doc => Documentation}/reference/os/index.rst | 0
{doc => Documentation}/reference/os/iob.rst | 0
{doc => Documentation}/reference/os/led.rst | 0
{doc => Documentation}/reference/os/nuttx.rst | 0
{doc => Documentation}/reference/os/paging.rst | 0
{doc => Documentation}/reference/os/shm.rst | 0
{doc => Documentation}/reference/os/smp.rst | 0
{doc => Documentation}/reference/os/time_clock.rst | 0
{doc => Documentation}/reference/os/wqueue.rst | 0
.../reference/user/01_task_control.rst | 0
.../reference/user/02_task_scheduling.rst | 0
.../reference/user/03_task_control.rst | 0
.../reference/user/04_message_queue.rst | 0
.../reference/user/05_counting_semaphore.rst | 0
.../reference/user/06_clocks_timers.rst | 0
.../reference/user/07_signals.rst | 0
.../reference/user/08_pthread.rst | 0
.../reference/user/09_env_vars.rst | 0
.../reference/user/10_filesystem.rst | 0
.../reference/user/11_network.rst | 0
.../reference/user/12_shared_memory.rst | 0
{doc => Documentation}/reference/user/index.rst | 0
.../reference/user/structures.rst | 0
{doc => Documentation}/releases/index.rst | 0
{doc => Documentation}/requirements.txt | 0
{doc => Documentation}/substitutions.rst | 0
doc/_static/favicon.ico | Bin 3126 -> 0 bytes
98 files changed, 13 insertions(+), 81 deletions(-)
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index cf00065..220d9e0 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -15,10 +15,10 @@ name: Build
on:
pull_request:
paths-ignore:
- - 'doc/**'
+ - 'Documentation/**'
push:
paths-ignore:
- - 'doc/**'
+ - 'Documentation/**'
branches:
- master
- 'releases/*'
diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml
index 9241135..02799f9 100644
--- a/.github/workflows/check.yml
+++ b/.github/workflows/check.yml
@@ -15,7 +15,7 @@ name: Check
on:
pull_request:
paths-ignore:
- - 'doc/**'
+ - 'Documentation/**'
jobs:
check:
diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index c32f707..10560aa 100644
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -10,32 +10,20 @@
# See the License for the specific language governing permissions and
# limitations under the License.
#
-name: Doc
-
+name: "Build Documentation"
on:
pull_request:
- paths:
- - 'docs/**'
+ push:
jobs:
docs:
- runs-on: ubuntu-18.04
+ runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v2
+ - uses: actions/checkout@v1
+ - uses: ammaraskar/sphinx-action@master
with:
- path: nuttx
- fetch-depth: 1
- - name: Generate Inlined Docs
- run: |
- echo "Inline Docs"
- npm install --no-audit inliner
- inliner=`pwd`/node_modules/inliner/cli/index.js
- build_output=`pwd`/build
- mkdir $build_output
- cd nuttx/Documentation
- find ./ -type f -name "*.html" -exec script -e -c "$inliner {} > $build_output/{}" \;
- ls -l $build_output/
- - uses: actions/upload-artifact@v1
+ docs-folder: "Documentation/"
+ - uses: actions/upload-artifact@v2
with:
- name: htmldocs
- path: ./build/
+ name: sphinx-docs
+ path: Documentation/_build/html/
diff --git a/.github/workflows/sphinx-docs.yml b/.github/workflows/sphinx-docs.yml
deleted file mode 100644
index b324527..0000000
--- a/.github/workflows/sphinx-docs.yml
+++ /dev/null
@@ -1,56 +0,0 @@
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-#
-name: "Build Sphinx Docs"
-on:
- pull_request:
- push:
- branches:
- - master
- - docs
- - 'releases/*'
- tags:
-
-jobs:
- docs:
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v1
- - uses: ammaraskar/sphinx-action@master
- with:
- docs-folder: "doc/"
- - uses: actions/upload-artifact@v2
- with:
- name: sphinx-docs
- path: doc/_build/html/
- - name: Commit documentation changes
- if: github.event_name != 'pull_request'
- run: |
- git clone https://github.com/v01d/incubator-nuttx.git --branch gh-pages --single-branch gh-pages
- cd gh-pages
- rm -rf ${GITHUB_REF##*/}
- mkdir -p ${GITHUB_REF##*/}
- cd ${GITHUB_REF##*/}
- cp -r ../../doc/_build/html/* .
- git config --local user.email "action@github.com"
- git config --local user.name "GitHub Action"
- git add .
- git commit -m "Update documentation" -a || true
- # The above command will fail if no changes were present, so we ignore
- # the return code.
- - name: Push changes
- if: github.event_name != 'pull_request'
- uses: ad-m/github-push-action@master
- with:
- branch: gh-pages
- directory: gh-pages
- github_token: ${{ secrets.GITHUB_TOKEN }}
diff --git a/doc/.gitignore b/Documentation/.gitignore
similarity index 100%
rename from doc/.gitignore
rename to Documentation/.gitignore
diff --git a/doc/Makefile b/Documentation/Makefile
similarity index 100%
rename from doc/Makefile
rename to Documentation/Makefile
diff --git a/doc/Pipfile b/Documentation/Pipfile
similarity index 100%
rename from doc/Pipfile
rename to Documentation/Pipfile
diff --git a/doc/Pipfile.lock b/Documentation/Pipfile.lock
similarity index 100%
rename from doc/Pipfile.lock
rename to Documentation/Pipfile.lock
diff --git a/doc/_static/NuttX.png b/Documentation/_static/NuttX.png
similarity index 100%
rename from doc/_static/NuttX.png
rename to Documentation/_static/NuttX.png
diff --git a/doc/_static/NuttX320.png b/Documentation/_static/NuttX320.png
similarity index 100%
rename from doc/_static/NuttX320.png
rename to Documentation/_static/NuttX320.png
diff --git a/doc/_static/custom.css b/Documentation/_static/custom.css
similarity index 100%
rename from doc/_static/custom.css
rename to Documentation/_static/custom.css
diff --git a/Documentation/_static/favicon.ico b/Documentation/_static/favicon.ico
new file mode 100644
index 0000000..4066865
Binary files /dev/null and b/Documentation/_static/favicon.ico differ
diff --git a/doc/applications/index.rst b/Documentation/applications/index.rst
similarity index 100%
rename from doc/applications/index.rst
rename to Documentation/applications/index.rst
diff --git a/doc/boards/index.rst b/Documentation/boards/index.rst
similarity index 100%
rename from doc/boards/index.rst
rename to Documentation/boards/index.rst
diff --git a/doc/components/binfmt.rst b/Documentation/components/binfmt.rst
similarity index 100%
rename from doc/components/binfmt.rst
rename to Documentation/components/binfmt.rst
diff --git a/doc/components/drivers/index.rst b/Documentation/components/drivers/index.rst
similarity index 100%
rename from doc/components/drivers/index.rst
rename to Documentation/components/drivers/index.rst
diff --git a/doc/components/filesystem.rst b/Documentation/components/filesystem.rst
similarity index 100%
rename from doc/components/filesystem.rst
rename to Documentation/components/filesystem.rst
diff --git a/doc/components/index.rst b/Documentation/components/index.rst
similarity index 100%
rename from doc/components/index.rst
rename to Documentation/components/index.rst
diff --git a/doc/components/nsh/builtin.rst b/Documentation/components/nsh/builtin.rst
similarity index 100%
rename from doc/components/nsh/builtin.rst
rename to Documentation/components/nsh/builtin.rst
diff --git a/doc/components/nsh/commands.rst b/Documentation/components/nsh/commands.rst
similarity index 100%
rename from doc/components/nsh/commands.rst
rename to Documentation/components/nsh/commands.rst
diff --git a/doc/components/nsh/config.rst b/Documentation/components/nsh/config.rst
similarity index 100%
rename from doc/components/nsh/config.rst
rename to Documentation/components/nsh/config.rst
diff --git a/doc/components/nsh/customizing.rst b/Documentation/components/nsh/customizing.rst
similarity index 100%
rename from doc/components/nsh/customizing.rst
rename to Documentation/components/nsh/customizing.rst
diff --git a/doc/components/nsh/index.rst b/Documentation/components/nsh/index.rst
similarity index 100%
rename from doc/components/nsh/index.rst
rename to Documentation/components/nsh/index.rst
diff --git a/doc/components/nsh/installation.rst b/Documentation/components/nsh/installation.rst
similarity index 100%
rename from doc/components/nsh/installation.rst
rename to Documentation/components/nsh/installation.rst
diff --git a/doc/components/nsh/login.rst b/Documentation/components/nsh/login.rst
similarity index 100%
rename from doc/components/nsh/login.rst
rename to Documentation/components/nsh/login.rst
diff --git a/doc/components/nsh/nsh.rst b/Documentation/components/nsh/nsh.rst
similarity index 100%
rename from doc/components/nsh/nsh.rst
rename to Documentation/components/nsh/nsh.rst
diff --git a/doc/components/nxflat.rst b/Documentation/components/nxflat.rst
similarity index 100%
rename from doc/components/nxflat.rst
rename to Documentation/components/nxflat.rst
diff --git a/doc/components/nxgraphics/NXOrganization.gif b/Documentation/components/nxgraphics/NXOrganization.gif
similarity index 100%
rename from doc/components/nxgraphics/NXOrganization.gif
rename to Documentation/components/nxgraphics/NXOrganization.gif
diff --git a/doc/components/nxgraphics/NuttXScreenShot.jpg b/Documentation/components/nxgraphics/NuttXScreenShot.jpg
similarity index 100%
rename from doc/components/nxgraphics/NuttXScreenShot.jpg
rename to Documentation/components/nxgraphics/NuttXScreenShot.jpg
diff --git a/doc/components/nxgraphics/appendix.rst b/Documentation/components/nxgraphics/appendix.rst
similarity index 100%
rename from doc/components/nxgraphics/appendix.rst
rename to Documentation/components/nxgraphics/appendix.rst
diff --git a/doc/components/nxgraphics/index.rst b/Documentation/components/nxgraphics/index.rst
similarity index 100%
rename from doc/components/nxgraphics/index.rst
rename to Documentation/components/nxgraphics/index.rst
diff --git a/doc/components/nxgraphics/nx.rst b/Documentation/components/nxgraphics/nx.rst
similarity index 100%
rename from doc/components/nxgraphics/nx.rst
rename to Documentation/components/nxgraphics/nx.rst
diff --git a/doc/components/nxgraphics/nxcursor.rst b/Documentation/components/nxgraphics/nxcursor.rst
similarity index 100%
rename from doc/components/nxgraphics/nxcursor.rst
rename to Documentation/components/nxgraphics/nxcursor.rst
diff --git a/doc/components/nxgraphics/nxfonts.rst b/Documentation/components/nxgraphics/nxfonts.rst
similarity index 100%
rename from doc/components/nxgraphics/nxfonts.rst
rename to Documentation/components/nxgraphics/nxfonts.rst
diff --git a/doc/components/nxgraphics/nxgl.rst b/Documentation/components/nxgraphics/nxgl.rst
similarity index 100%
rename from doc/components/nxgraphics/nxgl.rst
rename to Documentation/components/nxgraphics/nxgl.rst
diff --git a/doc/components/nxgraphics/nxtk.rst b/Documentation/components/nxgraphics/nxtk.rst
similarity index 100%
rename from doc/components/nxgraphics/nxtk.rst
rename to Documentation/components/nxgraphics/nxtk.rst
diff --git a/doc/components/nxgraphics/sample.rst b/Documentation/components/nxgraphics/sample.rst
similarity index 100%
rename from doc/components/nxgraphics/sample.rst
rename to Documentation/components/nxgraphics/sample.rst
diff --git a/doc/components/nxwidgets.rst b/Documentation/components/nxwidgets.rst
similarity index 100%
rename from doc/components/nxwidgets.rst
rename to Documentation/components/nxwidgets.rst
diff --git a/doc/components/paging.rst b/Documentation/components/paging.rst
similarity index 100%
rename from doc/components/paging.rst
rename to Documentation/components/paging.rst
diff --git a/doc/components/pm.png b/Documentation/components/pm.png
similarity index 100%
rename from doc/components/pm.png
rename to Documentation/components/pm.png
diff --git a/doc/components/power.rst b/Documentation/components/power.rst
similarity index 100%
rename from doc/components/power.rst
rename to Documentation/components/power.rst
diff --git a/doc/components/syslog.rst b/Documentation/components/syslog.rst
similarity index 100%
rename from doc/components/syslog.rst
rename to Documentation/components/syslog.rst
diff --git a/doc/conf.py b/Documentation/conf.py
similarity index 98%
rename from doc/conf.py
rename to Documentation/conf.py
index a2b4d18..054f25a 100644
--- a/doc/conf.py
+++ b/Documentation/conf.py
@@ -73,7 +73,7 @@ html_css_files = [
html_show_license = True
-html_logo = '../Documentation/NuttX.png'
+html_logo = '_static/NuttX.png'
html_favicon = '_static/favicon.ico'
today_fmt = '%d %B %y at %H:%M'
diff --git a/doc/contributing/coding_style.rst b/Documentation/contributing/coding_style.rst
similarity index 100%
rename from doc/contributing/coding_style.rst
rename to Documentation/contributing/coding_style.rst
diff --git a/doc/contributing/documentation.rst b/Documentation/contributing/documentation.rst
similarity index 100%
rename from doc/contributing/documentation.rst
rename to Documentation/contributing/documentation.rst
diff --git a/doc/contributing/index.rst b/Documentation/contributing/index.rst
similarity index 100%
rename from doc/contributing/index.rst
rename to Documentation/contributing/index.rst
diff --git a/doc/contributing/workflow.rst b/Documentation/contributing/workflow.rst
similarity index 100%
rename from doc/contributing/workflow.rst
rename to Documentation/contributing/workflow.rst
diff --git a/doc/glossary.rst b/Documentation/glossary.rst
similarity index 100%
rename from doc/glossary.rst
rename to Documentation/glossary.rst
diff --git a/doc/guides/index.rst b/Documentation/guides/index.rst
similarity index 100%
rename from doc/guides/index.rst
rename to Documentation/guides/index.rst
diff --git a/doc/guides/nfs.rst b/Documentation/guides/nfs.rst
similarity index 100%
rename from doc/guides/nfs.rst
rename to Documentation/guides/nfs.rst
diff --git a/doc/guides/usbtrace.rst b/Documentation/guides/usbtrace.rst
similarity index 100%
rename from doc/guides/usbtrace.rst
rename to Documentation/guides/usbtrace.rst
diff --git a/doc/index.rst b/Documentation/index.rst
similarity index 100%
rename from doc/index.rst
rename to Documentation/index.rst
diff --git a/doc/introduction/about.rst b/Documentation/introduction/about.rst
similarity index 100%
rename from doc/introduction/about.rst
rename to Documentation/introduction/about.rst
diff --git a/doc/introduction/detailed_support.rst b/Documentation/introduction/detailed_support.rst
similarity index 100%
rename from doc/introduction/detailed_support.rst
rename to Documentation/introduction/detailed_support.rst
diff --git a/doc/introduction/development_environments.rst b/Documentation/introduction/development_environments.rst
similarity index 100%
rename from doc/introduction/development_environments.rst
rename to Documentation/introduction/development_environments.rst
diff --git a/doc/introduction/index.rst b/Documentation/introduction/index.rst
similarity index 100%
rename from doc/introduction/index.rst
rename to Documentation/introduction/index.rst
diff --git a/doc/introduction/licensing.rst b/Documentation/introduction/licensing.rst
similarity index 100%
rename from doc/introduction/licensing.rst
rename to Documentation/introduction/licensing.rst
diff --git a/doc/introduction/resources.rst b/Documentation/introduction/resources.rst
similarity index 100%
rename from doc/introduction/resources.rst
rename to Documentation/introduction/resources.rst
diff --git a/doc/introduction/supported_platforms.rst b/Documentation/introduction/supported_platforms.rst
similarity index 100%
rename from doc/introduction/supported_platforms.rst
rename to Documentation/introduction/supported_platforms.rst
diff --git a/doc/introduction/trademarks.rst b/Documentation/introduction/trademarks.rst
similarity index 100%
rename from doc/introduction/trademarks.rst
rename to Documentation/introduction/trademarks.rst
diff --git a/doc/make.bat b/Documentation/make.bat
similarity index 100%
rename from doc/make.bat
rename to Documentation/make.bat
diff --git a/doc/quickstart/config_build.rst b/Documentation/quickstart/config_build.rst
similarity index 100%
rename from doc/quickstart/config_build.rst
rename to Documentation/quickstart/config_build.rst
diff --git a/doc/quickstart/index.rst b/Documentation/quickstart/index.rst
similarity index 100%
rename from doc/quickstart/index.rst
rename to Documentation/quickstart/index.rst
diff --git a/doc/quickstart/organization.rst b/Documentation/quickstart/organization.rst
similarity index 100%
rename from doc/quickstart/organization.rst
rename to Documentation/quickstart/organization.rst
diff --git a/doc/reference/index.rst b/Documentation/reference/index.rst
similarity index 100%
rename from doc/reference/index.rst
rename to Documentation/reference/index.rst
diff --git a/doc/reference/os/addrenv.rst b/Documentation/reference/os/addrenv.rst
similarity index 100%
rename from doc/reference/os/addrenv.rst
rename to Documentation/reference/os/addrenv.rst
diff --git a/doc/reference/os/app_vs_os.rst b/Documentation/reference/os/app_vs_os.rst
similarity index 100%
rename from doc/reference/os/app_vs_os.rst
rename to Documentation/reference/os/app_vs_os.rst
diff --git a/doc/reference/os/arch.rst b/Documentation/reference/os/arch.rst
similarity index 100%
rename from doc/reference/os/arch.rst
rename to Documentation/reference/os/arch.rst
diff --git a/doc/reference/os/board.rst b/Documentation/reference/os/board.rst
similarity index 100%
rename from doc/reference/os/board.rst
rename to Documentation/reference/os/board.rst
diff --git a/doc/reference/os/boardctl.rst b/Documentation/reference/os/boardctl.rst
similarity index 100%
rename from doc/reference/os/boardctl.rst
rename to Documentation/reference/os/boardctl.rst
diff --git a/doc/reference/os/conventions.rst b/Documentation/reference/os/conventions.rst
similarity index 100%
rename from doc/reference/os/conventions.rst
rename to Documentation/reference/os/conventions.rst
diff --git a/doc/reference/os/index.rst b/Documentation/reference/os/index.rst
similarity index 100%
rename from doc/reference/os/index.rst
rename to Documentation/reference/os/index.rst
diff --git a/doc/reference/os/iob.rst b/Documentation/reference/os/iob.rst
similarity index 100%
rename from doc/reference/os/iob.rst
rename to Documentation/reference/os/iob.rst
diff --git a/doc/reference/os/led.rst b/Documentation/reference/os/led.rst
similarity index 100%
rename from doc/reference/os/led.rst
rename to Documentation/reference/os/led.rst
diff --git a/doc/reference/os/nuttx.rst b/Documentation/reference/os/nuttx.rst
similarity index 100%
rename from doc/reference/os/nuttx.rst
rename to Documentation/reference/os/nuttx.rst
diff --git a/doc/reference/os/paging.rst b/Documentation/reference/os/paging.rst
similarity index 100%
rename from doc/reference/os/paging.rst
rename to Documentation/reference/os/paging.rst
diff --git a/doc/reference/os/shm.rst b/Documentation/reference/os/shm.rst
similarity index 100%
rename from doc/reference/os/shm.rst
rename to Documentation/reference/os/shm.rst
diff --git a/doc/reference/os/smp.rst b/Documentation/reference/os/smp.rst
similarity index 100%
rename from doc/reference/os/smp.rst
rename to Documentation/reference/os/smp.rst
diff --git a/doc/reference/os/time_clock.rst b/Documentation/reference/os/time_clock.rst
similarity index 100%
rename from doc/reference/os/time_clock.rst
rename to Documentation/reference/os/time_clock.rst
diff --git a/doc/reference/os/wqueue.rst b/Documentation/reference/os/wqueue.rst
similarity index 100%
rename from doc/reference/os/wqueue.rst
rename to Documentation/reference/os/wqueue.rst
diff --git a/doc/reference/user/01_task_control.rst b/Documentation/reference/user/01_task_control.rst
similarity index 100%
rename from doc/reference/user/01_task_control.rst
rename to Documentation/reference/user/01_task_control.rst
diff --git a/doc/reference/user/02_task_scheduling.rst b/Documentation/reference/user/02_task_scheduling.rst
similarity index 100%
rename from doc/reference/user/02_task_scheduling.rst
rename to Documentation/reference/user/02_task_scheduling.rst
diff --git a/doc/reference/user/03_task_control.rst b/Documentation/reference/user/03_task_control.rst
similarity index 100%
rename from doc/reference/user/03_task_control.rst
rename to Documentation/reference/user/03_task_control.rst
diff --git a/doc/reference/user/04_message_queue.rst b/Documentation/reference/user/04_message_queue.rst
similarity index 100%
rename from doc/reference/user/04_message_queue.rst
rename to Documentation/reference/user/04_message_queue.rst
diff --git a/doc/reference/user/05_counting_semaphore.rst b/Documentation/reference/user/05_counting_semaphore.rst
similarity index 100%
rename from doc/reference/user/05_counting_semaphore.rst
rename to Documentation/reference/user/05_counting_semaphore.rst
diff --git a/doc/reference/user/06_clocks_timers.rst b/Documentation/reference/user/06_clocks_timers.rst
similarity index 100%
rename from doc/reference/user/06_clocks_timers.rst
rename to Documentation/reference/user/06_clocks_timers.rst
diff --git a/doc/reference/user/07_signals.rst b/Documentation/reference/user/07_signals.rst
similarity index 100%
rename from doc/reference/user/07_signals.rst
rename to Documentation/reference/user/07_signals.rst
diff --git a/doc/reference/user/08_pthread.rst b/Documentation/reference/user/08_pthread.rst
similarity index 100%
rename from doc/reference/user/08_pthread.rst
rename to Documentation/reference/user/08_pthread.rst
diff --git a/doc/reference/user/09_env_vars.rst b/Documentation/reference/user/09_env_vars.rst
similarity index 100%
rename from doc/reference/user/09_env_vars.rst
rename to Documentation/reference/user/09_env_vars.rst
diff --git a/doc/reference/user/10_filesystem.rst b/Documentation/reference/user/10_filesystem.rst
similarity index 100%
rename from doc/reference/user/10_filesystem.rst
rename to Documentation/reference/user/10_filesystem.rst
diff --git a/doc/reference/user/11_network.rst b/Documentation/reference/user/11_network.rst
similarity index 100%
rename from doc/reference/user/11_network.rst
rename to Documentation/reference/user/11_network.rst
diff --git a/doc/reference/user/12_shared_memory.rst b/Documentation/reference/user/12_shared_memory.rst
similarity index 100%
rename from doc/reference/user/12_shared_memory.rst
rename to Documentation/reference/user/12_shared_memory.rst
diff --git a/doc/reference/user/index.rst b/Documentation/reference/user/index.rst
similarity index 100%
rename from doc/reference/user/index.rst
rename to Documentation/reference/user/index.rst
diff --git a/doc/reference/user/structures.rst b/Documentation/reference/user/structures.rst
similarity index 100%
rename from doc/reference/user/structures.rst
rename to Documentation/reference/user/structures.rst
diff --git a/doc/releases/index.rst b/Documentation/releases/index.rst
similarity index 100%
rename from doc/releases/index.rst
rename to Documentation/releases/index.rst
diff --git a/doc/requirements.txt b/Documentation/requirements.txt
similarity index 100%
rename from doc/requirements.txt
rename to Documentation/requirements.txt
diff --git a/doc/substitutions.rst b/Documentation/substitutions.rst
similarity index 100%
rename from doc/substitutions.rst
rename to Documentation/substitutions.rst
diff --git a/doc/_static/favicon.ico b/doc/_static/favicon.ico
deleted file mode 100644
index 2563e58..0000000
Binary files a/doc/_static/favicon.ico and /dev/null differ
[incubator-nuttx] 11/17: add basic documentation contributing
guidelines
Posted by bt...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
btashton pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
commit 3f723a247d49099595d0bb9756277259f56deb8a
Author: Matias N <ma...@protobits.dev>
AuthorDate: Sat Aug 15 22:28:02 2020 -0300
add basic documentation contributing guidelines
---
Documentation/contributing/documentation.rst | 326 ++++++++++++++-------------
1 file changed, 168 insertions(+), 158 deletions(-)
diff --git a/Documentation/contributing/documentation.rst b/Documentation/contributing/documentation.rst
index 0e2e90d..de92c16 100644
--- a/Documentation/contributing/documentation.rst
+++ b/Documentation/contributing/documentation.rst
@@ -1,170 +1,180 @@
-.. include:: /substitutions.rst
-
-.. note:: This is a first version of the document, will be updated once new documentation
- system is in place.
-
+=============
Documentation
=============
-The Apache NuttX Documentation is made using the
-`Sphinx documentation system <https://www.sphinx-doc.org/en/master/>`_. Sphinx documentation
-is written in `ReStructured Text <https://docutils.sourceforge.io/rst.html>`_ (RST). RST is
-the format used for `Python documentation <https://docs.python.org/3/>`_ and is also used
-in many other projects.
-
-Contributions and fixes to the Apache NuttX Companion are encouraged and welcome. Here's how to do
-it.
-
-#. Fork the Apache NuttX Documentation Repository
-
- Visit this link and hit the Fork button in the upper right of the page:
-
- * `NuttX (v01d's fork) <https://github.com/v01d/incubator-nuttx/>`_
-
- |br|
-
-#. Clone the Forked Repository
-
- Click the "Clone or Download" button and copy the clone URL. Then do this:
-
- .. code-block:: bash
-
- $ git clone <CLONE-URL-THAT-YOU-COPIED>
-
-#. Install Sphinx
-
- On the command line, change directories to the newly-downloaded repository directory:
-
- .. code-block:: bash
-
- $ cd incubator-nuttx
- $ # install pyenv
- $ curl -L https://github.com/pyenv/pyenv-installer/raw/master/bin/pyenv-installer | bash
- $ # install python
- $ pyenv install 3.7.3
- $ pyenv local 3.7.3
- $ # install pipenv
- $ pip install pipenv
- $ # install sphinx and related software
- $ pipenv install
- $ # activate the virtual environent
- $ pipenv shell
-
-#. Build the HTML Documentation Locally
-
- .. code-block:: bash
-
- $ cd docs
- $ make html
- Running Sphinx v2.4.1
- making output directory... done
- building [mo]: targets for 0 po files that are out of date
- building [html]: targets for 12 source files that are out of date
- updating environment: [new config] 12 added, 0 changed, 0 removed
- reading sources... [100%] user/simulator
- looking for now-outdated files... none found
- pickling environment... done
- checking consistency... done
- preparing documents... done
- writing output... [100%] user/simulator
- generating indices... genindexdone
- writing additional pages... searchdone
- copying static files... ... done
- copying extra files... done
- dumping search index in English (code: en)... done
- dumping object inventory... done
- build succeeded.
-
- The HTML pages are in ``_build/html``.
-
-#. Check Out a New Branch
-
- .. code-block:: bash
-
- $ git checkout -b feature/my-branch
-
-#. Make Your Changes
-
- .. code-block:: bash
-
- $ vim user/intro.rst # or use the editor of your choice
- # on whatever file you want to change
-
-#. Rebuild the HTML Documentation
-
- .. code-block:: bash
-
- $ make html
-
-#. View the Documentation in a Web Browser
-
- You can open the file ``docs/_build/html/index.html``.
- |br|
- |br|
-
-#. Iterate
-
- Repeat Steps 6, 7, and 8 until you're happy with the result.
- |br|
- |br|
-
-#. Commit the Changes
-
- .. code-block:: bash
-
- $ git add introduction/main.rst # or whatever files you changed
- $ git commit
-
-#. Push to Your Branch
-
- .. code-block:: bash
-
- $ git push
-
-#. Submit Your Pull Request
-
- Go to the `Apache NuttX (v01d's fork) <https://github.com/v01d/incubator-nuttx/>`_ page
- on Github and click the "Pull Request" button. See Github's `Creating a Pull Request
- <https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request>`__
- page for more info.
-
- Use this template for the Pull Request description text:
-
- ::
-
- ### Summary
- ### Impact
- ### Limitations / TODO
- ### Detail
- ### Testing
- ### How To Verify
+The Apache NuttX Documentation is built using the
+`Sphinx documentation system <https://www.sphinx-doc.org/en/master/>`_. Documentation
+is written in `ReStructured Text <https://docutils.sourceforge.io/rst.html>`_ (RST),
+with Sphinx-specific directives. RST is the format used for
+`Python documentation <https://docs.python.org/3/>`_ and is also used in many other projects.
+Using Sphinx, the RST files are rendered into HTML files that can be read in your browser.
+
+Building
+========
+
+To render the Documentation locally, you should clone the NuttX main repository, and
+go into ``Documentation`` directory. Then,
+
+ 1. Install sphinx and other dependencies. You can do this in one of two ways:
+
+ * **Fast and easy**:
+
+ .. code-block:: console
+
+ pip3 install -r requirements.txt
+
+ * **Slower but cleaner**:
+
+ .. code-block:: console
+
+ $ # install pyenv
+ $ curl -L https://github.com/pyenv/pyenv-installer/raw/master/bin/pyenv-installer | bash
+ $ # install python
+ $ pyenv install 3.7.3
+ $ pyenv local 3.7.3
+ $ # install pipenv
+ $ pip install pipenv
+ $ # install sphinx and related software
+ $ pipenv install
+ $ # activate the virtual environent
+ $ pipenv shell
+
+ .. todo:: check that Pipfile.lock is up to date w.r.t. requirements.txt
+
+ 2. Build documentation:
+
+ .. code-block:: console
+
+ $ make html
+
+ The resulting HTMLs will end up under ``_build/html``. You can open your browser at the root with:
+
+ .. code-block:: console
+
+ $ xdg-open _build/html/index.html
+
+Contributing
+============
+
+Contributions to documentation are appreciated. These can be as simple as fixing a typo or formatting issues to more involved
+changes such as documenting parts of NuttX which are not yet covered or even writing guides for other users.
+
+The contribution workflow is the same as for the code, so check the :doc:`/contributing/workflow` to understand
+how your changes should be upstreamed.
+
+Writing ReStructure Text with Sphinx
+====================================
+
+The following links can be used to learn about RST syntax and about Sphinx specific directives. Note that
+sometimes Sphinx's approach is used over standard RST since it is more powerful (e.g. standard linking vs Sphinx
+``:ref:`` which can be used across files, ``code-block`` directive vs ``::`` which allows specifying highlight language, etc.):
+
+ * `Sphinx documentation system <https://www.sphinx-doc.org/en/master/>`__
+ * `ReStructured Text documentation <https://docutils.sourceforge.io/rst.html>`__
+ * `Sphinx Guide to ReStructured Text <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__
+ * `Restructured Text cheat sheet <https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html>`__
+
+Documentation Conventions
+=========================
+
+While RST/Sphinx provide many ways to do things, it is best to follow a given convention to mantain consistency and avoid
+pitfalls. For this reason, documentation changes should follow the following set of conventions.
+
+Indentation
+-----------
+
+Child blocks should be indented two-spaces. This includes itemizations/enumerations.
+
+Headings
+--------
+
+Three levels of headings should be used in general. The style used to mark sections is based around ``=`` and ``-``.
+Sections should look like this:
+
+.. code-block:: RST
+
+ =================
+ Top Level Heading
+ =================
+
+ Subsection
+ ==========
+
+ Subsubsection
+ -------------
+
+Code
+----
+
+Code should be documented using the `C domain <https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-c-domain>`_.
+This means for example that a function should be documented as:
+
+.. code-block:: RST
+
+ .. c:function:: bool myfunction(int arg1, int arg2)
+
+ Here the function should be described
+
+ :param arg1: Description of arg1
+ :param arg2: Description of arg2
+
+ :return: Description of return value
+
+To document a piece of code, use a ``code-block`` `directive <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block>`_, specifying the highlight language. If the block is not of code but some verbatim piece of text,
+it is acceptable to use RST standard `::`. This is specially useful and compact when used in the following mode:
+
+.. code-block:: RST
+
+ The text file should have the following content::
+
+ Line1
+ Line2
+ Line3
+
+Linking
+-------
+
+To generate internal links, Sphinx's `roles <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role>`_ should
+be used. So, use ``:ref:`` instead of standard RST syntax like ```link <target>`_`` for internal links.
+
+Moreover, sphinx is configured to use `autosectionlabel <https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html#confval-autosectionlabel_prefix_document>`_ extension. This means that sections will automatically get a label that can be linked with the
+`:ref:`. For example:
+
+.. code-block:: RST
+
+ This is a Section
+ =================
+
+ :ref:`This is a Section` is a link to this very same section.
+
+If the target is in a different file, you can refer it with: ``:ref:`link text </pathtorst:Section Name>```.
- Fill out the sections describing your changes. The summary should be a concise bulleted
- list.
+Notes and TODOS
+---------------
- The ``How To Verify`` section is only needed if you change how the project is built or
- add some other programs or scripts.
- |br|
- |br|
+Use RST `admonitions <https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions>`_ to highlight things from the text,
+such as a note that should be prominently displayed.
-#. Make Changes If Requested
+In case you need to leave a TODO note in the documentation to point that something needs to be improved, use a ``todo`` admonition,
+which is available via the ``sphinx.ext.todo`` extension. This will let the reader of the documentation also know that the documentation
+is not yet finished somewhere and may further motivate a contribution.
- When you submit your Pull Request, the Apache NuttX Documentation team will review the changes,
- and may request that you modify your submission. Please work with them to get your
- changes accepted.
- |br|
- |br|
+Tips
+====
-#. You're Done!
+Spacing
+-------
- Feel good that you've made Apache NuttX documentation better for yourself and others. You've
- just made the world a better place!
+If you are getting formatting errors, be sure to provide the appropiate spacing between a directive and its content.
+Generally, you should follow this format:
-Sphinx Resources
-----------------
+.. code-block:: RST
-* `Sphinx documentation system <https://www.sphinx-doc.org/en/master/>`__
-* `ReStructured Text documentation <https://docutils.sourceforge.io/rst.html>`__
-* `Sphinx Guide to ReStructured Text <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__
-* `Restructured Text cheat sheet <https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html>`__
+ .. directive::
+
+ child content
+
+ non-child content which appears after previous directive
+
+Note the line between directive and content and the indentation.
[incubator-nuttx] 03/17: convert acronyms.txt to glossary.rst
Posted by bt...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
btashton pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
commit 71021575fc0d040a5c7a480c031b83173fad0807
Author: Matias N <ma...@protobits.dev>
AuthorDate: Fri Aug 14 15:26:05 2020 -0300
convert acronyms.txt to glossary.rst
---
Documentation/acronyms.txt | 121 ---------------
doc/glossary.rst | 368 +++++++++++++++++++++++++++++++++++++++++++++
doc/index.rst | 1 +
3 files changed, 369 insertions(+), 121 deletions(-)
diff --git a/Documentation/acronyms.txt b/Documentation/acronyms.txt
deleted file mode 100644
index 20448d7..0000000
--- a/Documentation/acronyms.txt
+++ /dev/null
@@ -1,121 +0,0 @@
-6LoWPAN IPv6 over Low power Wireless Personal Area Networks
-ACM Abstract Control Model (USB)
-ADC Analog to Digital Conversion
-AIC Advanced Interrupt Controller (Atmel SAM)
-ARP Address Resolution Protocol (networking)
-BCH Block to Character
-BINFMT Binary Format (Dynamic Loader)
-BLE Bluetooth4 Low Energy
-BPP Bits Per Pixel
-CAN Controller Area Network
-CDC Communication Device Class (USB)
-CP15 Coprocessor 15 (ARM)
-CPU Central Processing Unit
-DEVIF Device Interface (networking)
-DAC Digital to Analog Conversion
-DCD Device Controller Driver (USB)
-DCMI Digital Camera Interface
-DEV Device
-DHCP Dynamic Host Configuration Protocol
-DHCPC DHCP Client
-DHCPD DHCP Daemon (server)
-DMA Direct Memory Access (hardware)
-DMAC DMA Controller (hardware)
-DNS Domain Name Service (or System or Server) (networking)
-DRAM Dynamic RAM
-EABI Embedded-Application Binary Interface
-EEPROM Electrically Erasable Programmable Read-Only Memory
-EMAC Ethernet Media Access Controller (networking)
-EPROM Erasable Programmable Read-Only Memory
-FAT File Allocation Table (file systems)
-FB Frame Buffer (video interface)
-FSMC Flexible Static Memory Controller (STM32)
-FTL FLASH Translation Layer (MTD)
-GPIO General Purpose Input/Output
-GMAC Gigabit Media Access Controller (networking)
-HCD Host Controller Driver (USB)
-HSMCI High Speed Memory Card Interface (Atmel)
-I/O Input/Output
-IOCTL Input/Output Control
-IoT Internet of Things (marketing BS)
-IP Internet Protocol (version 4?) (networking)
-IPv4 Internet Protocol Version 4 (networking)
-IPv6 Internet Protocol Version 6 (networking)
-IRQ Interrupt Request (hardware)
-I2C Inter-Integrated Circuit (serial interface)
-I2S Inter IC Sound (serial interface)
-ICMP Internet Control Message Protocol (networking)
-ICMPv6 Internet Control Message Protocol for IPv6 (networking)
-IGMP Internet Group Multicast Protocol (networking)
-IOB I/O Buffer (networking)
-LAN Local Area Network (networking)
-LCD Liquid Crystal Display
-LIBC The "C" Library
-LIBM The "C" Math Library
-LP Low Power
-MAC Media Access Control (networking, OSI model)
-MCI Memory Card Interface
-MCU Microcontroller Unit
-MM Memory Management/Manager
-MMAP Memory Map
-MMC Multi-Media Card
-MMCSD See MMC and SD
-MMU Memory Management Unit
-MPU Memory Protection Unit
-MTD Memory Technology Device
-NFS Network File System
-NETDB Network Data Base (networking)
-NETDEV Network Device (networking)
-NSH NuttShell
-NVM Non-Volatile Memory
-NTP Network Time Protocol (networking)
-NX NuttX, the NuttX Graphics server (graphics)
-NXFFS NuttX Flash File System
-NXWM The NuttX Window Manager (graphics)
-PID Process ID (operating systems)
- Peripheral ID (Atmel SAM)
-PROM Programmable Read-Only Memory
-OS Operating System
-OTG On-The-Go (USB)
-OTP One-Time Programmable
-POR Power-On Reset
-PWM Pulse Width Modulation
-PKT "Raw" Packet socket (networking)
-PRNG Pseudo-Random Number Generator
-QSPI Quad SPI
-RAM Random Access Memory
-RNG Random Number Generator
-ROM Read-Only Memory
-RNDIS Remote Network Driver Interface Specification (USB, networking)
-RTC Real Time Clock
-RTCC Real Time Clock/Calendar
-RTOS Real Time Operating System
-SAIC Secure Advanced Interrupt Controller (Atmel SAM)
-SCI Serial Communications Interface
-SD Secure Digital (flash memory)
-SDHC Secure Digital High Capacity (flash memory),
- Secure Digital Host Controller (hardware)
-SDIO Secure Digital I/O
-SDRAM Synchronous Dynamic Random Access Memory
-SLCD Segment Liquid Crystal Display
-SMC Static Memory Controller (hardware)
-SPI Serial Peripheral Interface
-SPRNG Scalable Parallel Random Number Generator
-SRAM Static RAM
-SYSLOG System Log
-TCP Transmission Control Protocol (networking)
-TRNG True Random Number Generator
-TSC Touchscreen Controller
-TUN network TUNnel
-TWI Two-Wire Interface (serial interface)
-UDP User Datagram Protocol (networking)
-UART Universal Asynchronous Receiver/Transmitter
-USB Universal Serial Bus (serial interface)
-USART Universal Synchronous/Asynchronous Receiver/Transmitter
-VNC Virtual Network Computing (graphics, remote desktop)
-WAN Wide Area Network (networking)
-WLAN Wireless Local Area Network (networking)
-WPAN Wireless Personal Area Network (networking)
-WDT Watchdog Timer (hardware)
-XIP eXecute In Place
-XDMAC Extended DMA Controller (Atmel)
diff --git a/doc/glossary.rst b/doc/glossary.rst
new file mode 100644
index 0000000..15d5e74
--- /dev/null
+++ b/doc/glossary.rst
@@ -0,0 +1,368 @@
+========
+Glossary
+========
+
+.. glossary::
+
+ 6LoWPAN
+ IPv6 over Low power Wireless Personal Area Networks
+
+ ACM
+ Abstract Control Model (USB)
+
+ ADC
+ Analog to Digital Conversion
+
+ AIC
+ Advanced Interrupt Controller (Atmel SAM)
+
+ ARP
+ Address Resolution Protocol (networking)
+
+ BCH
+ Block to Character
+
+ BINFMT
+ Binary Format (Dynamic Loader)
+
+ BLE
+ Bluetooth4 Low Energy
+
+ BPP
+ Bits Per Pixel
+
+ CAN
+ Controller Area Network
+
+ CDC
+ Communication Device Class (USB)
+
+ CP15
+ Coprocessor 15 (ARM)
+
+ CPU
+ Central Processing Unit
+
+ DEVIF
+ Device Interface (networking)
+
+ DAC
+ Digital to Analog Conversion
+
+ DCD
+ Device Controller Driver (USB)
+
+ DCMI
+ Digital Camera Interface
+
+ DEV
+ Device
+
+ DHCP
+ Dynamic Host Configuration Protocol
+
+ DHCPC
+ DHCP Client
+
+ DHCPD
+ DHCP Daemon (server)
+
+ DMA
+ Direct Memory Access (hardware)
+
+ DMAC
+ DMA Controller (hardware)
+
+ DNS
+ Domain Name Service (or System or Server) (networking)
+
+ DRAM
+ Dynamic RAM
+
+ EABI
+ Embedded-Application Binary Interface
+
+ EEPROM
+ Electrically Erasable Programmable Read-Only Memory
+
+ EMAC
+ Ethernet Media Access Controller (networking)
+
+ EPROM
+ Erasable Programmable Read-Only Memory
+
+ FAT
+ File Allocation Table (file systems)
+
+ FB
+ Frame Buffer (video interface)
+
+ FSMC
+ Flexible Static Memory Controller (STM32)
+
+ FTL
+ FLASH Translation Layer (MTD)
+
+ GPIO
+ General Purpose Input/Output
+
+ GMAC
+ Gigabit Media Access Controller (networking)
+
+ HCD
+ Host Controller Driver (USB)
+
+ HSMCI
+ High Speed Memory Card Interface (Atmel)
+
+ I/O Input/Output
+
+ IOCTL
+ Input/Output Control
+
+ IoT
+ Internet of Things (marketing BS)
+
+ IP
+ Internet Protocol (version 4?) (networking)
+
+ IPv4
+ Internet Protocol Version 4 (networking)
+
+ IPv6
+ Internet Protocol Version 6 (networking)
+
+ IRQ
+ Interrupt Request (hardware)
+
+ I2C
+ Inter-Integrated Circuit (serial interface)
+
+ I2S
+ Inter IC Sound (serial interface)
+
+ ICMP
+ Internet Control Message Protocol (networking)
+
+ ICMPv6
+ Internet Control Message Protocol for IPv6 (networking)
+
+ IGMP
+ Internet Group Multicast Protocol (networking)
+
+ IOB
+ I/O Buffer (networking)
+
+ LAN
+ Local Area Network (networking)
+
+ LCD
+ Liquid Crystal Display
+
+ LIBC
+ The "C" Library
+
+ LIBM
+ The "C" Math Library
+
+ LP
+ Low Power
+
+ MAC
+ Media Access Control (networking, OSI model)
+
+ MCI
+ Memory Card Interface
+
+ MCU
+ Microcontroller Unit
+
+ MM
+ Memory Management/Manager
+
+ MMAP
+ Memory Map
+
+ MMC
+ Multi-Media Card
+
+ MMCSD
+ See MMC and SD
+
+ MMU
+ Memory Management Unit
+
+ MPU
+ Memory Protection Unit
+
+ MTD
+ Memory Technology Device
+
+ NFS
+ Network File System
+
+ NETDB
+ Network Data Base (networking)
+
+ NETDEV
+ Network Device (networking)
+
+ NSH
+ NuttShell
+
+ NVM
+ Non-Volatile Memory
+
+ NTP
+ Network Time Protocol (networking)
+
+ NX
+ NuttX, the NuttX Graphics server (graphics)
+
+ NXFFS
+ NuttX Flash File System
+
+ NXWM
+ The NuttX Window Manager (graphics)
+
+ PID
+ Process ID (operating systems)
+
+ Peripheral
+ ID (Atmel SAM)
+
+ PROM
+ Programmable Read-Only Memory
+
+ OS
+ Operating System
+
+ OTG
+ On-The-Go (USB)
+
+ OTP
+ One-Time Programmable
+
+ POR
+ Power-On Reset
+
+ PWM
+ Pulse Width Modulation
+
+ PKT
+ "Raw" Packet socket (networking)
+
+ PRNG
+ Pseudo-Random Number Generator
+
+ QSPI
+ Quad SPI
+
+ RAM
+ Random Access Memory
+
+ RNG
+ Random Number Generator
+
+ ROM
+ Read-Only Memory
+
+ RNDIS
+ Remote Network Driver Interface Specification (USB, networking)
+
+ RTC
+ Real Time Clock
+
+ RTCC
+ Real Time Clock/Calendar
+
+ RTOS
+ Real Time Operating System
+
+ SAIC
+ Secure Advanced Interrupt Controller (Atmel SAM)
+
+ SCI
+ Serial Communications Interface
+
+ SD
+ Secure Digital (flash memory)
+
+ SDHC
+ Secure Digital High Capacity (flash memory),
+
+ Secure
+ Digital Host Controller (hardware)
+
+ SDIO
+ Secure Digital I/O
+
+ SDRAM
+ Synchronous Dynamic Random Access Memory
+
+ SLCD
+ Segment Liquid Crystal Display
+
+ SMC
+ Static Memory Controller (hardware)
+
+ SPI
+ Serial Peripheral Interface
+
+ SPRNG
+ Scalable Parallel Random Number Generator
+
+ SRAM
+ Static RAM
+
+ SYSLOG
+ System Log
+
+ TCP
+ Transmission Control Protocol (networking)
+
+ TRNG
+ True Random Number Generator
+
+ TSC
+ Touchscreen Controller
+
+ TUN
+ network TUNnel
+
+ TWI
+ Two-Wire Interface (serial interface)
+
+ UDP
+ User Datagram Protocol (networking)
+
+ UART
+ Universal Asynchronous Receiver/Transmitter
+
+ USB
+ Universal Serial Bus (serial interface)
+
+ USART
+ Universal Synchronous/Asynchronous Receiver/Transmitter
+
+ VNC
+ Virtual Network Computing (graphics, remote desktop)
+
+ WAN
+ Wide Area Network (networking)
+
+ WLAN
+ Wireless Local Area Network (networking)
+
+ WPAN
+ Wireless Personal Area Network (networking)
+
+ WDT
+ Watchdog Timer (hardware)
+
+ XIP
+ eXecute In Place
+
+ XDMAC
+ Extended DMA Controller (Atmel)
+
diff --git a/doc/index.rst b/doc/index.rst
index ace3459..4b04390 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -26,5 +26,6 @@ Last Updated: |today|
guides/index.rst
releases/index.rst
contributing/index.rst
+ glossary.rst
.. include:: substitutions.rst
[incubator-nuttx] 04/17: move last content from old docs to new
docs; remove old docs
Posted by bt...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
btashton pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
commit 6d89ae8fc7668d49b90a130481eab4432d4e8120
Author: Matias N <ma...@protobits.dev>
AuthorDate: Fri Aug 14 16:50:02 2020 -0300
move last content from old docs to new docs; remove old docs
---
Documentation/.gitignore | 3 -
Documentation/NXGraphicsSubsystem.html | 4819 ------------
Documentation/NfsHowto.html | 385 -
Documentation/NuttShell.html | 6008 ---------------
Documentation/NuttX.html | 7576 ------------------
Documentation/NuttXBinfmt.html | 585 --
Documentation/NuttXDemandPaging.html | 672 --
Documentation/NuttXNxFlat.html | 765 --
Documentation/NuttxPortingGuide.html | 7273 ------------------
Documentation/NuttxUserGuide.html | 10600 --------------------------
Documentation/NxWidgets.html | 76 -
Documentation/UsbTrace.html | 453 --
Documentation/favicon.ico | Bin 3126 -> 0 bytes
Documentation/style.css | 84 -
{Documentation => doc/_static}/NuttX.png | Bin
{Documentation => doc/_static}/NuttX320.png | Bin
doc/_static/favicon.ico | Bin 4286 -> 3126 bytes
17 files changed, 39299 deletions(-)
diff --git a/Documentation/.gitignore b/Documentation/.gitignore
deleted file mode 100644
index a296626..0000000
--- a/Documentation/.gitignore
+++ /dev/null
@@ -1,3 +0,0 @@
-/TODO.txt
-/ChangeLog.txt
-/NuttXConfigVariables.*
diff --git a/Documentation/NXGraphicsSubsystem.html b/Documentation/NXGraphicsSubsystem.html
deleted file mode 100644
index b43f138..0000000
--- a/Documentation/NXGraphicsSubsystem.html
+++ /dev/null
@@ -1,4819 +0,0 @@
-<html>
-<head>
-<title>NX Graphics Subsystem</title>
-<meta name="author" content="Gregory Nutt">
-<link rel="stylesheet" href="style.css">
-</head>
-
-<body background="backgd.gif">
-<hr><hr>
-<table width ="100%">
- <tr align="center" bgcolor="#e4e4e4">
- <td>
- <h1><big><font color="#3c34ec">
- <i>NX Graphics Subsystem</i>
- </font></big></h1>
- <p>Last Updated: August 8, 2019</p>
- </td>
- </tr>
-</table>
-<hr><hr>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <h1>Table of Contents</h1>
- </td>
- </tr>
-</table>
-
-<table width="100%">
-<tr>
- <td align="left" valign="top">
- <p>
- <big><b>1.0</b> <a href="#Introduction">Introduction</a></big>
- </p>
- <ul>
- <p>
- <i><b>1.1</b> <a href="#Overview">Overview</a><br></i>
- <i><b>1.2</b> <a href="#Objectives">Objectives</a></i><br>
- <i><b>1.3</b> <a href="#Organization">Organization</a></i>
- </p>
- <p>
- <ul>
- <i>1.3.1 <a href="#nxgl1">NX Graphics Library (<code>NXGL</code>)</a></i><br>
- <i>1.3.2 <a href="#nx1">NX (NXSU and NXMU)</a></i><br>
- <i>1.3.3 <a href="#nxtk1">NX Tool Kit (<code>NXTK</code>)</a></i><br>
- <i>1.3.4 <a href="#nxfonts1">NX Fonts Support (<code>NXFONTS</code>)</a></i><br>
- <i>1.3.5 <a href="#nxwidgets1">NX Widgets (<code>NxWidgets</code>)</a></i><br>
- <i>1.3.6 <a href="#nxterm1">NX Terminal Driver (<code>NxTerm</code>)</a></i>
- </ul>
- </p>
- </ul>
- <p>
- <big><b>2.0</b> <a href="#nxapis">NX User APIs</a></big>
- </p>
- <ul>
- <p>
- <i><b>2.1</b> <a href="#nxheaders">NX Header Files</a></i><br>
- <i><b>2.2</b> <a href="#nxgl2">NX Graphics Library (<code>NXGL</code>)</a></i>
- </p>
- <p>
- <ul>
- <i>2.2.1 <a href="#nxgltypes">NXGL Types</a></i><br>
- <i>2.2.1 <a href="#nxglrgb2yuv"><code>nxgl_rgb2yuv()</code></a></i><br>
- <i>2.2.2 <a href="#nxglyuv2rgb"><code>nxgl_yuv2rgb()</code></a></i><br>
- <i>2.2.3 <a href="#nxglrectcopy"><code>nxgl_rectcopy()</code></a></i><br>
- <i>2.2.4 <a href="#nxglrectoffset"><code>nxgl_rectoffset()</code></a></i><br>
- <i>2.2.5 <a href="#nxglvectoradd"><code>nxgl_vectoradd()</code></a></i><br>
- <i>2.2.6 <a href="#nxglvectorsubtract"><code>nxgl_vectorsubtract()</code></a></i><br>
- <i>2.2.7 <a href="#nxglrectintersect"><code>nxgl_rectintersect()</code></a></i><br>
- <i>2.2.8 <a href="#nxglrectunion"><code>nxgl_rectunion()</code></a></i><br>
- <i>2.2.9 <a href="#nxglnonintersecting"><code>nxgl_nonintersecting()</code></a></i><br>
- <i>2.2.10 <a href="#nxglrectoverlap"><code>nxgl_rectoverlap()</code></a></i><br>
- <i>2.2.11 <a href="#nxglrectinside"><code>nxgl_rectinside()</code></a></i><br>
- <i>2.2.12 <a href="#nxglrectsize"><code>nxgl_rectsize()</code></a></i><br>
- <i>2.2.13 <a href="#nxglnullrect"><code>nxgl_nullrect()</code></a></i><br>
- <i>2.2.14 <a href="#nxglrunoffset"><code>nxgl_runoffset()</code></a></i><br>
- <i>2.2.15 <a href="#nxglruncopy"><code>nxgl_runcopy()</code></a></i><br>
- <i>2.2.16 <a href="#nxgltrapoffset"><code>nxgl_trapoffset()</code></a></i><br>
- <i>2.2.17 <a href="#nxgltrapcopy"><code>nxgl_trapcopy()</code></a></i><br>
- <i>2.2.18 <a href="#nxglcolorcopy"><code>nxgl_colorcopy</code></a></i><br>
- <i>2.2.19 <a href="#nxglsplitline"><code>nxgl_splitline()</code></a></i><br>
- <i>2.2.20 <a href="#nxglcirclepts"><code>nxgl_circlepts()</code></a></i><br>
- <i>2.2.21 <a href="#nxglcircletraps"><code>nxgl_circletraps()</code></a></i>
- </ul>
- </p>
- <p>
- <i><b>2.3</b> <a href="#nx2">NX</a></i>
- </p>
- <p>
- <ul>
- <i>2.3.1 <a href="#nxppdefs">Pre-Processor Definitions</a></i><br>
- <i>2.3.2 <a href="#nxtypes">NX Types</a></i><br>
- <i>2.3.3 <a href="#startingnx">Starting the NX Server</a></i>
- <p>
- <ul>
- <i>2.3.3.1 <a href="#nxstart"><code>nxmu_start()</code></a></i><br>
- <i>2.3.3.2 <a href="#boardctl"><code>boardctl()</code></a></i><br>
- </ul>
- <p>
- <i>2.3.4 <a href="#nxcallbacks">NX Server Callbacks</a></i>
- <p>
- <ul>
- <i>2.3.4.1 <a href="#nxcbredraw"><code>redraw()</code></a></i><br>
- <i>2.3.4.2 <a href="#nxcbposition"><code>position()</code></a></i><br>
- <i>2.3.4.3 <a href="#nxcbmousein"><code>mousein()</code></a></i><br>
- <i>2.3.4.4 <a href="#nxcbkbdin"><code>kbdin()</code></a></i><br>
- <i>2.3.4.5 <a href="#nxcbevent"><code>event()</code></a></i>
- </ul>
- <p>
- <i>2.3.5 <a href="#nxruninstance"><code>nx_runinstance()</code> (and <code>nx_run()<code> macro)</a></i><br>
- <i>2.3.6 <a href="#nxconnectinstance"><code>nx_connectinstance()</code> (and <code>nx_connect()</code> macro)</a></i><br>
- <i>2.3.7 <a href="#nxdisconnect"><code>nx_disconnect()</code></a></i><br>
- <i>2.3.8 <a href="#nxeventhandler"><code>nx_eventhandler()</code></a></i><br>
- <i>2.3.9 <a href="#nxeventnotify"><code>nx_eventnotify()</code></a></i><br>
- <i>2.3.10 <a href="#nxblock"><code>nx_block()</code></a></i><br>
- <i>2.3.11 <a href="#nxsynch"><code>nx_synch()</code></a></i><br>
- <i>2.3.12 <a href="#nxopenwindow"><code>nx_openwindow()</code></a></i><br>
- <i>2.3.13 <a href="#nxclosewindow"><code>nx_closewindow()</code></a></i><br>
- <i>2.3.14 <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a></i><br>
- <i>2.3.15 <a href="#nxreleasebkgd"><code>nx_releasebkgd()</code></a></i><br>
- <i>2.3.16 <a href="#nxgetposition"><code>nx_getposition()</code></a></i><br>
- <i>2.3.17 <a href="#nxsetposition"><code>nx_setposition()</code></a></i><br>
- <i>2.3.18 <a href="#nxsetsize"><code>nx_setsize()</code></a></i><br>
- <i>2.3.19 <a href="#nxraise"><code>nx_raise()</code></a></i><br>
- <i>2.3.20 <a href="#nxlower"><code>nx_lower()</code></a></i><br>
- <i>2.3.21 <a href="#nxmodal"><code>nx_modal()</code></a></i><br>
- <i>2.3.22 <a href="#nxsetvisibility"><code>nx_setvisibility()</code></a></i><br>
- <i>2.3.23 <a href="#nxishidden"><code>nx_ishidden()</code></a></i><br>
- <i>2.3.24 <a href="#nxfill"><code>nx_fill()</code></a></i><br>
- <i>2.3.25 <a href="#nxgetrectangle"><code>nx_getrectangle()</code></a></i><br>
- <i>2.3.26 <a href="#nxfilltrapezoid"><code>nx_filltrapezoid()</code></a></i><br>
- <i>2.3.27 <a href="#nxdrawline"><code>nx_drawline()</code></a></i><br>
- <i>2.3.28 <a href="#nxdrawcircle"><code>nx_drawcircle()</code></a></i><br>
- <i>2.3.29 <a href="#nxfillcircle"><code>nx_fillcircle()</code></a></i><br>
- <i>2.3.30 <a href="#nxglrgb2yuv"><code>nx_setbgcolor()</code></a></i><br>
- <i>2.3.31 <a href="#nxmove"><code>nx_move()</code></a></i><br>
- <i>2.3.32 <a href="#nxbitmap"><code>nx_bitmap()</code></a></i><br>
- <i>2.3.33 <a href="#nxkbdin"><code>nx_kbdin()</code></a></i><br>
- <i>2.3.34 <a href="#nxmousein"><code>nx_mousein()</code></a></i><br>
- </ul>
- </p>
- </td>
- <td align="left" valign="top">
- <p>
- <i><b>2.4</b> <a href="#nxtk2">NX Tool Kit (<code>NXTK</code>)</a></i>
- </p>
- <p>
- <ul>
- <i>2.4.1 <a href="#nxtktypes"><code>NXTK Types()</code></a></i><br>
- <i>2.4.2 <a href="#nxtkblock"><code>nxtk_block()</code></a></i><br>
- <i>2.4.3 <a href="#nxtksynch"><code>nxtk_synch()</code></a></i><br>
- <i>2.4.4 <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a></i><br>
- <i>2.4.5 <a href="#nxtkclosewindow"><code>nxtk_closewindow()</code></a></i><br>
- <i>2.4.6 <a href="#nxtkgetposition"><code>nxtk_getposition()</code></a></i><br>
- <i>2.4.7 <a href="#nxtksetposition"><code>nxtk_setposition()</code></a></i><br>
- <i>2.4.8 <a href="#nxtksetsize"><code>nxtk_setsize()</code></a></i><br>
- <i>2.4.9 <a href="#nxtkraise"><code>nxtk_raise()</code></a></i><br>
- <i>2.4.10 <a href="#nxtklower"><code>nxtk_lower()</code></a></i><br>
- <i>2.4.11 <a href="#nxtkmodal"><code>nxtk_modal()</code></a></i><br>
- <i>2.4.12 <a href="#nxtksetvisibility"><code>nxtk_setvisibility()</code></a></i><br>
- <i>2.4.13 <a href="#nxtkishidden"><code>nxtk_ishidden()</code></a></i><br>
- <i>2.4.14 <a href="#nxtkfillwindow"><code>nxtk_fillwindow()</code></a></i><br>
- <i>2.4.15 <a href="#nxtkgetwindow"><code>nxtk_getwindow()</code></a></i><br>
- <i>2.4.16 <a href="#nxtkfilltrapwindow"><code>nxtk_filltrapwindow()</code></a></i><br>
- <i>2.4.17 <a href="#nxtkdrawlinewindow"><code>nxtk_drawlinewindow()</code></a></i><br>
- <i>2.4.18 <a href="#nxtkdrawcirclewindow"><code>nxtk_drawcirclewindow()</code></a></i><br>
- <i>2.4.19 <a href="#nxtkfillcirclewindow"><code>nxtk_fillcirclewindow()</code></a></i><br>
- <i>2.4.20 <a href="#nxtkmovewindow"><code>nxtk_movewindow()</code></a></i><br>
- <i>2.4.21 <a href="#nxtkbitmapwindow"><code>nxtk_bitmapwindow()</code></a></i><br>
- <i>2.4.22 <a href="#nxtkopentoolbar"><code>nxtk_opentoolbar()</code></a></i><br>
- <i>2.4.23 <a href="#nxtkclosetoolbar"><code>nxtk_closetoolbar()</code></a></i><br>
- <i>2.4.24 <a href="#nxtkfilltoolbar"><code>nxtk_filltoolbar()</code></a></i><br>
- <i>2.4.25 <a href="#nxtkgettoolbar"><code>nxtk_gettoolbar()</code></a></i><br>
- <i>2.4.26 <a href="#nxtkfilltraptoolbar"><code>nxtk_filltraptoolbar()</code></a></i><br>
- <i>2.4.27 <a href="#nxtkdrawlinetoolbar"><code>nxtk_drawlinetoolbar()</code></a></i><br>
- <i>2.4.28 <a href="#nxtkdrawcircletoolbar"><code>nxtk_drawcircletoolbar()</code></a></i><br>
- <i>2.4.29 <a href="#nxtkfillcircletoolbar"><code>nxtk_fillcircletoolbar()</code></a></i><br>
- <i>2.4.30 <a href="#nxtkmovetoolbar"><code>nxtk_movetoolbar()</code></a></i><br>
- <i>2.4.31 <a href="#nxtkbitmaptoolbar"><code>nxtk_bitmaptoolbar()</code></a></i>
- </ul>
- </p>
- <p>
- <i><b>2.5</b> <a href="#nxfonts2">NX Fonts Support (<code>NXFONTS</code>)</a></i>
- </p>
- <p>
- <ul>
- <i>2.5.1 <a href="#nxfontstypes"><code>NXFONTS Types()</code></a></i><br>
- <i>2.5.2 <a href="#nxfgetfonthandle"><code>nxf_getfonthandle()</code></a></i><br>
- <i>2.5.3 <a href="#nxfgetfontset"><code>nxf_getfontset()</code></a></i><br>
- <i>2.5.4 <a href="#nxfgetbitmap"><code>nxf_getbitmap()</code></a></i><br>
- <i>2.5.5 <a href="#nxfconvertbpp"><code>nxf_convert_*bpp()</code></a></i>
- </ul>
- </p>
- <p>
- <i><b>2.6</b> <a href="#nxcursor">NX Cursor Support (<code>NXCURSOR</code>)</a></i>
- </p>
- <p>
- <ul>
- <i>2.6.1 <a href="#nxcursorenable"><code>nxcursor_enable()</code></a></i><br>
- <i>2.6.2 <a href="#nxcursorsetimage"><code>nxcursor_setimage()</code></a></i><br>
- <i>2.6.3 <a href="#nxcursorsetposition"><code>nxcursor_setposition()</code></a></i><br>
- </ul>
- </p>
- <p>
- <i><b>2.7</b> <a href="#samplecode">Sample Code</a></i>
- </p>
- </ul>
- <p>
- <big><b>Appendix A</b> <a href="#grapicsdirs"><code>graphics/</code> Directory Structure</a></big><br>
- <big><b>Appendix B</b> <a href="#nxconfigs">NX Configuration Options</a></big>
- </p>
- <p>
- <ul>
- <i><b>B.1</b> <a href="#nxgenconfig">General Configuration Settings</a></i><br>
- <i><b>B.2</b> <a href="#nxglconfig">NXGL Configuration Settings</a></i><br>
- <i><b>B.3</b> <a href="#nxconfig">NX Configuration Settings</a></i><br>
- <i><b>B.4</b> <a href="#nxmuconfig">NX Server Configuration Settings</a></i><br>
- <i><b>B.5</b> <a href="#nxtkconfig">NXTK Configuration Settings</a></i><br>
- <i><b>B.6</b> <a href="#nxfpmtsconfig">NXFONTS Configuration Settings</a></i><br>
- <i><b>B.7</b> <a href="#nxtermconfig">NxTerm Configuration Settings</a></i>
- </ul>
- </p>
- <p>
- <big><b>Appendix C</b> <a href="#installnewfonts">Installing New Fonts</a></big>
- </p>
- <p>
- <big><b>Appendix D</b> <a href="#testcoverage">NX Test Coverage</a></big>
- </p>
- <ul>
- <i><b>Table D.1:</b> <a href="#nxglibcoverage">NXGLIB API Test Coverage</a></i><br>
- <i><b>Table D.2:</b> <a href="#nxcbcoverage">NX Server Callbacks Test Coverage</a></i><br>
- <i><b>Table D.3:</b> <a href="#nxcoverage">NX API Test Coverage</a></i><br>
- <i><b>Table D.4:</b> <a href="#nxtkcoverage">NXTK API Test Coverage</a></i><br>
- <i><b>Table D.5:</b> <a href="#nxfontscoverage">NXFONTS API Test Coverage</a></i><br>
- </ul>
- </td>
- </tr>
-</table>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <h1>1.0 <a name="Introduction">Introduction</a></h1>
- </td>
- </tr>
-</table>
-
-<h2>1.1 <a name="Overview">Overview</a></h2>
-<p>
- This document describes the tiny graphics support included in NuttX.
- It includes an overview description of that graphics support, detailed
- descriptions of the NuttX graphics APIs, and discussion of code organization,
- and OS configuration options.
-</p>
-
-<center><table width="480">
- <tr>
- <td><a name="screenshot"><img src="NuttXScreenShot.jpg"></a></td>
- </tr>
- <tr>
- <td><small>Figure 1.
- This scren shot shows the final frame for the NuttX example at <code>apps/examples/nx</code>
- running on the simulated, Linux x86 platform with simulated framebuffer output to
- an X window.
- This picture shows to framed windows with (blank) toolbars.
- Each window has displayed text as received from the NX keyboard interface
- The second window has just been raised to the top of the display.
- </small>
- </tr>
-</table></center>
-
-
-<h2>1.2 <a name="Objectives">Objectives</a></h2>
-
-<p>
- The objective of this development was to provide a tiny windowing system in the
- spirit of X, but greatly scaled down and appropriate for most resource-limited
- embedded environments.
- The current NX implementation supports the general following, high-level features:
-</p>
-<ul>
- <li><b>Virtual Vertical Graphics Space</b>.
- Windows that reside in a virtual, <i>vertical</i> space so that it makes
- sense to talk about one window being on top of another and obscuring the
- window below it.
- </li>
- <li><b>Client/Server Model</b>.
- A standard client server/model was adopted. NX may be considered a server
- and other logic that presents the windows are NX clients.
- </li>
- <li><b>Multi-User Support</b>.
- NX includes <i>front-end</i> logic to support a separate NX server thread
- that can serve multiple NX client threads.
- The NX is a server thread/daemon the serializes graphics operations from
- multiple clients.
- </li>
- <li><b>Minimal Graphics Toolset</b>.
- The actual implementation of the graphics operations is performed by common,
- <i>back-end</i> logic. This back-end supports only a primitive set of graphic
- and rendering operations.
- </li>
- <li><b>Device Interface</b>.
- NX supports any graphics device either of two device interfaces:
- <ul>
- <li>
- Any device with random access video memory using the NuttX framebuffer driver interface
- (see <code>include/nuttx/video/fb.h</code>).
- </li>
- <li>
- Any LCD-like device than can accept raster line <i>runs</i> through a parallel or serial interface
- (see <code>include/nuttx/lcd/lcd.h</code>).
- By default, NX is configured to use the frame buffer driver unless <code>CONFIG_NX_LCDDRIVER</code> is defined =y in your NuttX configuration file.
- </li>
- </ul>
- </li>
- <li><b>Transparent to NX Client</b>.
- The window client on "sees" the sub-window that is operates in
- and does not need to be concerned with the virtual, vertical space (other
- that to respond to <i>redraw</i> requests from NX when needed).
- </li>
- <li><b>Framed Windows and Toolbars</b>.
- NX also adds the capability to support windows with frames and toolbars on
- top of the basic windowing support.
- These are windows such as those shown in the
- <a href="#screenshot">screenshot</a> above.
- These framed windows sub-divide one one window into three relatively independent
- subwindows: A frame, the contained window and an (optional) toolbar window.
- </li>
- <li><b>Mouse Support</b>.
- NX provides support for a mouse or other X/Y pointing devices.
- APIs are provided to allow external devices to give X/Y position information
- and mouse button presses to NX.
- NX will then provide the mouse input to the relevant window clients via callbacks.
- Client windows only receive the mouse input callback if the mouse is positioned over a visible
- portion of the client window; X/Y position is provided to the client in the relative
- coordinate system of the client window.
- </li>
- <li><b>Keyboard input</b>.
- NX also supports keyboard/keypad devices.
- APIs are provided to allow external devices to give keypad information to NX.
- NX will then provide the mouse input to the top window on the display (the window
- that has the <i>focus</i>) via a callback function.
- </li>
-</ul>
-
-<h2>1.3 <a name="Organization">Organization</a></h2>
-
-<p>
- NX is organized into 6 (and perhaps someday 7 or 8) logical modules.
- These logical modules also correspond to the directory organization.
- That NuttX directory organization is discussed in
- <a href="#grapicsdirs">Appendix B</a> of this document.
- The logic modules are discussed in the following sub-paragraphs.
-</p>
-
-<p>
- <center><img src="NXOrganization.gif" width="60%"></center>
-</p>
-
-<h3>1.3.1 <a name="nxgl1">NX Graphics Library (<code>NXGL</code>)</a></h3>
-
-<p>
- NXGLIB is a standalone library that contains low-level graphics utilities and
- direct framebuffer or LCD rendering logic. NX is built on top NXGLIB.
-</p>
-
-<h3>1.3.2 <a name="nx1">NX (<code>NXSU</code> and <code>NXMU</code>)</a></h3>
-
-<p>
- NX is the tiny NuttX windowing system for raw windows (i.e., simple regions of
- graphics memory).
- NX includes a small-footprint, multi-user implementation (NXMU as described below).
- NX can be used without NxWidgets and without NXTOOLKIT for raw window displays.
-</p>
-
-<p>
- <sup>1</sup><small>NXMU and NXSU are interchangeable other than (1) certain start-up
- and initialization APIs (as described below), and (2) timing. With NXSU, NX APIs
- execute immediately; with NXMU, NX APIs defer and serialize the operations and, hence,
- introduce different timing and potential race conditions that you would not experience
- with NXSU.</small>
-</p>
-
-<p><b>NXNULL?</b>
- At one time, I also envisioned a <i>NULL</i> front-end that did not support windowing
- at all but, rather, simply provided the entire framebuffer or LCD memory as one dumb window.
- This has the advantage that the same NX APIs can be used on the one dumb window as
- for the other NX windows.
- This would be in the NuttX spirit of scalability.
-</p>
-<p>
- However, the same end result can be obtained by using the
- <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a> API.
- It still may be possible to reduce the footprint in this usage case by developing
- and even thinner NXNULL front-end.
- That is a possible future development.
-</p>
-
-<h3>1.3.3 <a name="nxtk1">NX Tool Kit (<code>NXTK</code>)</a></h3>
-
-<p>
- NXTK is a s set of C graphics tools that provide higher-level window drawing
- operations.
- This is the module where the framed windows and toolbar logic is implemented.
- NXTK is built on top of NX and does not depend on NxWidgets.
-</p>
-
-<h3>1.3.4 <a name="nxfonts1">NX Fonts Support (<code>NXFONTS</code>)</a></h3>
-
-<p>
- A set of C graphics tools for present (bitmap) font images.
- The font implementation is at a very low level or graphics operation,
- comparable to the logic in NXGLIB.
- NXFONTS does not depend on any NX module other than some utilities and types from NXGLIB.
-</p>
-
-<h3>1.3.5 <a name="nxwidgets1">NX Widgets (<code>NxWidgets</code>)</a></h3>
-
-<p>
- <a href="NxWidgets.html">NxWidgets</a> is a higher level, C++, object-oriented library for object-oriented access to graphical "widgets."
- NxWidgets is provided as a separate library in the <code>apps/</code> repository
- NxWidgets is built on top of the core NuttX graphics subsystem, but is part of the application space rather than part of the core OS graphics subsystems.
-</p>
-
-<h3>1.3.6 <a name="nxterm1">NX Terminal Driver (<code>NxTerm</code>)</a></h3>
-
-<p>
- NxTerm is a write-only character device (not shown) that is built on top of an NX window.
- This character device can be used to provide <code>stdout</code> and <code>stderr</code> and, hence, can provide the output side of NuttX console.
-</code>).
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <h1>2.0 <a name="nxapis">NX User APIs</a></h1>
- </td>
- </tr>
-</table>
-
-<h2>2.1 <a name="nxheaders">NX Header Files</a></h2>
-
-<ul><dl>
- <dt><code>include/nuttx/nx/nxglib.h</code>
- <dd>Describes the NXGLIB C interfaces
- <dt><code>include/nuttx/nx/nx.h</code>
- <dd>Describes the NX C interfaces
- <dt><code>include/nutt/nxtk.h</code>
- <dd>Describe the NXTOOLKIT C interfaces
- <dt><code>include/nutt/nxfont.h</code>
- <dd>Describe sthe NXFONT C interfaces
-</dl></ul>
-
-<h2>2.2 <a name="nxgl2">NX Graphics Library (<code>NXGL</code>)</a></h2>
-
-<p>
- NXGL provides many APIs, some available for use internally by NX and
- others for use by applications as well.
- Only those APIs intended for application usage are documented here
- See <code>include/nuttx/nx/nxglib.h</code> for the full set of APIs;
- those APIs might be of interest if you are rendering directly into
- framebuffer or LCD memory.
-</p>
-
-<h3>2.2.1 <a name="nxgltypes">NXGL Types</a></h3>
-
-<p>
- <code>nxgl_mxpixel_t</code>.
- Holds one device pixel.
- NXGLIB will select the smallest size for the <code>nxgl_mxpixel_t</code>
- that just contains the pixel: <code>byte</code> if 16, 24, and 32 resolution
- support is disabled, <code>uint16_t</code> if 24, and 32 resolution
- support is disabled, or <code>uint32_t</code>.
-</p>
-
-<p>
- <code>nxgl_coord_t</code>.
- A given coordinate is limited to the screen height an width. If either
- of those values exceed 32,767 pixels, then the following will have to need
- to change:
-</p>
-<ul><pre>
-typedef int16_t nxgl_coord_t;
-</pre></ul>
-
-<p>
- <code>struct nxgl_point_s</code>. Describes a point on the display:
-</p>
-<ul><pre>
-struct nxgl_point_s
-{
- nxgl_coord_t x; /* X position, range: 0 to screen width - 1 */
- nxgl_coord_t y; /* Y position, range: 0 to screen height - 1 */
-};
-</pre></ul>
-
-<p>
- <code>struct nxgl_size_s</code>. Describes the size of a rectangular region.
-</p>
-<ul><pre>
-struct nxgl_size_s
-{
- nxgl_coord_t w; /* Width in pixels */
- nxgl_coord_t h; /* Height in rows */
-};
-</pre></ul>
-
-<p>
- <code>struct nxgl_rect_s</code>. Describes a positioned rectangle on the display.
-</p>
-<ul><pre>
-struct nxgl_rect_s
-{
- struct nxgl_point_s pt1; /* Upper, left-hand corner */
- struct nxgl_point_s pt2; /* Lower, right-hand corner */
-};
-</pre></ul>
-
-<p>
- <code>struct nxgl_run_s</code>.
- Describes a run, i.e., a horizontal line. Note that the start/end positions
- have fractional precision. This is necessary for good joining of trapezoids
- when a more complex shape is decomposed into trapezoids
-</p>
-<ul><pre>
-struct nxgl_run_s
-{
- b16_t x1; /* Left X position, range: 0 to x2 */
- b16_t x2; /* Right X position, range: x1 to screen width - 1 */
- nxgl_coord_t y; /* Top Y position, range: 0 to screen height - 1 */
-};
-</pre></ul>
-
-<p>
- <code>struct nxgl_trapezoid_s</code>.
- Describes a horizontal trapezoid on the display in terms the run at the
- top of the trapezoid and the run at the bottom
-</p>
-<ul><pre>
-struct nxgl_trapezoid_s
-{
- struct nxgl_run_s top; /* Top run */
- struct nxgl_run_s bot; /* bottom run */
-};
-</pre></ul>
-
-<h3>2.2.1 <a name="nxglrgb2yuv"><code>nxgl_rgb2yuv()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-void nxgl_rgb2yuv(uint8_t r, uint8_t g, uint8_t b, uint8_t *y, uint8_t *u, uint8_t *v);
-</pre></ul>
-<p>
- <b>Description:</b>
- Convert 8-bit RGB triplet to 8-bit YUV triplet.
-</p>
-
-<h3>2.2.2 <a name="nxglyuv2rgb"><code>nxgl_yuv2rgb()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-void nxgl_yuv2rgb(uint8_t y, uint8_t u, uint8_t v, uint8_t *r, uint8_t *g, uint8_t *b);
-</pre></ul>
-<p>
- <b>Description:</b>
- Convert 8-bit YUV triplet to 8-bit RGB triplet.
-</p>
-
-<h3>2.2.3 <a name="nxglrectcopy"><code>nxgl_rectcopy()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-void nxgl_rectcopy(FAR struct nxgl_rect_s *dest,
- FAR const struct nxgl_rect_s *src);
-</pre></ul>
-<p>
- <b>Description:</b>
- This is essentially <code>memcpy()</code>for rectangles. We don't do structure
- assignments because some compilers are not good at that.
-</p>
-
-<h3>2.2.4 <a name="nxglrectoffset"><code>nxgl_rectoffset()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-void nxgl_rectoffset(FAR struct nxgl_rect_s *dest,
- FAR const struct nxgl_rect_s *src,
- nxgl_coord_t dx, nxgl_coord_t dy);
-</pre></ul>
-<p>
- <b>Description:</b>
- Offset the rectangle position by the specified dx, dy values.
-</p>
-
-<h3>2.2.5 <a name="nxglvectoradd"><code>nxgl_vectoradd()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-void nxgl_vectoradd(FAR struct nxgl_point_s *dest,
- FAR const struct nxgl_point_s *v1,
- FAR const struct nxgl_point_s *v2);
-</pre></ul>
-<p>
- <b>Description:</b>
- Add two 2x1 vectors and save the result to a third.
-</p>
-
-<h3>2.2.6 <a name="nxglvectorsubtract"><code>nxgl_vectorsubtract()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-void nxgl_vectsubtract(FAR struct nxgl_point_s *dest,
- FAR const struct nxgl_point_s *v1,
- FAR const struct nxgl_point_s *v2);
-</pre></ul>
-<p>
- <b>Description:</b>
- Add subtract vector <code>v2</code> from vector <code>v1</code> and return the result in vector dest.
-</p>
-
-<h3>2.2.7 <a name="nxglrectintersect"><code>nxgl_rectintersect()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-void nxgl_rectintersect(FAR struct nxgl_rect_s *dest,
- FAR const struct nxgl_rect_s *src1,
- FAR const struct nxgl_rect_s *src2);
-</pre></ul>
-<p>
- <b>Description:</b>
- Return the rectangle representing the intersection of the two rectangles.
-</p>
-
-<h3>2.2.8 <a name="nxglrectunion"><code>nxgl_rectunion()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-void nxgl_rectunion(FAR struct nxgl_rect_s *dest,
- FAR const struct nxgl_rect_s *src1,
- FAR const struct nxgl_rect_s *src2);
-</pre></ul>
-<p>
- <b>Description:</b>
- Given two rectangles, <code>src1</code> and <code>src2</code>, return the larger rectangle that
- contains both, <code>dest</code>.
-</p>
-
-<h3>2.2.9 <a name="nxglnonintersecting"><code>nxgl_nonintersecting()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-nxgl_nonintersecting(FAR struct nxgl_rect_s result[4],
- FAR const struct nxgl_rect_s *rect1,
- FAR const struct nxgl_rect_s *rect2);
-</pre></ul>
-<p>
- <b>Description:</b>
- Return the regions of rectangle <code>rect1</code> that do not intersect with
- <code>rect2</code>. This will four rectangles, some of which may be
- degenerate (and can be picked off with <a href="#nxglnullrect"><code>nxgl_nullrect()</code></a>).
-</p>
-
-<h3>2.2.10 <a name="nxglrectoverlap"><code>nxgl_rectoverlap()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-bool nxgl_rectoverlap(FAR struct nxgl_rect_s *rect1,
- FAR struct nxgl_rect_s *rect2);
-</pre></ul>
-<p>
- <b>Description:</b>
- Return true if the two rectangles overlap.
-</p>
-
-<h3>2.2.11 <a name="nxglrectinside"><code>nxgl_rectinside()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-bool nxgl_rectinside(FAR const struct nxgl_rect_s *rect,
- FAR const struct nxgl_point_s *pt);
-</pre></ul>
-<p>
- <b>Description:</b>
- Return true if the point <code>pt</code> lies within <code>rect</code>.
-</p>
-
-<h3>2.2.12 <a name="nxglrectsize"><code>nxgl_rectsize()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-void nxgl_rectsize(FAR struct nxgl_size_s *size,
- FAR const struct nxgl_rect_s *rect);
-</pre></ul>
-<p>
- <b>Description:</b>
- Return the size of the specified rectangle.
-</p>
-
-<h3>2.2.13 <a name="nxglnullrect"><code>nxgl_nullrect()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-bool nxgl_nullrect(FAR const struct nxgl_rect_s *rect);
-</pre></ul>
-<p>
- <b>Description:</b>
- Return true if the area of the retangle is <= 0.
-</p>
-
-<h3>2.2.14 <a name="nxglrunoffset"><code>nxgl_runoffset()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-void nxgl_runoffset(FAR struct nxgl_run_s *dest,
- FAR const struct nxgl_run_s *src,
- nxgl_coord_t dx, nxgl_coord_t dy);
-</pre></ul>
-<p>
- <b>Description:</b>
- Offset the run position by the specified <code>dx</code>, <code>dy</code> values.
-</p>
-
-<h3>2.2.15 <a name="nxglruncopy"><code>nxgl_runcopy()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-void nxgl_runcopy(FAR struct nxgl_run_s *dest,
- FAR const struct nxgl_run_s *src);
-</pre></ul>
-<p>
- <b>Description:</b>
- This is essentially <code>memcpy()</code>for runs. We don't do structure assignments
- because some compilers are not good at that.
-</p>
-
-<h3>2.2.16 <a name="nxgltrapoffset"><code>nxgl_trapoffset()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-void nxgl_trapoffset(FAR struct nxgl_trapezoid_s *dest,
- FAR const struct nxgl_trapezoid_s *src,
- nxgl_coord_t dx, nxgl_coord_t dy);
-</pre></ul>
-<p>
- <b>Description:</b>
- Offset the trapezoid position by the specified <code>dx</code>, <code>dy</code> values.
-</p>
-
-<h3>2.2.17 <a name="nxgltrapcopy"><code>nxgl_trapcopy()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-void nxgl_trapcopy(FAR struct nxgl_trapezoid_s *dest,
- FAR const struct nxgl_trapezoid_s *src);
-</pre></ul>
-<p>
- <b>Description:</b>
- This is essentially <code>memcpy()</code>for trapezoids. We don't do structure
- assignments because some compilers are not good at that.
-</p>
-
-<h3>2.2.18 <a name="nxglcolorcopy"><code>nxgl_colorcopy</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-nxgl_colorcopy(nxgl_mxpixel_t dest[CONFIG_NX_NPLANES],
- const nxgl_mxpixel_t src[CONFIG_NX_NPLANES]);
-</pre></ul>
-<p>
- <b>Description:</b>
- This is essentially <code>memcpy()</code>for colors. This does very little for us
- other than hide all of the conditional compilation for planar colors
- in one place.
-</p>
-
-<h3>2.2.19 <a name="nxglsplitline"><code>nxgl_splitline</code></a></h3>
-
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-int nxgl_splitline(FAR struct nxgl_vector_s *vector, FAR struct nxgl_trapezoid_s *traps,
- FAR struct nxgl_rect_s *rect, nxgl_coord_t linewidth);
-</pre></ul>
-<p>
- <b>Description:</b>
- In the general case, a line with width can be represented as a parallelogram with a triangle at the top and bottom.
- Triangles and parallelograms are both degenerate versions of a trapezoid.
- This function breaks a wide line into triangles and trapezoids.
- This function also detects other degenerate cases:
-</p>
-<ol>
- <li>
- If <code>y1 == y2</code> then the line is horizontal and is better represented as a rectangle.
- </li>
- <li>
- If <code>x1 == x2</code> then the line is vertical and also better represented as a rectangle.
- </li>
- <li>
- If the width of the line is 1, then there are no triangles at the top and bottom
- (this may also be the case if the width is narrow and the line is near vertical).
- </li>
- <li>
- If the line is oriented is certain angles, it may consist only of the upper and lower triangles with no trapezoid in between.
- In this case, 3 trapezoids will be returned, but traps[1] will be degenerate.
- </li>
-</ol>
-<p>
- <b>Input parameters</b>:
-<p>
-<ul><dl>
- <dt><code>vector</code>
- <dd>A pointer to the vector described the line to be drawn.
- <dt><code>traps</code>
- <dd>A pointer to a array of trapezoids (size 3).
- <dt><code>rect</code>
- <dd> A pointer to a rectangle.
-</dl></ul>
-<p>
- <b>Returned value</b>:
-</p>
-<ul>
- <p>
- <code>0</code>: Line successfully broken up into three trapezoids.
- Values in <code>traps[0]</code>, <code>traps[1]</code>, and <code>traps[2]</code> are valid.
- </p>
- <p>
- <code>1</code>: Line successfully represented by one trapezoid.
- Value in <code>traps[1]</code> is valid.
- </p>
- <p>
- <code>2</code>: Line successfully represented by one rectangle.
- Value in <code>rect </code>is valid
- </p>
- <p>
- <code><0</code>: On errors, a negated <code>errno</code> value is returned.
- </p>
- <p>
-</ul>
-
-<h3>2.2.20 <a name="nxglcirclepts"><code>nxgl_circlepts</code></a></h3>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-void nxgl_circlepts(FAR const struct nxgl_point_s *center, nxgl_coord_t radius,
- FAR struct nxgl_point_s *circle);
-</pre></ul>
-<p>
- <b>Description:</b>
- Given a description of a circle, return a set of 16 points on the circumference of the circle.
- These points may then be used by <a href="nxdrawcircle"><code>nx_drawcircle()</code></a> or related APIs to draw a circle outline.
-</p>
-<p>
- <b>Input parameters</b>:
-<p>
-<ul><dl>
- <dt><code>center</code>
- <dd>A pointer to the point that is the center of the circle.
- <dt><code>radius</code>
- <dd>The radius of the circle in pixels.
- <dt><code>circle</code>
- <dd>A pointer the first entry in an array of 16 points where the circle points will be returned.
-</dl></ul>
-<p>
- <b>Returned value</b>: None
-</p>
-
-<h3>2.2.21 <a name="nxglcircletraps"><code>nxgl_circletraps</code></a></h3>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-oid nxgl_circletraps(FAR const struct nxgl_point_s *center, nxgl_coord_t radius,
- FAR struct nxgl_trapezoid_s *circle);
-</pre></ul>
-<p>
- <b>Description:</b>
- Given a description of a a circle, return 8 trapezoids that can be used to fill the circle by <a href="nxfillcircle"><code>nx_fillcircle()</code></a> and other interfaces.
-</p>
-<p>
- <b>Input parameters</b>:
-<p>
-<ul><dl>
- <dt><code>center</code>
- <dd>A pointer to the point that is the center of the circle.
- <dt><code>radius</code>
- <dd>The radius of the circle in pixels.
- <dt><code>circle</code>
- <dd>A pointer the first entry in an array of 8 trapezoids where the circle description will be returned.
-</dl></ul>
-<p>
- <b>Returned value</b>: None
-</p>
-
-<h2>2.3 <a name="nx2">NX</a></h2>
-
-<h3>2.3.1 <a name="nxppdefs">Pre-Processor Definitions</a></h3>
-
-<p>
- The default server message queue name used by the
- <a href="#nxruninstance"><code>nx_run()</code></a> macro:
-</p>
-<ul><pre>
-#define NX_DEFAULT_SERVER_MQNAME "/dev/nxs"
-</pre></ul>
-
-<p>
- Mouse button bits:
-</p>
-<ul><pre>
-#define NX_MOUSE_NOBUTTONS 0x00
-#define NX_MOUSE_LEFTBUTTON 0x01
-#define NX_MOUSE_CENTERBUTTON 0x02
-#define NX_MOUSE_RIGHTBUTTON 0x04
-</pre></ul>
-
-<h3>2.3.2 <a name="nxtypes">NX Types</a></h3>
-
-<p>
- The interface to the NX server is managed using a opaque handle:
-</p>
-<ul><pre>
-typedef FAR void *NXHANDLE;
-</pre></ul>
-
-<p>
- The interface to a specific window is managed using an opaque handle:
-</p>
-<ul><pre>
-typedef FAR void *NXWINDOW;
-</pre></ul>
-
-<p>
- These define callbacks that must be provided to <a href="#nxopenwindow"><code>nx_openwindow()</code></a>.
- These callbacks will be invoked as part of the processing performed by <a href="#nxeventhandler"><code>nx_eventhandler()</code></a>.
-</p>
-<ul><pre>
-struct nx_callback_s
-{
- void (*redraw)(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect,
- bool more, FAR void *arg);
- void (*position)(NXWINDOW hwnd, FAR const struct nxgl_size_s *size,
- FAR const struct nxgl_point_s *pos,
- FAR const struct nxgl_rect_s *bounds,
- FAR void *arg);
-#ifdef CONFIG_NX_XYINPUT
- void (*mousein)(NXWINDOW hwnd, FAR const struct nxgl_point_s *pos,
- uint8_t buttons, FAR void *arg);
-#endif
-#ifdef CONFIG_NX_KBD
- void (*kbdin)(NXWINDOW hwnd, uint8_t nch, FAR const uint8_t *ch, FAR void *arg);
-#endif
-};
-</pre></ul>
-
-<h3>2.3.3 <a name="startingnx">Starting the NX Server</a></h3>
-<p>
- The <i>NX Server</i> is a kernel daemon that receives and serializes graphic commands.
- Before you can use the NX graphics system, you must first start this daemon.
- There are two ways that this can be done:
-</p>
-<ol>
- <li>
- <p>
- The NX server may be started in your board startup logic by simply calling the function <code> nxmu_start()</code>.
- The board startup logic usually resides the the <code>boards/<i>arch</i>/<i>chip</i>/<i>board</i>/src</code> directory.
- The board startup logic can run automatically during the early system if <code>CONFIG_BOARD_LATE_INITIALIZE</code> is defined in the configuration.
- Or, the board startup logic can execute under control of the application by calling the <code>boardctl(BOARDIOC_INIT, arg)</code> OS interface.
- </p>
- <p>
- The board initialization logic will run in either case and the simple call to <code>nxmu_start()</code> will start the NX server.
- </p>
- </li>
- <li>
- The NX server may also be started later by the application via the <code>boardctl(BOARDIOC_NX_START, arg)</code>
- </li>
-</ol>
-
-<h4>2.3.3.1 <a name="nxstart"><code>nxmu_start()</code></a></h4>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nx.h>
-
-int nxmu_start(int display, int plane);
-</pre></ul>
-<p>
- <b>Description:</b>
- <code>nxmu_start()</code> provides a wrapper function to simplify and standardize the starting of the NX server.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>display</code>
- <dd>The display number to be served by this new NXMU instance.
- <dt><code>plane</code>
- <dd>The plane number to use to get information about the display geometry and color format.
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- Zero (<code>OK</code>) is returned on success.
- This indicates that the NX server has been successfully started, is running, and waiting to accept connections from NX clients.
-</p>
-<p>
- A negated <code>errno</code> value is returned on failure.
- The <code>errno</code> value indicates the nature of the failure.
-</p>
-
-<h4>2.3.3.1 <a name="boardctl"><code>boardctl()</code></a></h4>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <sys/boardctl.h>
-
-</pre></ul>
-<p>
- <b>Description:</b>
- <code>boardctl()</code> is a generic NuttX interface that among many of it functions, may also be used to start the NX server.
-</p>
- In a small embedded system, there will typically be a much greater interaction between application and low-level board features.
- The canonically correct to implement such interactions is by implementing a character driver and performing the interactions via low level <code>ioctl()</code> calls.
- This, however, may not be practical in many cases and will lead to "correct" but awkward implementations.
-</p>
-<p>
- <code>boardctl()</code> is non-standard OS interface to alleviate the problem.
- It basically circumvents the normal device driver ioctl interlace and allows the application to perform direction IOCTL-like calls to the board-specific logic.
- In it is especially useful for setting up board operational and test configurations.
-</p>
-<p>
- When called with the <code>cmd</code> of <code>BOARDIOC_NX_START</code>, then the <code>boardctl()</code> will call <code>nxmu_start</code> indirectly on behalf of the application.
- In this case the <code>arg</code> parameter is ignored.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>cmd</code>
- <dd> Identifies the board command to be executed
- <dt><code>arg</code>
- <dd>The argument that accompanies the command. The nature of the argument is determined by the specific command.
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- On success zero (<code>OK</code) is returned; -1 (<code>ERROR</code>) is returned on failure with the <code>errno</code> variable set to indicate the nature of the failure.
-</p>
-
-<h3>2.3.4 <a name="nxcallbacks">NX Server Callbacks</a></h3>
-
-<h4>2.3.4.1 <a name="nxcbredraw"><code>redraw()</code></a></h4>
-<p><b>Callback Function Prototype:</b></p>
-<ul><pre>
-void redraw(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect,
- bool more, FAR void *arg);
-</pre></ul>
-<p>
- <b>Description:</b>
- NX requests that the client re-draw the portion of the window within
- with rectangle.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hwnd</code>
- <dd>The handle created by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>
- or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>
- <dt><code>rect</code>
- <dd>The rectangle that needs to be re-drawn (in window relative coordinates)
- <dt><code>more</code>
- <dd>true: More re-draw requests will follow
- <dt><code>arg</code>
- <dd>User provided argument (see <a href="#nxopenwindow"><code>nx_openwindow()</code></a>)
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b> None
-</p>
-
-<h4>2.3.4.2 <a name="nxcbposition"><code>position()</code></a></h4>
-<p><b>Callback Function Prototype:</b></p>
-<ul><pre>
-void position(NXWINDOW hwnd, FAR const struct nxgl_size_s *size,
- FAR const struct nxgl_point_s *pos,
- FAR const struct nxgl_rect_s *bounds,
- FAR void *arg);
-</pre></ul>
-<p>
- <b>Description:</b>
- The size or position of the window has changed (or the window was
- just created with zero size.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hwnd</code>
- <dd>The handle created by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>
- or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>
- <dt><code>size</code>
- <dd>The size of the window
- <dt><code>pos</code>
- <dd>The position of the upper left hand corner of the window on
- the overall display
- <dt><code>bounds</code>
- <dd>The bounding rectangle that the describes the entire display
- <dt><code>arg</code>
- <dd>User provided argument (see <a href="#nxopenwindow"><code>nx_openwindow()</code></a>)
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b> None
-</p>
-
-<h4>2.3.4.3 <a name="nxcbmousein"><code>mousein()</code></a></h4>
-<p><b>Callback Function Prototype:</b></p>
-<ul><pre>
-#ifdef CONFIG_NX_XYINPUT
-void mousein(NXWINDOW hwnd, FAR const struct nxgl_point_s *pos,
- uint8_t buttons, FAR void *arg);
-#endif
-</pre></ul>
-<p>
- <b>Description:</b>
- New mouse data is available for the window
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hwnd</code>
- <dd>The handle created by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>
- or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>
- <dt><code>pos</code>
- <dd>The (x,y) position of the mouse
- <dt><code>buttons</code>
- <dd>See <code>NX_MOUSE_*</code> definitions
- <dt><code>arg</code>
- <dd>User provided argument (see <a href="#nxopenwindow"><code>nx_openwindow()</code></a>)
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b> None
-</p>
-
-<h4>2.3.4.4 <a name="nxcbkbdin"><code>kbdin()</code></a></h4>
-<p><b>Callback Function Prototype:</b></p>
-<ul><pre>
-#ifdef CONFIG_NX_KBD
-void (*kbdin)(NXWINDOW hwnd, uint8_t nch, FAR const uint8_t *ch, FAR void *arg);
-#endif
-</pre></ul>
-<p>
- <b>Description:</b>
- New keyboard/keypad data is available for the window.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hwnd</code>
- <dd>The handle created by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>
- or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>
- <dt><code>nch</code>
- <dd>The number of characters that are available in ch[]
- <dt><code>ch</code>
- <dd>The array of characters
- <dt><code>arg</code>
- <dd>User provided argument (see <a href="#nxopenwindow"><code>nx_openwindow()</code></a>)
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b> None
-</p>
-
- <i>2.3.4.5 <a href="#"><code>event()</code></a></i>
-<h4>2.3.4.5 <a name="nxcbevent"><code>event()</code></a></h4>
-<p><b>Callback Function Prototype:</b></p>
-<ul><pre>
-void (*event)(NXWINDOW hwnd, enum nx_event_e event, FAR void *arg1, FAR void *arg2);
-</pre></ul>
-<p>
- <b>Description:</b>
- This callback is used to communicate server events to the window listener.
-</p>
-<dl>
- <dt>NXEVENT_BLOCKED - Window messages are blocked.
- <dd>This callback is the response from <a href="#nxblock"><code>nx_block()</code></a>, <a href="#nxtkblock"><code>nxtk_block()</code></a>. Those blocking interfaces are used to assure that no further messages are directed to the window. Receipt of the blocked callback signifies that (1) there are no further pending callbacks and (2) that the window is now <i>defunct</i> and will receive no further callbacks.
-
- This callback supports coordinated destruction of a window. In the multi-user mode, the client window logic must stay intact until all of the queued callbacks are processed. Then the window may be safely closed. Closing the window prior with pending callbacks can lead to bad behavior when the callback is executed.
- <dt>NXEVENT_SYNCHED - Synchronization handshake
- <dd>This completes the handshake started by <a href="#nxsynch"><code>nx_synch()</code></a>, or <a href="#nxtksynch"><code>nxtk_synch()</code></a>. Those interfaces send a synchronization messages to the NX server which responds with this event. The sleeping client is awakened and continues graphics processing, completing the handshake.
-
- Due to the highly asynchronous nature of client-server communications, synchronization is sometimes necessary to assure that the client and server are working together properly.
-</dl>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hwnd</code>
- <dd>TWindow handle of window receiving the event
- <dt><code>event</code>
- <dd>The server event
- <dt><code>arg1</code>
- <dd>User provided argument (see <a href="#nxopenwindow"><code>nx_openwindow()</code></a>, <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>, or <a href="#nxtkopentoolbar"><code>nxtk_opentoolbar()</code></a>)
- <dt><code>arg2</code>
- <dd>TUser provided argument (see <a href="#nxblock"><code>nx_block()</code></a>, <a href="#nxtkblock"><code>nxtk_block()</code></a>, <a href="#nxsynch"><code>nx_synch()</code></a>, or <a href="#nxtksynch"><code>nxtk_synch()</code></a>)
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b> None
-</p>
-
-
-<h3>2.3.5 <a name="nxruninstance"><code>nx_runinstance()</code> (and <code>nx_run()</code> macro)</a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-int nx_runinstance(FAR const char *mqname, FAR struct fb_vtable_s *fb);
-#define nx_run(fb) nx_runinstance(NX_DEFAULT_SERVER_MQNAME, dev)
-</pre></ul>
-<p>
- <b>Description:</b>
- This is the server entry point. It does not return; the calling thread
- is dedicated to supporting NX server.
-</p>
-<p>
- NOTE that multiple instances of the NX server may run at the same time,
- with different callback and message queue names.
- <code>nx_run()</code> is simply a macro that can be used when only one
- server instance is required.
- In that case, a default server name is used.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>mqname</code>
- <dd>
- - The name for the server incoming message queue
- <dt><code>dev</code>
- <dd>Framebuffer or LCD driver "object" to be used
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- This function usually does not return. If it does return, it will
- return <code>ERROR</code> and <code>errno</code> will be set appropriately.
-</p>
-
-<h3>2.3.6 <a name="nxconnectinstance"><code>nx_connectinstance()</code> (and <code>nx_connect()</code> macro)</a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-NXHANDLE nx_connectinstance(FAR const char *svrmqname);
-#define nx_connect(cb) nx_connectinstance(NX_DEFAULT_SERVER_MQNAME)
-</pre></ul>
-<p>
- <b>Description:</b>
- Open a connection from a client to the NX server. One one client
- connection is normally needed per thread as each connection can host
- multiple windows.
-</p>
-<p>
- NOTES:
-</p>
-<ul>
- <li>
- This function returns before the connection is fully instantiated.
- it is necessary to wait for the connection event before using the
- returned handle.
- </li>
- <li>
- Multiple instances of the NX server may run at the same time,
- each with different message queue names.
- </li>
- <li>
- <code>nx_connect()</code> is simply a macro that can be used when only one
- server instance is required. In that case, a default server name
- is used.
- </li>
-</ul>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>svrmqname</code>
- <dd>The name for the server incoming message queue
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
-</p>
-<ul>
- Success: A non-NULL handle used with subsequent NX accesses<br>
- Failure: NULL is returned and <code>errno</code> is set appropriately.
-</ul>
-
-<h3>2.3.7 <a name="nxdisconnect"><code>nx_disconnect()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-void nx_disconnect(NXHANDLE handle);
-</pre></ul>
-<p>
- <b>Description:</b>
- Disconnect a client from the NX server and/or free resources reserved
- by <a href="#nxconnectinstance"><code>nx_connect()</code>/<code>nx_connectinstance()</code></a>.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>handle</code>
- <dd>The handle returned by <a href="#nxconnectinstance"><code>nx_connect()</code></a>.
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b> None.
-</p>
-
-<h3>2.3.8 <a name="nxeventhandler"><code>nx_eventhandler()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-int nx_eventhandler(NXHANDLE handle);
-</pre></ul>
-<p>
- <b>Description:</b>
- The client code must call this function periodically to process
- incoming messages from the server. If <code>CONFIG_NX_BLOCKING</code> is defined,
- then this function not return until a server message is received.
-</p>
-<p>
- When <code>CONFIG_NX_BLOCKING</code> is not defined, the client must exercise
- caution in the looping to assure that it does not eat up all of
- the CPU bandwidth calling nx_eventhandler repeatedly.
- <a href="#nxeventnotify"><code>nx_eventnotify()</code></a>
- may be called to get a signal event whenever a new incoming server
- event is available.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>handle</code>
- <dd>The handle returned by <a href="#nxconnectinstance"><code>nx_connect()</code></a>.
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
-</p>
-<ul>
- <li>
- <code>OK</code>: No errors occurred. If <code>CONFIG_NX_BLOCKING</code> is defined,
- then one or more server messages were processed.
- </li>
- <li>
- <code>ERROR</code>: An error occurred and <code>errno</code> has been set appropriately.
- Of particular interest, it will return <code>errno == EHOSTDOWN</code> when the
- server is disconnected. After that event, the handle can no longer be used.
- </li>
-</ul>
-
-<h3>2.3.9 <a name="nxeventnotify"><code>nx_eventnotify()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-int nx_eventnotify(NXHANDLE handle, int signo);
-</pre></ul>
-<p>
- <b>Description:</b>
- Rather than calling <a href="#nxeventhandler"><code>nx_eventhandler()</code></a> periodically,
- the client may register to receive a signal when a server event is available.
- The client can then call <a href="#nxeventhandler"><code>nv_eventhandler()</code></a> only when
- incoming events are available.
-</p>
-<p>
- The underlying implementation used <code>mq_notifiy()</code> and, as a result,
- the client must observe the rules for using <code>mq_notifiy()</code>:
- <ul>
- <li>
- Only one event is signalled. Upon receipt of the signal, if the client
- wishes further notifications, it must call <code>nx_eventnotify()</code> again.
- </li>
- <li>
- The signal will only be issued when the message queue transitions from empty to
- not empty.
- </li>
- </ul>
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>handle</code>
- <dd>The handle returned by <a href="#nxconnectinstance"><code>nx_connect()</code></a>.
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.3.10 <a name="nxblock"><code>nx_block()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nx.h>
-
-int nx_block(NXWINDOW hwnd, FAR void *arg);
-</pre></ul>
-<p>
- <b>Description:</b>
- The response to this function call is two things: (1) any queued callback messages to the window are 'blocked' and then (2) also subsequent window messaging is blocked.
-</p>
-<p>
- The <code>event</code> callback with the <code>NXEVENT_BLOCKED</code> event is the response from <code>nx_block()</code>. This blocking interface is used to assure that no further messages are are directed to the window. Receipt of the <code>NXEVENT_BLOCKED</code> event signifies that (1) there are no further pending callbacks and (2) that the window is now <i>defunct</i> and will receive no further callbacks.
-</p>
-<p>
- This callback supports coordinated destruction of a window. The client window logic must stay intact until all of the queued callbacks are processed. Then the window may be safely closed. Closing the window prior with pending callbacks can lead to bad behavior when the callback is executed.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul>
- <dl>
- <dt><code>wnd</code>
- <dd>The window to be blocked
- <dt><code>arg</code>
- <dd>An argument that will accompany the block messages (This is <code>arg2</code> in the event callback).
- </ul>
-</p>
-<p>
- <b>Returned Value:</b>
- OK on success; ERROR on failure with errno set appropriately.
-</p>
-
-<h3>2.3.11 <a name="nxsynch"><code>nx_synch()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nx.h>
-
-int nx_synch(NXWINDOW hwnd, FAR void *arg);
-</pre></ul>
-<p>
- <b>Description:</b>
- This interface can be used to synchronize the window client with the NX server. It really just implements an <i>echo</i>: A synch message is sent from the window client to the server which then responds immediately by sending the <code>NXEVENT_SYNCHED</code> back to the windows client.
-</p>
-<p>
- Due to the highly asynchronous nature of client-server communications, <code>nx_synch()</code> is sometimes necessary to assure that the client and server are fully synchronized in time.
-</p>
-<p>
- Usage by the window client might be something like this:
-</p>
-<ul><pre>
- extern bool g_synched;
- extern sem_t g_synch_sem;
-
- g_synched = false;
- ret = nx_synch(hwnd, handle);
- if (ret < 0)
- {
- -- Handle the error --
- }
-
- while (!g_synched)
- {
- ret = sem_wait(&g_sync_sem);
- if (ret < 0)
- {
- -- Handle the error --
- }
- }
-</pre></ul>
-<p>
- When the window listener thread receives the <code>NXEVENT_SYNCHED</code> event, it would set <code>g_synched</code> to <code>true</code> and post <code>g_synch_sem</code>, waking up the above loop.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>wnd</code>
- <dd>The window to be synched
- <dt><code>arg</code>
- <dd>An argument that will accompany the synch messages (This is <code>arg2</code> in the event callback).
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- OK on success; ERROR on failure with errno set appropriately
-</p>
-
-<h3>2.3.12 <a name="nxopenwindow"><code>nx_openwindow()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-NXWINDOW nx_openwindow(NXHANDLE handle, uint8_t flags,
- FAR const struct nx_callback_s *cb,
- FAR void *arg);
-</pre></ul>
-<p>
- <b>Description:</b> Create a new window.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>handle</code>
- <dd>The handle returned by <a href="#nxconnectinstance"><code>nx_connect()</code></a>.
- <dt><code>flags</code>
- <dd>Optional flags.
- These include:
- <ul>
- <li><code>NXBE_WINDOW_RAMBACKED</code>: Creates a RAM backed window.
- This option is only valid if <code>CONFIG_NX_RAMBACKED</code> is enabled.
- </li>
- <li><code>NXBE_WINDOW_HIDDEN</code>: The window is create in the HIDDEN state and can be made visible later with <code>nx_setvisibility()</code>.
- </li>
- </ul>
- <dt><code>cb</code>
- <dd>Callbacks used to process window events
- <dt><code>arg</code>
- <dd>User provided value that will be returned with NX callbacks.
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
-</p>
-<ul>
- Success: A non-NULL handle used with subsequent NX accesses<br>
- Failure: NULL is returned and <code>errno</code> is set appropriately.
-</ul>
-
-<h3>2.3.13 <a name="nxclosewindow"><code>nx_closewindow()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-int nx_closewindow(NXWINDOW hwnd);
-</pre></ul>
-<p>
- <b>Description:</b>
- Destroy a window created by <a href="#nxopenwindow"><code>nx_openwindow()</code></a> window.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hwnd</code>
- <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>
- that identifies the window to be destroyed.
- This handle must not have been one returned by
- <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>.
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.3.14 <a name="nxrequestbkgd"><code>nx_requestbkgd()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-int nx_requestbkgd(NXHANDLE handle,
- FAR const struct nx_callback_s *cb,
- FAR void *arg);
-</pre></ul>
-<p>
- <b>Description:</b>
- NX normally controls a separate window called the background window.
- It repaints the window as necessary using only a solid color fill. The
- background window always represents the entire screen and is always
- below other windows. It is useful for an application to control the
- background window in the following conditions:
-</p>
-<ul>
- <li>
- If you want to implement a windowless solution. The single screen
- can be used to create a truly simple graphic environment.
- </li>
- <li>
- When you want more on the background than a solid color. For
- example, if you want an image in the background, or animations in the
- background, or live video, etc.
- </li>
-</ul>
-<p>
- This API only requests the handle of the background window. That
- handle will be returned asynchronously in a subsequent position and
- redraw callbacks.
-</p>
-<p>
- Cautions:
-</p>
-<ul>
- <li>
- The following should never be called using the background window.
- They are guaranteed to cause severe crashes:
- <a href="#nxsetposition"><code>nx_setposition()</code></a>,
- <a href="#nxsetsize"><code>nx_setsize()</code></a>,
- <a href="#nxraise"><code>nx_raise()</code></a>, or
- <a href="#nxlower"><code>nx_lower()</code></a>.
- <a href="#nxmodal"><code>nx_modal()</code></a>.
- <a href="#nxsetvisibility"><code>nx_setvisibility()</code></a>.
- </li>
- <li>
- Neither <code>nx_requestbkgd()</code> nor
- <a href="#nxreleasebkgd"><code>nx_releasebkgd ()</code></a> should be called more than once.
- Multiple instances of the background window are not supported.
- </li>
-</ul>
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>handle</code>
- <dd>The handle returned by <a href="#nxconnectinstance"><code>nx_connect()</code></a>.
- <dt><code>cb</code>
- <dd>Callbacks to use for processing background window events
- <dt><code>arg</code>
- <dd>User provided argument (see <a href="#nxopenwindow"><code>nx_openwindow()</code></a>)
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.3.15 <a name="nxreleasebkgd"><code>nx_releasebkgd()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-int nx_releasebkgd(NXWINDOW hwnd);
-</pre></ul>
-<p>
- <b>Description:</b>
- Release the background window previously acquired using
- <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>
- and return control of the background to NX.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>handle</code>
- <dd>The handle returned indirectly by
- <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>.
- This handle must not have been one created by
- <a href="#nxopenwindow"><code>nx_openwindow()</code></a>.
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.3.16 <a name="nxgetposition"><code>nx_getposition()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-int nx_getposition(NXWINDOW hwnd);
-</pre></ul>
-<p>
- <b>Description:</b>
- Request the position and size information for the selected window. The
- values will be return asynchronously through the client callback function
- pointer.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hwnd</code>
- <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a> or
- <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>.
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.3.17 <a name="nxsetposition"><code>nx_setposition()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-int nx_setposition(NXWINDOW hwnd, FAR struct nxgl_point_s *pos);
-</pre></ul>
-<p>
- <b>Description:</b>
- Set the position and size for the selected window.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hwnd</code>
- <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>.
- This handle must not have been created by
- <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>.
- <dt><code>pos</code>
- <dd>The new position of the window
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.3.18 <a name="nxsetsize"><code>nx_setsize()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-int nx_setsize(NXWINDOW hwnd, FAR struct nxgl_size_s *size);
-</pre></ul>
-<p>
- <b>Description:</b> Set the size of the selected window.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hwnd</code>
- <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>.
- This handle must not have been created by
- <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>.
- <dt><code>size</code>
- <dd>The new size of the window (in pixels).
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.3.19 <a name="nxraise"><code>nx_raise()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-int nx_raise(NXWINDOW hwnd);
-</pre></ul>
-<p>
- <b>Description:</b> Bring the specified window to the top of the display.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hwnd</code>
- <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>.
- This handle must not have been created by
- <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>.
- <dt><code></code>
- <dd>
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.3.20 <a name="nxlower"><code>nx_lower()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-int nx_lower(NXWINDOW hwnd);
-</pre></ul>
-<p>
- <b>Description:</b> Lower the specified window to the bottom of the display.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hwnd</code>
- <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>.
- This handle must not have been created by
- <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>.
- <dt><code></code>
- <dd>
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.3.21 <a name="nxmodal"><code>nx_modal()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-int nx_modal(NXWINDOW hwnd, bool modal);
-</pre></ul>
-<p>
- <b>Description:</b> May be used to either (1) raise a window to the top of the display and select modal behavior, or (2) disable modal behavior.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hwnd</code>
- <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>.
- This handle must not have been created by
- <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>.
- <dt><code>modal</code>
- <dd>True: enter modal state; False: leave modal state
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.3.22 <a name="nxsetvisibility"><code>nx_setvisibility()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-int nx_setvisibility(NXWINDOW hwnd, bool hide);
-</pre></ul>
-<p>
- <b>Description:</b> Select if the window is visible or hidden.
- A hidden window is still present and will update normally, but will not be visible on the display until it is unhidden.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hwnd</code>
- <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>.
- This handle must not have been created by
- <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>.
- <dt><code>hide</code>
- <dd>True: Window will be hidden; false: Window will be visible
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.3.23 <a name="nxishidden"><code>nx_ishidden()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nx.h>
-
-bool nx_ishidden(NXWINDOW hwnd);
-</pre></ul>
-<p>
- <b>Description:</b> Return true if the window is hidden.
-</p>
-<p>
- <b>NOTE</b>: There will be a delay between the time that the visibility of the window is changed via <a href="#nxsetvisibility"><code>nx_setvisibily()</code></a> before that new setting is reported by <code>nx_ishidden()</code>.
- <code>nx_synch()</code> may be used if temporal synchronization is required.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hwnd</code>
- <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a> that identifies the window to be queried.
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <i>True</i>: the window is hidden, <i>false</i>: the window is visible
-</p>
-
-<h3>2.3.24 <a name="nxfill"><code>nx_fill()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-int nx_fill(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect,
- nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
-</pre></ul>
-<p>
- <b>Description:</b>
- Fill the specified rectangle in the window with the specified color.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hwnd</code>
- <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>
- or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>
- <dt><code>rect</code>
- <dd>The location to be filled
- <dt><code>color</code>
- <dd>The color to use in the fill
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.3.25 <a name="nxgetrectangle"><code>nx_getrectangle()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-void nx_getrectangle(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect,
- unsigned int plane, FAR uint8_t *dest,
- unsigned int deststride);
-</pre></ul>
-<p>
- <b>Description:</b>
- Get the raw contents of graphic memory within a rectangular region. NOTE:
- Since raw graphic memory is returned, the returned memory content may be
- the memory of windows above this one and may not necessarily belong to
- this window unless you assure that this is the top window.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hwnd</code>
- <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>
- or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>
- <dt><code>rect</code>
- <dd>The location to be copied
-
- <dt><code>plane</code>
- <dd>Specifies the color plane to get from
- <dt><code>dest</code>
- <dd>The location to copy the memory region
- <dt><code>deststride</code>
- <dd>The width, in bytes, of the dest memory
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.3.26 <a name="nxfilltrapezoid"><code>nx_filltrapezoid()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-int nx_filltrapezoid(NXWINDOW hwnd, FAR const struct nxgl_rect_s *clip,
- FAR const struct nxgl_trapezoid_s *trap,
- nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
-</pre></ul>
-<p>
- <b>Description:</b>
- Fill the specified trapezoidal region in the window with the specified color.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hwnd</code>
- <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>
- or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>
- <dt><code>clip</code>
- <dd>Clipping rectangle relative to window (may be null)
- <dt><code>trap</code>
- <dd>The trapezoidal region to be filled
- <dt><code>color</code>
- <dd>The color to use in the fill
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.3.27 <a name="nxdrawline"><code>nx_drawline()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-int nx_drawline(NXWINDOW hwnd, FAR struct nxgl_vector_s *vector,
- nxgl_coord_t width, nxgl_mxpixel_t color[CONFIG_NX_NPLANES],
- uint8_t caps);
-</pre></ul>
-<p>
- <b>Description:</b>
- Fill the specified trapezoidal region in the window with the specified color.
- Fill the specified line in the window with the specified color.
- This is simply a wrapper that uses <code>nxgl_splitline()</code> to break the line into
- trapezoids and then calls <code>nx_filltrapezoid()</code> to render the line.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hwnd</code>
- <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>
- or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>
- <dt><code>vector</code>
- <dd>Describes the line to be drawn.
- <dt><code>width</code>
- <dd>The width of the line
- <dt><code>color</code>
- <dd>The color to use to fill the line
- <dt><code>caps</code>
- <dd>Draw a circular cap on the ends of the line to support better line joins.
- One of:
-<ul><pre>
-/* Line caps */
-
-#define NX_LINECAP_NONE 0x00, /* No line caps */
-#define NX_LINECAP_PT1 0x01 /* Line cap on pt1 on of the vector only */
-#define NX_LINECAP_PT2 0x02 /* Line cap on pt2 on of the vector only */
-#define NX_LINECAP_BOTH 0x03 /* Line cap on both ends of the vector only */
-</pre></ul>
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.3.28 <a name="nxdrawcircle"><code>nx_drawcircle()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-int nx_drawcircle(NXWINDOW hwnd, FAR const struct nxgl_point_s *center,
- nxgl_coord_t radius, nxgl_coord_t width,
- nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
-</pre></ul>
-<p>
- <b>Description:</b>
- Draw a circular outline using the specified line thickness and color.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hwnd</code>
- <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>
- or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>
- <dt><code>center</code>
- <dd>A pointer to the point that is the center of the circle.
- <dt><code>radius</code>
- <dd>The radius of the circle in pixels.
- <dt><code>width</code>
- <dd>The width of the line
- <dt><code>color</code>
- <dd>The color to use to fill the line
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.3.29 <a name="nxfillcircle"><code>nx_fillcircle()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-int nx_fillcircle(NXWINDOW hwnd, FAR const struct nxgl_point_s *center,
- nxgl_coord_t radius, nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
-</pre></ul>
-<p>
- <b>Description:</b>
- Fill a circular region using the specified color.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hwnd</code>
- <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>
- or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>
- <dt><code>center</code>
- <dd>A pointer to the point that is the center of the circle.
- <dt><code>radius</code>
- <dd>The width of the line
- <dt><code>color</code>
- <dd>The color to use to fill the circle
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.3.30 <a name="nxglrgb2yuv"><code>nx_setbgcolor()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-int nx_setbgcolor(NXHANDLE handle,
- nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
-</pre></ul>
-<p>
- <b>Description:</b> Set the color of the background.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>handle</code>
- <dd>The handle created by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>
- or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>
- <dt><code>color</code>
- <dd>The color to use in the background
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.3.31 <a name="nxmove"><code>nx_move()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-int nx_move(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect,
- FAR const struct nxgl_point_s *offset);
-</pre></ul>
-<p>
- <b>Description:</b> Move a rectangular region within the window.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hwnd</code>
- <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>
- or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a> that specifies
- the window within which the move is to be done
- <dt><code>rect</code>
- <dd>Describes the (source) rectangular region to move
- <dt><code>offset</code>
- <dd>The offset to move the region
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.3.32 <a name="nxbitmap"><code>nx_bitmap()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-int nx_bitmap(NXWINDOW hwnd, FAR const struct nxgl_rect_s *dest,
- FAR const void *src[CONFIG_NX_NPLANES],
- FAR const struct nxgl_point_s *origin,
- unsigned int stride);
-</pre></ul>
-<p>
- <b>Description:</b>
- Copy a rectangular region of a larger image into the rectangle in the
- specified window.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hwnd</code>
- <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>
- or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a> that specifies the
- window that will receive the bitmap image.
- <dt><code>dest</code>
- <dd> Describes the rectangular on the display that will receive the bit map.
- <dt><code>src</code>
- <dd>The start of the source image. This is an array source images of size
- <code>CONFIG_NX_NPLANES</code> (probably 1).
- <dt><code>origin</code>
- <dd>The origin of the upper, left-most corner of the full bitmap.
- Both dest and origin are in window coordinates, however, the origin
- may lie outside of the display.
- <dt><code>stride</code>
- <dd>The width of the full source image in bytes.
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.3.33 <a name="nxkbdin"><code>nx_kbdin()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-#ifdef CONFIG_NX_KBD
-int nx_kbdchin(NXHANDLE handle, uint8_t ch);
-int nx_kbdin(NXHANDLE handle, uint8_t nch, FAR const uint8_t *ch);
-#endif
-</pre></ul>
-<p>
- <b>Description:</b>
- Used by a thread or interrupt handler that manages some kind of keypad
- hardware to report text information to the NX server. That text
- data will be routed by the NX server to the appropriate window client.
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.3.34 <a name="nxmousein"><code>nx_mousein()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-
-#ifdef CONFIG_NX_XYINPUT
-int nx_mousein(NXHANDLE handle, nxgl_coord_t x, nxgl_coord_t y, uint8_t buttons);
-#endif
-</pre></ul>
-<p>
- <b>Description:</b>
- Used by a thread or interrupt handler that manages some kind of pointing
- hardware to report new positional data to the NX server. That positional
- data will be routed by the NX server to the appropriate window client.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code></code>
- <dd>
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h2>2.4 <a name="nxtk2">NX Tool Kit (<code>NXTK</code>)</a></h2>
-
-<p>
- NXTK implements where the <i>framed window</i>.
- NX framed windows consist of three components within one NX window:
-</p>
-<ol>
- <li>The window <i>border</i>,</li>
- <li>The main <i>client window</i> area, and</li>
- <li>A <i>toolbar</i> area</li>
-</ol>
-
-<p>
- Each sub-window represents a region within one window.
- <a href="#screenshot">Figure 1</a> shows some simple NX framed windows.
- NXTK allows these sub-windows to be managed more-or-less independently:
-</p>
-<ul>
- <li>
- Each component has its own callbacks for redraw and position events
- as well as mouse and keyboard inputs.
- The client sub-window callbacks are registered when the framed window is
- created with a call to <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>;
- Separate toolbar sub-window callbacks are reigistered when the toolbar
- is added using <a href="#nxtkopentoolbar"><code>nxtk_opentoolbar()</code></a>.
- (NOTES: (1) only the client sub-window receives keyboard input and,
- (2) border callbacks are not currently accessible by the user).
- <li>
- </li>
- All position informational provided within the callback is relative
- to the specific sub-window.
- That is, the origin (0,0) of the coordinate system for each sub-window
- begins at the top left corner of the subwindow.
- This means that toolbar logic need not be concerned about client window
- geometry (and vice versa) and, for example, common toolbar logic can
- be used with different windows.
- </li>
-</ul>
-
-<h3>2.4.1 <a name="nxtktypes"><code>NXTK Types()</code></a></h3>
-
-<p>
- This is the handle that can be used to access the window data region.
-</p>
-<ul><pre>
-typedef FAR void *NXTKWINDOW;
-</pre></ul>
-
-<h3>2.4.2 <a name="nxtkblock"><code>nxtk_block()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_block(NXWINDOW hwnd, FAR void *arg);
-</pre></ul>
-<p>
- <b>Description:</b>
- The response to this function call is two things: (1) any queued callback messages to the window are 'blocked' and then (2) also subsequent window messaging is blocked.
-</p>
-<p>
- The <code>event</code> callback with the <code>NXEVENT_BLOCKED</code> event is the response from <code>nxtk_block()</code>. This blocking interface is used to assure that no further messages are are directed to the window. Receipt of the <code>NXEVENT_BLOCKED</code> event signifies that (1) there are no further pending callbacks and (2) that the window is now <i>defunct</i> and will receive no further callbacks.
-</p>
-<p>
- This callback supports coordinated destruction of a window. The client window logic must stay intact until all of the queued callbacks are processed. Then the window may be safely closed. Closing the window prior with pending callbacks can lead to bad behavior when the callback is executed.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul>
- <dl>
- <dt><code>wnd</code>
- <dd>The window to be blocked
- <dt><code>arg</code>
- <dd>An argument that will accompany the block messages (This is <code>arg2</code> in the event callback).
- </ul>
-</p>
-<p>
- <b>Returned Value:</b>
- OK on success; ERROR on failure with errno set appropriately.
-</p>
-
-<h3>2.4.3 <a name="nxtksynch"><code>nxtk_synch()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_synch(NXWINDOW hwnd, FAR void *arg);
-</pre></ul>
-<p>
- <b>Description:</b>
- This interface can be used to synchronize the window client with the NX server. It really just implements an <i>echo</i>: A synch message is sent from the window client to the server which then responds immediately by sending the <code>NXEVENT_SYNCHED</code> back to the windows client.
-</p>
-<p>
- Due to the highly asynchronous nature of client-server communications, <code>nx_synch()</code> is sometimes necessary to assure that the client and server are fully synchronized in time.
-</p>
-<p>
- Usage by the window client might be something like this:
-</p>
-<ul><pre>
- extern bool g_synched;
- extern sem_t g_synch_sem;
-
- g_synched = false;
- ret = nxtk_synch(hfwnd, handle);
- if (ret < 0)
- {
- -- Handle the error --
- }
-
- while (!g_synched)
- {
- ret = sem_wait(&g_sync_sem);
- if (ret < 0)
- {
- -- Handle the error --
- }
- }
-</pre></ul>
-<p>
- When the window listener thread receives the <code>NXEVENT_SYNCHED</code> event, it would set <code>g_synched</code> to <code>true</code> and post <code>g_synch_sem</code>, waking up the above loop.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>wnd</code>
- <dd>The window to be synched
- <dt><code>arg</code>
- <dd>An argument that will accompany the synch messages (This is <code>arg2</code> in the event callback).
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- OK on success; ERROR on failure with errno set appropriately
-</p>
-
-<h3>2.4.4 <a name="nxtkopenwindow"><code>nxtk_openwindow()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-#include <nuttx/nx/nxtk.h>
-
-NXTKWINDOW nxtk_openwindow(NXHANDLE handle, uint8_t flags,
- FAR const struct nx_callback_s *cb,
- FAR void *arg);
-</pre></ul>
-<p>
- <b>Description:</b> Create a new, framed window.
-</p>
-<p>
- <b>Input Parameters:</b>
- <dl>
- <dt><code>handle</code>
- <dd>The handle returned by <a href="#nxconnectinstance"><code>nx_connect()</code></a>.
- <dt><code>flags</code>
- <dd>Optional flags.
- These include:
- <ul>
- <li><code>NXBE_WINDOW_RAMBACKED</code>: Creates a RAM backed window.
- This option is only valid if <code>CONFIG_NX_RAMBACKED</code> is enabled.
- </li>
- <li><code>NXBE_WINDOW_HIDDEN</code>: The window is create in the HIDDEN state and can be made visible later with <code>nxtk_setvisibility()</code>.
- </li>
- </ul>
- <dt><code>cb</code>
- <dd>Callbacks used to process window events
- <dt><code>arg</code>
- <dd>User provided argument (see <a href="#nxopenwindow"><code>nx_openwindow()</code></a>)
- </dl>
-</p>
-<p>
- <b>Returned Value:</b>
-</p>
-<ul>
- Success: A non-NULL handle used with subsequent NXTK window accesses<br>
- Failure: NULL is returned and <code>errno</code> is set appropriately.
-</ul>
-
-<h3>2.4.5 <a name="nxtkclosewindow"><code>nxtk_closewindow()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_closewindow(NXTKWINDOW hfwnd);
-</pre></ul>
-<p>
- <b>Description:</b>
- Close the window opened by <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>.
-</p>
-<p>
- <b>Input Parameters:</b>
- <dl>
- <dt><code>hfwnd</code>
- <dd>A handle previously returned by
- <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>.
- </dl>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.4.6 <a name="nxtkgetposition"><code>nxtk_getposition()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_getposition(NXTKWINDOW hfwnd);
-</pre></ul>
-<p>
- <b>Description:</b>
- Request the position and size information for the selected framed window.
- The size/position for the client window and toolbar will be return
- asynchronously through the client callback function pointer.
-</p>
-<p>
- <b>Input Parameters:</b>
- <dl>
- <dt><code>hfwnd</code>
- <dd>A handle previously returned by
- <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>.
- </dl>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.4.7 <a name="nxtksetposition"><code>nxtk_setposition()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_setposition(NXTKWINDOW hfwnd, FAR struct nxgl_point_s *pos);
-</pre></ul>
-<p>
- <b>Description:</b>
- Set the position for the selected client window. This position does not
- include the offsets for the borders nor for any toolbar. Those offsets
- will be added in to set the full window position.
-</p>
-<p>
- <b>Input Parameters:</b>
- <dl>
- <dt><code>hfwnd</code>
- <dd>A handle previously returned by
- <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>.
- <dt><code>pos</code>
- <dd>The new position of the client sub-window
- </dl>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.4.8 <a name="nxtksetsize"><code>nxtk_setsize()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_setsize(NXTKWINDOW hfwnd, FAR struct nxgl_size_s *size);
-</pre></ul>
-<p>
- <b>Description:</b>
- Set the size for the selected client window. This size does not
- include the sizes of the borders nor for any toolbar. Those sizes
- will be added in to set the full window size.
-</p>
-<p>
- <b>Input Parameters:</b>
- <dl>
- <dt><code>hfwnd</code>
- <dd>A handle previously returned by
- <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>.
- <dt><code>size</code>
- <dd>The new size of the client sub-window.
- </dl>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.4.9 <a name="nxtkraise"><code>nxtk_raise()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_raise(NXTKWINDOW hfwnd);
-</pre></ul>
-<p>
- <b>Description:</b>
- Bring the window containing the specified client sub-window to the top
- of the display.
-</p>
-<p>
- <b>Input Parameters:</b>
- <dl>
- <dt><code>hfwnd</code>
- <dd>A handle previously returned by
- <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>
- specifying the window to be raised.
- <dt><code></code>
- <dd>
- </dl>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.4.10 <a name="nxtklower"><code>nxtk_lower()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_lower(NXTKWINDOW hfwnd);
-</pre></ul>
-<p>
- <b>Description:</b>
- Lower the window containing the specified client sub-window to the
- bottom of the display.
-</p>
-<p>
- <b>Input Parameters:</b>
- <dl>
- <dt><code>hfwnd</code>
- <dd>A handle previously returned by
- <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>
- specifying the window to be lowered.
- <dt><code></code>
- <dd>
- </dl>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.4.11 <a name="nxtkmodal"><code>nxtk_modal()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_modal(NXWINDOW hwnd, bool modal);
-</pre></ul>
-<p>
- <b>Description:</b> May be used to either (1) raise a window to the top of the display and select modal behavior, or (2) disable modal behavior.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hwnd</code>
- <dd>The handle returned by <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a> specifying the window to be modified.
- <dt><code>modal</code>
- <dd>True: enter modal state; False: leave modal state
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.4.12 <a name="nxtksetvisibility"><code>nxtk_setvisibility()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_setvisibility(NXWINDOW hwnd, bool hide);
-</pre></ul>
-<p>
- <b>Description:</b> Select if the window is visible or hidden.
- A hidden window is still present and will update normally, but will not be visible on the display until it is unhidden.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hwnd</code>
- <dd>The handle returned by <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a> specifying the window to be modified.
- <dt><code>hide</code>
- <dd>True: Window will be hidden; false: Window will be visible
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.4.13 <a name="nxtkishidden"><code>nxtk_ishidden()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxtk.h>
-
-bool nxtk_ishidden(NXTKWINDOW hfwnd);
-</pre></ul>
-<p>
- <b>Description:</b> Return true if the window is hidden.
-</p>
-<p>
- <b>NOTE</b>: There will be a delay between the time that the visibility of the window is changed via <a href="#nxtksetvisibility"><code>nxtk_setvisibily()</code></a> before that new setting is reported by <code>nxtk_ishidden()</code>.
- <code>nxtk_synch()</code> may be used if temporal synchronization is required.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hfwnd</code>
- <dd>The handle returned by <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a> that identifies the window to be queried.
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <i>True</i>: the window is hidden, <i>false</i>: the window is visible
-</p>
-
-<h3>2.4.14 <a name="nxtkfillwindow"><code>nxtk_fillwindow()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_fillwindow(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect,
- nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
-</pre></ul>
-<p>
- <b>Description:</b>
- Fill the specified rectangle in the client window with the specified color.
-</p>
-<p>
- <b>Input Parameters:</b>
- <dl>
- <dt><code>hfwnd</code>
- <dd>A handle previously returned by
- <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>.
- <dt><code>rect</code>
- <dd>The location within the client window to be filled
- <dt><code>color</code>
- <dd>The color to use in the fill
- </dl>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.4.15 <a name="nxtkgetwindow"><code>nxtk_getwindow()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-#include <nuttx/nx/nxtk.h>
-
-void nxtk_getwindow(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect,
- unsigned int plane, FAR uint8_t *dest,
- unsigned int deststride);
-</pre></ul>
-<p>
- <b>Description:</b>
- Get the raw contents of graphic memory within a rectangular region. NOTE:
- Since raw graphic memory is returned, the returned memory content may be
- the memory of windows above this one and may not necessarily belong to
- this window unless you assure that this is the top window.</p>
-<p>
- <b>Input Parameters:</b>
- <dl>
- <dt><code>hfwnd</code>
- <dd>A handle previously returned by
- <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>.
- <dt><code>rect</code>
- <dd>The location within the client window to be retrieved.
-
- <dt><code>plane</code>
- <dd>Specifies the color plane to get from.
- <dt><code>dest</code>
- <dd>The location to copy the memory region
- <dt><code>deststride</code>
- <dd>The width, in bytes, of the dest memory
- </dl>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.4.16 <a name="nxtkfilltrapwindow"><code>nxtk_filltrapwindow()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_filltrapwindow(NXTKWINDOW hfwnd,
- FAR const struct nxgl_trapezoid_s *trap,
- nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
-</pre></ul>
-<p>
- <b>Description:</b>
- Fill the specified trapezoid in the client window with the specified color
-</p>
-<p>
- <b>Input Parameters:</b>
- <dl>
- <dt><code>hfwnd</code>
- <dd>A handle previously returned by
- <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>.
- <dt><code>trap</code>
- <dd>The trapezoidal region to be filled.
- <dt><code>color</code>
- <dd>The color to use in the fill.
- </dl>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.4.17 <a name="nxtkdrawlinewindow"><code>nxtk_drawlinewindow()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_drawlinewindow(NXTKWINDOW hfwnd, FAR struct nxgl_vector_s *vector,
- nxgl_coord_t width, nxgl_mxpixel_t color[CONFIG_NX_NPLANES],
- uint8_t caps);
-</pre></ul>
-<p>
- <b>Description:</b>
- Fill the specified trapezoidal region in the window with the specified color.
- Fill the specified line in the window with the specified color.
- This is simply a wrapper that uses <code>nxgl_splitline()</code> to break the line into
- trapezoids and then calls <code>nxtk_filltrapwindow()</code> to render the line.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hfwnd</code>
- <dd>A handle previously returned by
- <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>.
- <dt><code>vector</code>
- <dd>Describes the line to be drawn.
- <dt><code>width</code>
- <dd>The width of the line
- <dt><code>color</code>
- <dd>The color to use to fill the line
- <dt><code>caps</code>
- <dd>Draw a circular cap on the ends of the line to support better line joins.
- One of:
-<ul><pre>
-/* Line caps */
-
-#define NX_LINECAP_NONE 0x00, /* No line caps */
-#define NX_LINECAP_PT1 0x01 /* Line cap on pt1 on of the vector only */
-#define NX_LINECAP_PT2 0x02 /* Line cap on pt2 on of the vector only */
-#define NX_LINECAP_BOTH 0x03 /* Line cap on both ends of the vector only */
-</pre></ul>
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.4.18 <a name="nxtkdrawcirclewindow"><code>nxtk_drawcirclewindow()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_drawcirclewindow(NXTKWINDOW hfwnd, FAR const struct nxgl_point_s *center,
- nxgl_coord_t radius, nxgl_coord_t width,
- nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
-</pre></ul>
-<p>
- <b>Description:</b>
- Draw a circular outline using the specified line thickness and color.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hfwnd</code>
- <dd>A handle previously returned by
- <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>.
- <dt><code>center</code>
- <dd>A pointer to the point that is the center of the circle.
- <dt><code>radius</code>
- <dd>The radius of the circle in pixels.
- <dt><code>width</code>
- <dd>The width of the line
- <dt><code>color</code>
- <dd>The color to use to fill the line
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.4.19 <a name="nxtkfillcirclewindow"><code>nxtk_fillcirclewindow()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_fillcirclewindow(NXWINDOW hfwnd, FAR const struct nxgl_point_s *center,
- nxgl_coord_t radius, nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
-</pre></ul>
-<p>
- <b>Description:</b>
- Fill a circular region using the specified color.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hfwnd</code>
- <dd>A handle previously returned by
- <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>.
- <dt><code>center</code>
- <dd>A pointer to the point that is the center of the circle.
- <dt><code>radius</code>
- <dd>The width of the line
- <dt><code>color</code>
- <dd>The color to use to fill the circle
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.4.20 <a name="nxtkmovewindow"><code>nxtk_movewindow()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_movewindow(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect,
- FAR const struct nxgl_point_s *offset);
-</pre></ul>
-<p>
- <b>Description:</b>
- Move a rectangular region within the client sub-window of a framed window.
-</p>
-<p>
- <b>Input Parameters:</b>
- <dl>
- <dt><code>hfwnd</code>
- <dd>A handle previously returned by
- <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>
- specifying the client sub-window within which the move is to be done.
- <dt><code>rect</code>
- <dd>Describes the rectangular region relative to the client sub-window to move.
- <dt><code>offset</code>
- <dd>The offset to move the region
- </dl>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.4.21 <a name="nxtkbitmapwindow"><code>nxtk_bitmapwindow()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_bitmapwindow(NXTKWINDOW hfwnd,
- FAR const struct nxgl_rect_s *dest,
- FAR const void *src[CONFIG_NX_NPLANES],
- FAR const struct nxgl_point_s *origin,
- unsigned int stride);
-</pre></ul>
-<p>
- <b>Description:</b>
- Copy a rectangular region of a larger image into the rectangle in the
- specified client sub-window.
-</p>
-<p>
- <b>Input Parameters:</b>
- <dl>
- <dt><code>hfwnd</code>
- <dd>A handle previously returned by
- <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>
- specifying the client sub-window that will receive the bitmap.
- <dt><code>dest</code>
- <dd>Describes the rectangular region on in the client sub-window
- will receive the bit map.
- <dt><code>src</code>
- <dd>The start of the source image(s). This is an array source
- images of size <code>CONFIG_NX_NPLANES</code> (probably 1).
- <dt><code>origin</code>
- <dd>The origin of the upper, left-most corner of the full bitmap.
- Both dest and origin are in sub-window coordinates, however, the
- origin may lie outside of the sub-window display.
- <dt><code>stride</code>
- <dd>The width of the full source image in pixels.
- </dl>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.4.22 <a name="nxtkopentoolbar"><code>nxtk_opentoolbar()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_opentoolbar(NXTKWINDOW hfwnd, nxgl_coord_t height,
- FAR const struct nx_callback_s *cb,
- FAR void *arg);
-</pre></ul>
-<p>
- <b>Description:</b>
- Create a tool bar at the top of the specified framed window.
-</p>
-<p>
- <b>Input Parameters:</b>
- <dl>
- <dt><code>hfwnd</code>
- <dd>A handle previously returned by
- <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>.
- <dt><code>height</code>
- <dd>The requested height of the toolbar in pixels.
- <dt><code>cb</code>
- <dd>Callbacks used to process toolbar events.
- <dt><code>arg</code>
- <dd>User provided value that will be returned with toolbar callbacks.
- </dl>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.4.23 <a name="nxtkclosetoolbar"><code>nxtk_closetoolbar()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_closetoolbar(NXTKWINDOW hfwnd);
-</pre></ul>
-<p>
- <b>Description:</b>
- Remove the tool bar at the top of the specified framed window.
-</p>
-<p>
- <b>Input Parameters:</b>
- <dl>
- <dt><code>hfwnd</code>
- <dd>A handle previously returned by
- <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>.
- <dt><code></code>
- <dd>
- </dl>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.4.24 <a name="nxtkfilltoolbar"><code>nxtk_filltoolbar()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_filltoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect,
- nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
-</pre></ul>
-<p>
- <b>Description:</b>
- Fill the specified rectangle in the toolbar sub-window with the specified color.
-</p>
-<p>
- <b>Input Parameters:</b>
- <dl>
- <dt><code>hfwnd</code>
- <dd>A handle previously returned by
- <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>.
- <dt><code>rect</code>
- <dd>The location within the toolbar window to be filled.
- <dt><code>color</code>
- <dd>The color to use in the fill.
- </dl>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.4.25 <a name="nxtkgettoolbar"><code>nxtk_gettoolbar()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_gettoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect,
- unsigned int plane, FAR uint8_t *dest,
- unsigned int deststride);
-</pre></ul>
-<p>
- <b>Description:</b>
- Get the raw contents of graphic memory within a rectangular region. NOTE:
- Since raw graphic memory is returned, the returned memory content may be
- the memory of windows above this one and may not necessarily belong to
- this window unless you assure that this is the top window.
-</p>
-<p>
- <b>Input Parameters:</b>
- <dl>
- <dt><code>hfwnd</code>
- <dd>A handle previously returned by
- <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>.
- <dt><code>rect</code>
- <dd>The location within the toolbar window to be retrieved.
-
- <dt><code>plane</code>
- <dd>TSpecifies the color plane to get from.
- <dt><code>dest</code>
- <dd>TThe location to copy the memory region.
- <dt><code>deststride</code>
- <dd>The width, in bytes, of the dest memory.
- </dl>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.4.26 <a name="nxtkfilltraptoolbar"><code>nxtk_filltraptoolbar()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_filltraptoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_trapezoid_s *trap,
- nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
-</pre></ul>
-<p>
- <b>Description:</b>
- Fill the specified trapezoid in the toolbar sub-window with the specified color.
-</p>
-<p>
- <b>Input Parameters:</b>
- <dl>
- <dt><code>hfwnd</code>
- <dd>A handle previously returned by
- <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>.
- <dt><code>trap</code>
- <dd>The trapezoidal region to be filled
- <dt><code>color</code>
- <dd>The color to use in the fill
- </dl>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.4.27 <a name="nxtkdrawlinetoolbar"><code>nxtk_drawlinetoolbar()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_drawlinetoolbar(NXTKWINDOW hfwnd, FAR struct nxgl_vector_s *vector,
- nxgl_coord_t width, nxgl_mxpixel_t color[CONFIG_NX_NPLANES],
- uint8_t caps);
-
-</pre></ul>
-<p>
- <b>Description:</b>
- Fill the specified line in the toolbar sub-window with the specified color.
- This is simply a wrapper that uses <code>nxgl_splitline()</code> to break the line into
- trapezoids and then calls <code>nxtk_filltraptoolbar()</code> to render the line.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hfwnd</code>
- <dd>A handle previously returned by
- <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>.
- <dt><code>vector</code>
- <dd>Describes the line to be drawn.
- <dt><code>width</code>
- <dd>The width of the line
- <dt><code>color</code>
- <dd>The color to use to fill the line
- <dt><code>caps</code>
- <dd>Draw a circular cap on the ends of the line to support better line joins.
- One of:
-<ul><pre>
-/* Line caps */
-
-#define NX_LINECAP_NONE 0x00, /* No line caps */
-#define NX_LINECAP_PT1 0x01 /* Line cap on pt1 on of the vector only */
-#define NX_LINECAP_PT2 0x02 /* Line cap on pt2 on of the vector only */
-#define NX_LINECAP_BOTH 0x03 /* Line cap on both ends of the vector only */
-</pre></ul>
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.4.28 <a name="nxtkdrawcircletoolbar"><code>nxtk_drawcircletoolbar()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_drawcircletoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_point_s *center,
- nxgl_coord_t radius, nxgl_coord_t width,
- nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
-</pre></ul>
-<p>
- <b>Description:</b>
- Draw a circular outline using the specified line thickness and color.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hfwnd</code>
- <dd>A handle previously returned by
- <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>.
- <dt><code>center</code>
- <dd>A pointer to the point that is the center of the circle.
- <dt><code>radius</code>
- <dd>The radius of the circle in pixels.
- <dt><code>width</code>
- <dd>The width of the line
- <dt><code>color</code>
- <dd>The color to use to fill the line
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.4.29 <a name="nxtkfillcircletoolbar"><code>nxtk_fillcircletoolbar()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_fillcircletoolbar(NXWINDOW hfwnd, FAR const struct nxgl_point_s *center,
- nxgl_coord_t radius, nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
-</pre></ul>
-<p>
- <b>Description:</b>
- Fill a circular region using the specified color.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hfwnd</code>
- <dd>A handle previously returned by
- <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>.
- <dt><code>center</code>
- <dd>A pointer to the point that is the center of the circle.
- <dt><code>radius</code>
- <dd>The width of the line
- <dt><code>color</code>
- <dd>The color to use to fill the circle
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.4.30 <a name="nxtkmovetoolbar"><code>nxtk_movetoolbar()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_movetoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect,
- FAR const struct nxgl_point_s *offset);
-</pre></ul>
-<p>
- <b>Description:</b>
- Move a rectangular region within the toolbar sub-window of a framed window.
-</p>
-<p>
- <b>Input Parameters:</b>
- <dl>
- <dt><code>hfwnd</code>
- <dd>A handle identifying sub-window containing the toolbar within which the move is
- to be done.
- This handle must have previously been returned by
- <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>.
- <dt><code>rect</code>
- <dd>Describes the rectangular region relative to the toolbar sub-window to move.
- <dt><code>offset</code>
- <dd>The offset to move the region
- </dl>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h3>2.4.31 <a name="nxtkbitmaptoolbar"><code>nxtk_bitmaptoolbar()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nx.h>
-#include <nuttx/nx/nxtk.h>
-
-int nxtk_bitmaptoolbar(NXTKWINDOW hfwnd,
- FAR const struct nxgl_rect_s *dest,
- FAR const void *src[CONFIG_NX_NPLANES],
- FAR const struct nxgl_point_s *origin,
- unsigned int stride);
-</pre></ul>
-<p>
- <b>Description:</b>
- Copy a rectangular region of a larger image into the rectangle in the
- specified toolbar sub-window.
-</p>
-<p>
- <b>Input Parameters:</b>
- <dl>
- <dt><code>hfwnd</code>
- <dd>A handle previously returned by
- <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>.
- <dt><code>dest</code>
- <dd>Describes the rectangular region on in the toolbar sub-window
- will receive the bit map.
- <dt><code>src</code>
- <dd>The start of the source image.
- <dt><code>origin</code>
- <dd>The origin of the upper, left-most corner of the full bitmap.
- Both dest and origin are in sub-window coordinates, however, the
- origin may lie outside of the sub-window display.
- <dt><code>stride</code>
- <dd>The width of the full source image in bytes.
- </dl>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately
-</p>
-
-<h2>2.5 <a name="nxfonts2">NX Fonts Support (<code>NXFONTS</code>)</a></h2>
-
-<h3>2.5.1 <a name="nxfontstypes"><code>NXFONTS Types()</code></a></h3>
-<p>
- This structures provides the metrics for one glyph:
-</p>
-<ul><pre>
-struct nx_fontmetric_s
-{
- uint32_t stride : 2; /* Width of one font row in bytes */
- uint32_t width : 6; /* Width of the font in bits */
- uint32_t height : 6; /* Height of the font in rows */
- uint32_t xoffset : 6; /* Top, left-hand corner X-offset in pixels */
- uint32_t yoffset : 6; /* Top, left-hand corner y-offset in pixels */
- uint32_t unused : 6;
-};
-</pre></ul>
-
-<p>
- This structure binds the glyph metrics to the glyph bitmap:
-</p>
-<ul><pre>
-struct nx_fontbitmap_s
-{
- struct nx_fontmetric_s metric; /* Character metrics */
- FAR const uint8_t *bitmap; /* Pointer to the character bitmap */
-};
-</pre></ul>
-
-<p>
- This structure describes one contiguous grouping of glyphs that
- can be described by an array starting with encoding <code>first</code> and
- extending through (<code>first</code> + <code>nchars</code> - 1).
-</p>
-<ul><pre>
-struct nx_fontset_s
-{
- uint8_t first; /* First bitmap character code */
- uint8_t nchars; /* Number of bitmap character codes */
- FAR const struct nx_fontbitmap_s *bitmap;
-};
-</pre></ul>
-
-<p>
- This structure describes the overall fontset:
-</p>
-<ul><pre>
-struct nx_font_s
-{
- uint8_t mxheight; /* Max height of one glyph in rows */
- uint8_t mxwidth; /* Max width of any glyph in pixels */
- uint8_t mxbits; /* Max number of bits per character code */
- uint8_t spwidth; /* The width of a space in pixels */
-};
-</pre></ul>
-
-<h3>2.5.2 <a name="nxfgetfonthandle"><code>nxf_getfonthandle()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxfonts.h>
-
-NXHANDLE nxf_getfonthandle(enum nx_fontid_e fontid);
-</pre></ul>
-<p>
- <b>Description:</b>
- Given a numeric font ID, return a handle that may be subsequently be used to access the font data sets.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>fontid</code>
- <dd>Identifies the font set to use
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- A handle that may be subsequently be used to access the font data sets.
-</p>
-
-<h3>2.5.3 <a name="nxfgetfontset"><code>nxf_getfontset()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nxfonts.h>
-
-FAR const struct nx_font_s *nxf_getfontset(NXHANDLE handle);
-</pre></ul>
-<p>
- <b>Description:</b>
- Return information about the current font set.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>handle</code>
- <dd>A font handle previously returned by <a href="#nxfgetfonthandle"><code>nxf_getfonthandle()</code></a>.
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- An instance of <code>struct nx_font_s</code> describing the font set.
-</p>
-
-<h3>2.5.4 <a name="nxfgetbitmap"><code>nxf_getbitmap()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nxfonts.h>
-
-FAR const struct nx_fontbitmap_s *nxf_getbitmap(NXHANDLE handle, uint16_t ch);
-</pre></ul>
-<p>
- <b>Description:</b>
- Return font bitmap information for the selected character encoding.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>ch</code>
- <dd>The char code for the requested bitmap.
- <dt><code>handle</code>
- <dd>A font handle previously returned by <a href="#nxfgetfonthandle"><code>nxf_getfonthandle()</code></a>.
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- An instance of <code>struct nx_fontbitmap_s</code> describing the glyph.
-</p>
-
-<h3>2.5.5 <a name="nxfconvertbpp"><code>nxf_convert_*bpp()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxglib.h>
-#include <nuttx/nx/nxfonts.h>
-
-int nxf_convert_2bpp(FAR uint8_t *dest, uint16_t height,
- uint16_t width, uint16_t stride,
- FAR const struct nx_fontbitmap_s *bm,
- nxgl_mxpixel_t color);
-int nxf_convert_4bpp(FAR uint8_t *dest, uint16_t height,
- uint16_t width, uint16_t stride,
- FAR const struct nx_fontbitmap_s *bm,
- nxgl_mxpixel_t color);
-int nxf_convert_8bpp(FAR uint8_t *dest, uint16_t height,
- uint16_t width, uint16_t stride,
- FAR const struct nx_fontbitmap_s *bm,
- nxgl_mxpixel_t color);
-int nxf_convert_16bpp(FAR uint16_t *dest, uint16_t height,
- uint16_t width, uint16_t stride,
- FAR const struct nx_fontbitmap_s *bm,
- nxgl_mxpixel_t color);
-int nxf_convert_24bpp(FAR uint32_t *dest, uint16_t height,
- uint16_t width, uint16_t stride,
- FAR const struct nx_fontbitmap_s *bm,
- nxgl_mxpixel_t color);
-int nxf_convert_32bpp(FAR uint32_t *dest, uint16_t height,
- uint16_t width, uint16_t stride,
- FAR const struct nx_fontbitmap_s *bm,
- nxgl_mxpixel_t color);
-</pre></ul>
-<p>
- <b>Description:</b> Convert the 1BPP font to a new pixel depth.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>dest</code>
- <dd>The destination buffer provided by the caller.
- <dt><code>height</code>
- <dd>The max height of the returned char in rows.
- <dt><code>width</code>
- <dd>The max width of the returned char in pixels.
- <dt><code>stride</code>
- <dd>The width of the destination buffer in bytes.
- <dt><code>bm</code>
- <dd>Describes the character glyph to convert
- <dt><code>color</code>
- <dd>The color to use for '1' bits in the font bitmap (0 bits are transparent).
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- <code>OK</code> on success;
- <code>ERROR</code> on failure with <code>errno</code> set appropriately.
-</p>
-
-
-
- <p>
- <i><b>2.6</b> <a href="#nxcursor"</a></i>
- </p>
- <p>
- <ul>
- <i>2.6.1 <a href="#"><code>()</code></a></i><br>
- <i>2.6.2 <a href="#"><code>()</code></a></i><br>
- <i>2.6.3 <a href="#"><code>()</code></a></i><br>
- </ul>
- </p>
-
-<h2>2.6 <a name="nxcursor">NX Cursor Support (<code>NXCURSOR</code>)</a></h2>
-
-<h3>2.6.1 <a name="nxcursorenable"><code>nxcursor_enable()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxcursor.h>
-
-#ifdef CONFIG_NX_SWCURSOR
-int nxcursor_enable(NXHANDLE hnd, bool enable);
-#endif
-</pre></ul>
-<p>
- <b>Description:</b>
- Enable/disable presentation of the cursor. The disabled cursor still exits and still may be controlled, but is not visible on the display.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hnd</code>
- <dd>The server handle returned by <a href="#nxconnectinstance"><code>nx_connect()</code></a>.
- <dt><code>enable</code>
- <dd>The new cursor position
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- OK on success; ERROR on failure with errno set appropriately.
-</p>
-
-<h3>2.6.2 <a name="nxcursorsetimage"><code>nxcursor_setimage()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxcursor.h>
-
-#ifdef CONFIG_NX_SWCURSOR
-int nxcursor_setimage(NXHANDLE hnd, FAR const struct nx_cursorimage_s *image);
-#endif
-</pre></ul>
-<p>
- <b>Description:</b>
- Set the cursor image.
-</p>
-<p>
- The image is provided a a 2-bits-per-pixel image. The two bit incoding is as following:
-</p>
-<ul>
- 00 - The transparent background.<br>
- 01 - Color1: The main color of the cursor.<br>
- 10 - Color2: The color of any border.<br>
- 11 - Color3: A blend color for better imaging (fake anti-aliasing).<br>
-</ul>
-<p>
- <b>NOTE:</b> The NX logic will reference the user image buffer repeatedly. That image buffer must persist for as long as the NX server connection persists.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hnd</code>
- <dd>The server handle returned by <a href="#nxconnectinstance"><code>nx_connect()</code></a>.
- <dt><code>image</code>
- <dd>An instance of <code>struct struct nx_cursorimage_s</code> that describes the cursor image. See <code> <nuttx/nx/nxcursor.h></code> for the full description of this structure.
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- OK on success; ERROR on failure with errno set appropriately.
-</p>
-
-<h3>2.6.3 <a name="nxcursorsetposition"><code>nxcursor_setposition()</code></a></h3>
-<p><b>Function Prototype:</b></p>
-<ul><pre>
-#include <nuttx/nx/nxcursor.h>
-
-#ifdef CONFIG_NX_SWCURSOR
-int nxcursor_setposition(NXHANDLE hnd, FAR const struct nxgl_point_s *pos);
-#endif
-</pre></ul>
-<p>
- <b>Description:</b>
- Move the cursor to the specified position.
-</p>
-<p>
- <b>Input Parameters:</b>
- <ul><dl>
- <dt><code>hnd</code>
- <dd>The server handle returned by <a href="#nxconnectinstance"><code>nx_connect()</code></a>.
- <dt><code>pos</code>
- <dd>The new cursor position
- </dl></ul>
-</p>
-<p>
- <b>Returned Value:</b>
- OK on success; ERROR on failure with errno set appropriately.
-</p>
-
-<h2>2.7 <a name="samplecode">Sample Code</a></h2>
-
-<p><b><code>apps/examples/nx*</code></b>.
- No sample code is provided in this document.
- However, examples can be found in the NuttX source tree at the follow locations:
- That example code is intended to test NX.
- Since it is test code, it is designed to exercise functionality and does not necessarily represent best NX coding practices.
-</p>
-<ul>
- <li><code>apps/examples/nx</code>.
- This is a test of windows, optionally with toolbars.
- Two windows are created, re-sized, moved, raise lowered.
- Simulated mouse and keyboard input is provided.
- </li>
- <li><code>apps/examples/nxhello</code>.
- This is intended to be simplest NX test:
- It simply displays the words "Hello, World!" centered on the display.
- </li>
- <li><code>apps/examples/nxtext</code>.
- This illustrates how fonts may be managed to provide scrolling text windows.
- Pop-up windows are included to verify the clipping and re-drawing of the text display.
- </li>
-</ul>
-
-<p>
- In its current form, the NX graphics system provides a low level of graphics and window
- support.
- Most of the complexity of manage redrawing and handling mouse and keyboard events must
- be implemented by the NX client code.
-</p>
-
-<p><b>Building <code>apps/examples/nx</code></b>.
- Testing was performed using the Linux/Cygwin-based NuttX simulator.
- Instructions are provided for building that simulation are provided in
- <a href="#testcoverage">Appendix C</a> of this document.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <h1>Appendix A <a name="grapicsdirs"><code>graphics/</code> Directory Structure</a></h1>
- </td>
- </tr>
-</table>
-
-<p>
- The graphics capability consist both of components internal to the RTOS and of user-callable interfaces.
- In the NuttX kernel mode build there are some components of the graphics subsystem are callable in user mode and other components that are internal to the RTOS.
- The directory <code>nuttx/graphics</code> contains only those components that are internal to the RTOS.
-
- User callable functions must be part of a library that can be linked against user applications.
- This user callable interfaces are provided in sub-directories under <code>nuttx/libnx</code>.
-<p>
-<ul>
- <dl>
- <dt><code>libnx/nx</code>
- <dd>Common callable interfaces that are, logically, part of both nxmu and nxsu.
-
- <dt><code>graphics/nxglib</code> and <code>libnx/nxglib</code>
- <dd>The NuttX tiny graphics library.
- The directory contains generic utilities support operations on primitive graphics objects
- and logic to rasterize directly into a framebuffer or through an LCD driver interface.
- It has no concept of windows (other than the one, framebuffer or LCD window).
-
- <dt><code>graphics/nxbe</code>
- <dd>This is the <i>back-end</i> of a tiny windowing system.
- It can be used with either of two front-ends to complete a windowing system (see
- <code>nxmu</code> and <code>nxsu</code> below).
- It contains most of the important window management logic: clipping, window controls,
- window drawing, etc.
-
- <dt><code>graphics/nxmu</code> and <code>libnx/nxmu</code>
- <dd>This is the NX multi user <i>front end</i>.
- When combined with the generic <i>back-end</i> (<code>nxbe</code>), it implements a
- multi-threaded, multi-user windowing system.
- The files in this directory present the window APIs described in
- <code>include/nuttx/nx/nx.h</code>.
- The multi-user front end includes a graphics server that executes on its own thread;
- multiple graphics clients then communicate with the server via a POSIX message
- queue to serialize window operations from many threads.
-
- <dt><code>libnx/nxfonts</code>
- <dd>This is where the NXFONTS implementation resides.
- This is a relatively low-level set of charset set/glyph management APIs.
- See <code>include/nuttx/nx/nxfonts.h</code>.
-
- <dt><code>libnx/nxtk</code>
- <dd>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 <code>include/nuttx/nx/nxtk.h</code>.
-
- <dt><code>apps/graphics/NxWidgets</code>
- <dd>The <a href="NxWidgets.html">NxWidgets</a> code is provided as a separate package provided in the <code>apps/</code> repository.
-
- <dt><code>graphics/nxterm</code>
- <dd>The NxTerm driver is built on top of NX and works with the multi-user NX front-end.
- See <code>include/nuttx/nx/nxterm.h</code>.
- </dl>
-</ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <h1>Appendix B <a name="nxconfigs">NX Configuration Options</a></h1>
- </td>
- </tr>
-</table>
-
-<h2>B.1 <a name="nxgenconfig">General Configuration Settings</a></h2>
-
-<ul>
- <dl>
- <dt><code>CONFIG_NX</code>
- <dd>Enables overall support for graphics library and NX
- <dt><code>CONFIG_NX_RAMBACKED</code>
- <dd>Enables RAM backed window support.
- If this option is selected, then windows may be optionally created with a RAM framebuffer backing up the window content.
- Rending into the window will result in rending into the backup framebuffer, then updating the physical display from the framebuffer.
- <p>
- The advantage of this option is that the application that manages window will no longer receive redraw() callbacks.
- Those calls normally occur, for example, when a window "above" moves exposing a portion of the window below.
- If this option is selected, then the system will redraw the exposed portion of the window from the backup framebuffer without intervention of the window applications.
- This greatly reduces the complexity of the application and performance of the window at the expense of increased memory usage.
- </p>
- <p>
- An exception is the case when the window is resized to a wider and/or taller size.
- In that case, the redraw callback will till occur.
- It is necessary in that case to provide new graphic content for the extended window area.
- </p>
- <p>
- Redraw requests in other cases are also suppressed: Changes to window position, size, etc.
- </p>
- </dl>
-</ul>
-
-<h2>B.2 <a name="nxglconfig">NXGL Configuration Settings</a></h2>
-
-<ul>
- <dl>
- <dt><code>CONFIG_NX_NPLANES</code>:
- <dd>Some YUV color formats requires support for multiple planes,
- one for each color component. Unless you have such special
- hardware, this value should be undefined or set to 1.
- <dt><code>CONFIG_NX_DISABLE_1BPP</code>, <code>CONFIG_NX_DISABLE_2BPP</code>,
- <code>CONFIG_NX_DISABLE_4BPP</code>, <code>CONFIG_NX_DISABLE_8BPP</code>
- <code>CONFIG_NX_DISABLE_16BPP</code>, <code>CONFIG_NX_DISABLE_24BPP</code>, and
- <code>CONFIG_NX_DISABLE_32BPP</code>:
- <dd>NX supports a variety of pixel depths. You can save some
- memory by disabling support for unused color depths.
- <dt><code>CONFIG_NX_PACKEDMSFIRST</code>:
- <dd>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
- <dt><code>CONFIG_NX_LCDDRIVER</code>:
- <dd>By default, NX builds to use a framebuffer driver (see <code>include/nuttx/video/fb.h</code>).
- If this option is defined, NX will build to use an LCD driver (see <code>include/nuttx/lcd/lcd.h</code>).
- <dt><code>CONFIG_NX_ANTIALIASING</code>:
- <dd>Enable support for anti-aliasing when rendering lines as various
- orientations.
- This option is only available for use with frame buffer drivers and
- only with 16-, 24-, or 32-bit RGB color formats.
- </li>
- </dl>
-</ul>
-
-<h2>B.3 <a name="nxconfig">NX Configuration Settings</a></h2>
-
-<ul>
- <dl>
- <dt><code>CONFIG_NX_XYINPUT</code>:
- <dd>Build in support for an X/Y input such as a mouse or a touscreen.
- <dt><code>CONFIG_NX_KBD</code>:
- <dd>Build in support of keypad/keyboard input.
- <dt><code>CONFIG_NX_WRITEONLY</code>:
- <dd>Define if the underlying graphics device does not support read operations.
- Automatically defined if <code>CONFIG_NX_LCDDRIVER</code> and <code>CONFIG_LCD_NOGETRUN</code>
- are defined.
- </dl>
-</ul>
-
-<h2>B.4 <a name="nxmuconfig">NX Server Configuration Settings</a></h2>
-
-<ul>
- <dl>
- <dt><code>CONFIG_NX_BLOCKING</code>
- <dd>Open the client message queues in blocking mode. In this case,
- <code>nx_eventhandler()</code> will not return until a message is received and processed.
- <dt><code>CONFIG_NX_MXSERVERMSGS</code> and <code>CONFIG_NX_MXCLIENTMSGS</code>
- <dd>Specifies the maximum number of messages that can fit in
- the message queues. No additional resources are allocated, but
- this can be set to prevent flooding of the client or server with
- too many messages (<code>CONFIG_PREALLOC_MQ_MSGS</code> controls how many
- messages are pre-allocated).
- </dl>
-</ul>
-
-<h2>B.5 <a name="nxtkconfig">NXTK Configuration Settings</a></h2>
-
-<ul>
- <dl>
- <dt><code>CONFIG_NXTK_BORDERWIDTH</code>:
- <dd>Specifies the width of the border (in pixels) used with
- framed windows. The default is 4.
- <dt><code>CONFIG_NXTK_BORDERCOLOR1</code>, <code>CONFIG_NXTK_BORDERCOLOR2</code>, and <code>CONFIG_NXTK_BORDERCOLOR3</code>:
- <dd>Specify the colors of the border used with framed windows.
- <dt><code>CONFIG_NXTK_BORDERCOLOR2</code>
- <dd>The shadow side color and so is normally darker.
- <dt><code>CONFIG_NXTK_BORDERCOLOR3</code>
- <dd>The shiny side color and so is normally brighter.
- The default is medium, dark, and light grey, respectively
- <dt><code>CONFIG_NXTK_AUTORAISE</code>:
- <dd>If set, a window will be raised to the top if the mouse position
- is over a visible portion of the window. Default: A mouse
- button must be clicked over a visible portion of the window.
- </dl>
-</ul>
-
-<h2>B.6 <a name="nxfpmtsconfig">NXFONTS Configuration Settings</a></h2>
-
-<ul>
- <dl>
- <dt><code>CONFIG_NXFONTS_CHARBITS</code>:
- <dd>The number of bits in the character set. Current options are
- only 7 and 8. The default is 7.
- <dt><code>CONFIG_NXFONT_SANS17X22</code>:
- <dd>This option enables support for a tiny, 17x22 san serif font
- (font <code>ID FONTID_SANS17X22</code> == 14).
- <dt><code>CONFIG_NXFONT_SANS20X26</code>:
- <dd>This option enables support for a tiny, 20x26 san serif font
- (font <code>ID FONTID_SANS20X26</code> == 15).
- <dt><code>CONFIG_NXFONT_SANS23X27</code>:
- <dd>This option enables support for a tiny, 23x27 san serif font
- (font <code>ID FONTID_SANS23X27</code> == 1).
- <dt><code>CONFIG_NXFONT_SANS22X29</code>:
- <dd>This option enables support for a small, 22x29 san serif font
- (font <code>ID FONTID_SANS22X29</code> == 2).
- <dt><code>CONFIG_NXFONT_SANS28X37</code>:
- <dd>This option enables support for a medium, 28x37 san serif font
- (font <code>ID FONTID_SANS28X37</code> == 3).
- <dt><code>CONFIG_NXFONT_SANS39X48</code>:
- <dd>This option enables support for a large, 39x48 san serif font
- (font <code>ID FONTID_SANS39X48</code> == 4).
- <dt><code>CONFIG_NXFONT_SANS17X23B</code>:
- <dd>This option enables support for a tiny, 17x23 san serif bold font
- (font <code>ID FONTID_SANS17X23B</code> == 16).
- <dt><code>CONFIG_NXFONT_SANS20X27B</code>:
- <dd>This option enables support for a tiny, 20x27 san serif bold font
- (font <code>ID FONTID_SANS20X27B</code> == 17).
- <dt><code>CONFIG_NXFONT_SANS22X29B</code>:
- <dd>This option enables support for a small, 22x29 san serif bold font
- (font ID <code>FONTID_SANS22X29B</code> == 5).
- <dt><code>CONFIG_NXFONT_SANS28X37B</code>:
- <dd>This option enables support for a medium, 28x37 san serif bold font
- (font ID <code>FONTID_SANS28X37B</code> == 6).
- <dt><code>CONFIG_NXFONT_SANS40X49B</code>:
- <dd>This option enables support for a large, 40x49 san serif bold font
- (font ID <code>FONTID_SANS40X49B</code> == 7).
- <dt><code>CONFIG_NXFONT_SERIF22X29</code>:
- <dd>This option enables support for a small, 22x29 font (with serifs)
- (font ID <code>FONTID_SERIF22X29</code> == 8).
- <dt><code>CONFIG_NXFONT_SERIF29X37</code>:
- <dd>This option enables support for a medium, 29x37 font (with serifs)
- (font ID <code>FONTID_SERIF29X37</code> == 9).
- <dt><code>CONFIG_NXFONT_SERIF38X48</code>:
- <dd>This option enables support for a large, 38x48 font (with serifs)
- (font ID <code>FONTID_SERIF38X48</code> == 10).
- <dt><code>CONFIG_NXFONT_SERIF22X28B</code>:
- <dd>This option enables support for a small, 27x38 bold font (with serifs)
- (font ID <code>FONTID_SERIF22X28B</code> == 11).
- <dt><code>CONFIG_NXFONT_SERIF27X38B</code>:
- <dd>This option enables support for a medium, 27x38 bold font (with serifs)
- (font ID <code>FONTID_SERIF27X38B</code> == 12).
- <dt><code>CONFIG_NXFONT_SERIF38X49B</code>:
- <dd>This option enables support for a large, 38x49 bold font (with serifs)
- (font ID <code>FONTID_SERIF38X49B</code> == 13).
- </dl>
-</ul>
-
-<h2>B.7 <a name="nxtermconfig">NxTerm Configuration Settings</a></h2>
-
-<p>General NxTerm settings.</p>
-<ul>
- <dl>
- <dt><code>CONFIG_NXTERM</code>:
- <dd>Enables building of the NxTerm driver.
- </dl>
-</ul>
-
-<p>NxTerm output text/graphics options:</p>
-<ul>
- <dl>
- <dt><code>CONFIG_NXTERM_BPP</code>:
- <dd>Currently, NxTerm supports only a single pixel depth.
- This configuration setting must be provided to support that single pixel depth.
- Default: The smallest enabled pixel depth. (see <code>CONFIG_NX_DISABLE_*BPP</code>)
- <dt><code>CONFIG_NXTERM_CURSORCHAR</code>:
- <dd>The bitmap code to use as the cursor. Default '_'
- <dt><code>CONFIG_NXTERM_MXCHARS</code>:
- <dd>NxTerm needs to remember every character written to the console so that it can redraw the window.
- This setting determines the size of some internal memory allocations used to hold the character data.
- Default: 128.
- <dt><code>CONFIG_NXTERM_CACHESIZE</code>:
- <dd>
- NxTerm supports caching of rendered fonts.
- This font caching is required for two reasons:
- (1) First, it improves text performance, but more importantly
- (2) it preserves the font memory.
- Since the NX server runs on a separate server thread, it requires that the rendered font memory persist until the server has a chance to render the font.
- Unfortunately, the font cache would be quite large if all fonts were saved.
- The <code>CONFIG_NXTERM_CACHESIZE</code> setting will control the size of the font cache (in number of glyphs).
- Only that number of the most recently used glyphs will be retained.
- Default: 16.
- <blockquote>
- NOTE: There can still be a race condition between the NxTerm driver and the
- NX task. If you every see character corruption (especially when printing
- a lot of data or scrolling), then increasing the value of <code>CONFIG_NXTERM_CACHESIZE</code>
- is something that you should try.
- Alternatively, you can reduce the size of <code>CONFIG_MQ_MAXMSGSIZE</code> which will force NxTerm task to pace the server task.
- <code>CONFIG_NXTERM_CACHESIZE</code> should be larger than <code>CONFIG_MQ_MAXMSGSIZE</code> in any event.
- </blockquote>
- <dt><code>CONFIG_NXTERM_LINESEPARATION</code>:
- <dd>This the space (in rows) between each row of test. Default: 0
- <dt><code>CONFIG_NXTERM_NOWRAP</code>:
- <dd>By default, lines will wrap when the test reaches the right hand side of the window.
- This setting can be defining to change this behavior so that the text is simply truncated until a new line is encountered.
- </dl>
-</ul>
-
-<p>NxTerm input options:</p>
-<ul>
- <dl>
- <dt><code>CONFIG_NXTERM_NXKBDIN</code>:
- <dd>Take input from the NX keyboard input callback.
- By default, keyboard input is taken from stdin (<code>/dev/console</code>).
- If this option is set, then the interface<code>nxterm_kdbin()</code> is enabled.
- That interface may be driven by window callback functions so that keyboard input <i>only</i> goes to the top window.
- <dt><code>CONFIG_NXTERM_KBDBUFSIZE</code>:
- <dd>If <code>CONFIG_NXTERM_NXKBDIN</code> is enabled, then this value may be used to
- define the size of the per-window keyboard input buffer. Default: 16
- <dt><code>CONFIG_NXTERM_NPOLLWAITERS</code>:
- <dd>The number of threads that can be waiting for read data available.
- Default: 4
- </dl>
-</ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <h1>Appendix C <a name="installnewfonts">Installing New Fonts</a></h1>
- </td>
- </tr>
-</table>
-
-<p><b>The BDF Font Converter</b>.
- There is a tool called <i>bdf-converter</i> in the directory <code>tools/.</code>.
- The <i>bdf-converter</i> program be used to convert fonts in Bitmap Distribution Format (BDF) into fonts that can be used in the NX graphics system.
- The BDF format most well known as a font format traditionally used for X-11 bitmap fonts.
-</p>
-<blockquote><small>
- A Note about Font Copyrights:
- My understanding is that the underlying bitmap font data for traditional fonts cannot be copyrighted (the same is not true for scalable fonts).
- This is because a copyright covers only the form of delivery of the font and not the underlying font content and, at least for the traditional typefaces, the underlying font designs are ancient.
- There could be issues, however, if you convert from modern, trademarked images.
- However, remember that I am a programmer not an attorney and that my knowledge of font copyright issues is limited to what I glean by Googling.
-</small></blockquote>
-<p>
- <b>Font Installation Steps</b>,
- Below are general instructions for creating and installing a new font in the NX graphic system.
- The first two steps only apply if you are using the BDF font converter program.
-</p>
-<ol start="1">
- <li>
- <p>
- Locate a font in BDF format.
- There are many good BDF bitmap fonts bundled with X-11.
- See <a href="http://www.cl.cam.ac.uk/~mgk25/ucs-fonts.html">this link</a>, as an example,
- </p>
- </li>
- <li>
- <p>
- Use the <i>bdf-converter</i> program to convert the BDF font to the NuttX font format.
- This will result in a C header file containing definitions.
- That header file should be installed at, for example, <code>graphics/nxfonts/nxfonts_myfont.h</code>.
- </p>
- </li>
-</ol>
-<p>
- The remaining steps apply however you managed to create the NuttX C font header file.
- After you have your C font header file, the next thing to do is to create a new NuttX configuration variable to select the font.
- For example, suppose you define the following variable: <code>CONFIG_NXFONT_MYFONT</code>.
- Then you would need to:
-</p>
-<ol start="3">
- <li>
- <p>
- Define <code>CONFIG_NXFONT_MYFONT=y</code> in your NuttX configuration file.
- </p>
- </li>
-</ol>
-<p>
- A font ID number has to be assigned for each new font.
- The font IDs are defined in the file <code>include/nuttx/nx/nxfonts.h</code>.
- Those definitions have to be extended to support your new font.
- Look at how the font ID enabled by <code>CONFIG_NXFONT_SANS23X27</code> is defined and add an ID for yournew font in a similar fashion:
-</p>
-<ol start="4">
- <li>
- <p>
- <b><code>include/nuttx/nx/nxfonts.h</code></b>. Add you new font as a possible system default font:
- </p>
- <ul><pre>
-#if defined(CONFIG_NXFONT_SANS23X27)
-# define NXFONT_DEFAULT FONTID_SANS23X27
-#elif defined(CONFIG_NXFONT_MYFONT)
-# define NXFONT_DEFAULT FONTID_MYFONT
-#endif
-</pre></ul>
- <p>
- Then define the actual font ID.
- Make sure that the font ID value is unique:
- </p>
- <ul><pre>
-enum nx_fontid_e
-{
- FONTID_DEFAULT = 0 /* The default font */
-#ifdef CONFIG_NXFONT_SANS23X27
- , FONTID_SANS23X27 = 1 /* The 23x27 sans serif font */
-#endif
-#ifdef CONFIG_NXFONT_MYFONT
- , FONTID_MYFONT = 2 /* My shiny, new font */
-#endif
-...
-</pre></ul>
- </li>
-</ol>
-<p>
- 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 CONFIG_NXFONT_SANS23X27 for examaples:
-</p>
-<ol start="5">
- <li>
- <p>
- <b><code>nuttx/graphics/Makefile</code></b>.
- This file needs logic to auto-generate a C source file from the header file that you generated with the <i>bdf-converter</i> program.
- Notice <code>NXFONTS_FONTID=2</code>; this must be set to the same font ID value that you defined in the <code>include/nuttx/nx/nxfonts.h</code> file.
- </p>
- <ul><pre>
-genfontsources:
- ifeq ($(CONFIG_NXFONT_SANS23X27),y)
- @$(MAKE) -C nxfonts -f Makefile.sources TOPDIR=$(TOPDIR) NXFONTS_FONTID=1 EXTRAFLAGS=$(EXTRAFLAGS)
- endif
- ifeq ($(CONFIG_NXFONT_MYFONT),y)
- @$(MAKE) -C nxfonts -f Makefile.sources TOPDIR=$(TOPDIR) NXFONTS_FONTID=2 EXTRAFLAGS=$(EXTRAFLAGS)
- endif
-</pre></ul>
- </li>
- <li>
- <p>
- <b><code>nuttx/graphics/nxfonts/Make.defs</code></b>.
- Set the make variable <code>NXFSET_CSRCS</code>.
- <code>NXFSET_CSRCS</code> determines the name of the font C file to build when <code>NXFONTS_FONTID=2</code>:
- </p>
- <ul><pre>
-ifeq ($(CONFIG_NXFONT_SANS23X27),y)
-NXFSET_CSRCS += nxfonts_bitmaps_sans23x27.c
-endif
-ifeq ($(CONFIG_NXFONT_MYFONT),y)
-NXFSET_CSRCS += nxfonts_bitmaps_myfont.c
-endif
-</pre></ul>
- </li>
- <li>
- <p>
- <b><code>nuttx/graphics/nxfonts/Makefile.sources</code></b>.
- This is the Makefile used in step 5 that will actually generate the font C file.
- So, given your </code>NXFONTS_FONTID=2</code>, it needs to determine a prefix to use for auto-generated variable and function names and (again) the name of the autogenerated file to create (this must be the same name that was used in <code>nuttx/graphics/nxfonts/Make.defs</code>):
- </p>
- <ul><pre>
-ifeq ($(NXFONTS_FONTID),1)
-NXFONTS_PREFIX := g_sans23x27_
-GEN_CSRC = nxfonts_bitmaps_sans23x27.c
-endif
-ifeq ($(NXFONTS_FONTID),2)
-NXFONTS_PREFIX := g_myfont_
-GEN_CSRC = nxfonts_bitmaps_myfont.c
-endif
-</pre></ul>
- </li>
- <li>
- <p>
- <b><code>graphics/nxfonts/nxfonts_bitmaps.c</code></b>.
- This is the file that contains the generic font structures.
- It is used as a "template&qout; file by <code>nuttx/graphics/nxfonts/Makefile.sources </code>to create your customized font data set at build time.
- </p>
- <ul><pre>
-#if NXFONTS_FONTID == 1
-# include "nxfonts_sans23x27.h"
-#elif NXFONTS_FONTID == 2
-# include "nxfonts_myfont.h"
-#else
-# error "No font ID specified"
-#endif
-</pre></ul>
- <p>
- Where <code>nxfonts_myfont.h</code> is the NuttX font file that we generated in
- step 2 using the <i>bdf-converter</i> tool.
- </p>
- <li>
- <p>
- <b><code>graphics/nxfonts/nxfonts_getfont.c</code></b>.
- Finally, we need to extend the logic that does the run-time font lookups so that can find our new font.
- The lookup function is <a href="#nxfgetfonthandle"><code>NXHANDLE nxf_getfonthandle(enum nx_fontid_e fontid)</code></a>.
- Note that the lookup is based on the font ID that was defined in step 4.
- The new font information needs to be added to data structures used by that function:
- </p>
- <ul><pre>
-#ifdef CONFIG_NXFONT_SANS23X27
-extern const struct nx_fontpackage_s g_sans23x27_package;
-#endif
-#ifdef CONFIG_NXFONT_MYFONT
-extern const struct nx_fontpackage_s g_myfont_package;
-#endif
-
-static FAR const struct nx_fontpackage_s *g_fontpackages[] =
-{
-#ifdef CONFIG_NXFONT_SANS23X27
- &g_sans23x27_package,
-#endif
-#ifdef CONFIG_NXFONT_MYFONT
- &g_myfont_package,
-#endif
- NULL
-};
-</pre></ul>
- </li>
-</ol>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <h1>Appendix D <a name="testcoverage">NX Test Coverage</a></h1>
- </td>
- </tr>
-</table>
-
-<p><b><code>apps/examples/nx</code></b>.
- The primary test tool for debugging NX resides at <code>apps/examples/nx</code>.
-</p>
-<p><b>Building <code>apps/examples/nx</code></b>.
- NX testing was performed using <code>apps/examples/nx</code> with the
- Linux/Cygwin-based NuttX simulator.
- Configuration files for building this test can be found in <code>boards/sim/sim/sim/configs/nx</code>
- and <code>boards/sim/sim/sim/configs/nx11</code>.
- There are two alternative configurations for building the simulation:
-</p>
-<ol>
- <li>
- The configuration using the configuration file at <code>boards/sim/sim/sim/configs/nx/defconfig</code>.
- This default configuration exercises the NX logic a 8 BPP but provides no visual feedback.
- In this configuration, a very simple, simulated framebuffer driver is used that is
- based upon a simple region of memory posing as video memory.
- That default configuration can be built as follows:
-<ul><pre>
-tools/configure.sh sim:nx
-make
-./nuttx
-</pre></ul>
- </li>
- <li>
- <p>
- The preferred configuration is at <code>boards/sim/sim/sim/configs/nx11/defconfig</code>.
- This configuration extends the test with a simulated framebuffer driver
- that uses an X window as a framebuffer.
- This is a superior test configuration because the X window appears at your desktop
- and you can see the NX output.
- This preferred configuration can be built as follows:
- </p>
-<ul><pre>
-tools/configure sim:nx11
-make
-./nuttx
-</pre></ul>
- <p>
- <i>Update:</i>
- The sim target has suffered some bit-rot over the years and so the following caveats need to be added:
- <ul>
- <li><p>
- The X target builds under recent Cygwin configurations, but does not execute.
- (It fails inside of <code>XOpenDisplay()</code>.
- </p></li>
- <li><p>
- The X target does not build under current (9.09) Ubuntu distributions.
- I needed to make the following changes:
- </p>
- <ul></pre>
-cd /usr/lib/
-sudo ln -s libXext.so.6.4.0 libXext.so
-</pre></ul>
- <p>
- The build will also fail to locate the X header files unless you install an X11 development package.
- </p></li>
- <li><p>
- The sim target itself is broken under 64-bit Linux.
- This is because the sim target is based upon some assembly language setjmp/longjmp logic that only works on 32-bit systems.
- </p>
- <p><small>
- <b>NOTE</b>: There is a workaround in this case:
- You can build for 32-bit execution on a 64-bit machine by adding <code>-m3</code> to the <code>CFLAGS</code> and <code>-m32 -m elf_i386</code> to the <code>LDFLAGS</code>.
- The configuration/build system will do this for you;
- you simply need to select <code>CONFIG_SIM_M32=y</code> in your configuration file.
- </small></p>
- </li>
- <li><p>
- Refer to the readme file in sim configuration
- <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/sim/sim/sim/README.txt" target="_blank">README.txt</a> file for additional information.
- </p></li>
- </ul>
- </p>
- </li>
-</ol>
-
-<p><b>Test Coverage</b>.
- At present, <code>apps/examples/nx</code>t only exercises a subset of NX;
- the remainder is essentially untested.
- The following table describes the testing performed on each NX API:
-</p>
-
-<center><h2>Table D.1: <a name="nxglibcoverage">NXGLIB API Test Coverage</a></h2></center>
-<center><table border="1" width="80%">
-<tr>
- <th width="40%">Function</th>
- <th width="60%">Special Setup/Notes</th>
- <th width="5%">Verified</th></tr>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxglrgb2yuv"><code>nxgl_rgb2yuv()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="lightgrey">NO</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxglyuv2rgb"><code>nxgl_yuv2rgb()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="lightgrey">NO</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxglrectcopy"><code>nxgl_rectcopy()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxglrectoffset"><code>nxgl_rectoffset()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxglvectoradd"><code>nxgl_vectoradd()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxglvectorsubtract"><code>nxgl_vectorsubtract()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxglrectintersect"><code>nxgl_rectintersect()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxglrectunion"><code>nxgl_rectunion()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxglnonintersecting"><code>nxgl_nonintersecting()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxglrectoverlap"><code>nxgl_rectoverlap()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxglrectinside"><code>nxgl_rectinside()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxglrectsize"><code>nxgl_rectsize()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxglnullrect"><code>nxgl_nullrect()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxglrunoffset"><code>nxgl_runoffset()</code></a></td>
- <td>
- Verified by <code>apps/examples/nxlines</code>.
- </td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxglruncopy"><code>nxgl_runcopy()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="lightgrey">NO</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxgltrapoffset"><code>nxgl_trapoffset()</code></a></td>
- <td>
- Verified by <code>apps/examples/nxlines</code>.
- </td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxgltrapcopy"><code>nxgl_trapcopy()</code></a></td>
- <td>
- Verified by <code>apps/examples/nxlines</code>.
- </td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxglcolorcopy"><code>nxgl_colorcopy</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxglsplitline"><code>nxgl_splitline</code></a></td>
- <td bgcolor="lightgreen">
- Verified using <code>apps/examples/nxlines</code>.
- Generally works well, but has some accuracy/overflow problems wide lines
- that are nearly horizontal.
- There is a "fudge factor" that seems to eliminate the problem,
- but there could still be issues in some configurations.
- </td>
- <td align="center" bgcolor="lightgreen">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxglcirclepts"><code>nxgl_circlepts</code></a></td>
- <td>
- Verified by <code>apps/examples/nxlines</code>.
- </td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxglcircletraps"><code>nxgl_circletraps</code></a></td>
- <td>
- Verified by <code>apps/examples/nxlines</code>.
- </td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-</table></center>
-
-<center><h2>Table D.2: <a name="nxcbcoverage">NX Server Callbacks Test Coverage</a></h2></center>
-<center><table border="1" width="80%">
-<tr>
- <th width="40%">Function</th>
- <th width="60%">Special Setup/Notes</th>
- <th width="5%">Verified</th></tr>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxcbredraw"><code>redraw()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxcbposition"><code>position()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxcbmousein"><code>mousein()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxcbkbdin"><code>kbdin()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-</table></center>
-
-<center><h2>Table D.3: <a name="nxcoverage">NX API Test Coverage</a></h2></center>
-<center><table border="1" width="80%">
-<tr>
- <th width="40%">Function</th>
- <th width="60%">Special Setup/Notes</th>
- <th width="5%">Verified</th></tr>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxruninstance"><code>nx_runinstance()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxconnectinstance"><code>nx_connectinstance()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxdisconnect"><code>nx_disconnect()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxeventhandler"><code>nx_eventhandler()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxeventnotify"><code>nx_eventnotify()</code></a></td>
- <td>This is not used in the current version of <code>apps/examples/nx</code>,
- was tested in a previous version)</td>
- <td align="center" bgcolor="lightgrey">NO</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxopenwindow"><code>nx_openwindow()</code></a></td>
- <td>Change to <code>CONFIG_EXAMPLES_NX_RAWWINDOWS=y</code> in the
- <code><NuttX-Directory>/.config</code> file</td>
- </td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxclosewindow"><code>nx_closewindow()</code></a></td>
- <td>Change to <code>CONFIG_EXAMPLES_NX_RAWWINDOWS=y</code> in the
- <code><NuttX-Directory>/.config</code> file</td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a></td>
- <td>
- Verified by <code>apps/examples/nxtext</code> and <code>apps/examples/nxhello</code>.
- </td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxreleasebkgd"><code>nx_releasebkgd()</code></a></td>
- <td>
- Verified by <code>apps/examples/nxtext</code> and <code>apps/examples/nxhello</code>.
- </td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxgetposition"><code>nx_getposition()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="lightgrey">NO</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxsetposition"><code>nx_setposition()</code></a></td>
- <td>Change to <code>CONFIG_EXAMPLES_NX_RAWWINDOWS=y</code> in the
- <code><NuttX-Directory>/.config</code> file</td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxsetsize"><code>nx_setsize()</code></a></td>
- <td>Change to <code>CONFIG_EXAMPLES_NX_RAWWINDOWS=y</code> in the
- <code><NuttX-Directory>/.config</code> file</td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxraise"><code>nx_raise()</code></a></td>
- <td>Change to <code>CONFIG_EXAMPLES_NX_RAWWINDOWS=y</code> in the
- <code><NuttX-Directory>/.config</code> file</td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxlower"><code>nx_lower()</code></a></td>
- <td>Change to <code>CONFIG_EXAMPLES_NX_RAWWINDOWS=y</code> in the
- <code><NuttX-Directory>/.config</code> file</td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-
-<tr>
- <td align="left" valign="top"><a href="#nxmodal"><code>nx_modal()</code></a></td>
- <td> </td>
- <td align="center" bgcolor="lightgrey">NO</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxsetvisibility"><code>nx_setvisibility()</code></a></td>
- <td>Exercized using Twm4Nx</td>
- <td align="center" bgcolor="skyblue">YES, Informally</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxishidden"><code>nx_ishidden()</code></a></td>
- <td>Exercized using Twm4Nx</td>
- <td align="center" bgcolor="skyblue">YES, Informally</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxfill"><code>nx_fill()</code></a></td>
- <td>Change to <code>CONFIG_EXAMPLES_NX_RAWWINDOWS=y</code> in the
- <code><NuttX-Directory>/.config</code> file</td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxgetrectangle"><code>nx_getrectangle()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxfilltrapezoid"><code>nx_filltrapezoid()</code></a></td>
- <td>
- Verified by <code>apps/examples/nxlines</code>.
- </td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxdrawline"><code>nx_drawline()</code></a></td>
- <td>
- Verified by <code>apps/examples/nxlines</code>.
- </td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxdrawcircle"><code>nx_drawcircle()</code></a></td>
- <td>
- Verified by <code>apps/examples/nxlines</code>.
- </td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxfillcircle"><code>nx_fillcircle()</code></a></td>
- <td>
- Verified by <code>apps/examples/nxlines</code>.
- </td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxglrgb2yuv"><code>nx_setbgcolor()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxmove"><code>nx_move()</code></a></td>
- <td>Change to <code>CONFIG_EXAMPLES_NX_RAWWINDOWS=y</code> in the
- <code><NuttX-Directory>/.config</code> file</td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxbitmap"><code>nx_bitmap()</code></a></td>
- <td>Change to <code>CONFIG_EXAMPLES_NX_RAWWINDOWS=y</code> in the
- <code><NuttX-Directory>/.config</code> file.</td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxkbdin"><code>nx_kbdin()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxmousein"><code>nx_mousein()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-</table></center>
-
-
-<center><h2>Table D.4: <a name="nxtkcoverage">NXTK API Test Coverage</a></h2></center>
-<center><table border="1" width="80%">
-<tr>
- <th width="40%">Function</th>
- <th width="60%">Special Setup/Notes</th>
- <th width="5%">Verified</th></tr>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtkclosewindow"><code>nxtk_closewindow()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtkgetposition"><code>nxtk_getposition()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="lightgrey">NO</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtksetposition"><code>nxtk_setposition()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtksetsize"><code>nxtk_setsize()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtkraise"><code>nxtk_raise()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtklower"><code>nxtk_lower()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtkmodal"><code>nxtk_modal()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="lightgrey">NO</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtksetvisibility"><code>nxtk_setvisibility()</code></a></td>
- <td>Exercized using Twm4Nx</td>
- <td align="center" bgcolor="skyblue">YES, informally</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtkishidden"><code>nxtk_ishidden()</code></a></td>
- <td>Exercized using Twm4Nx</td>
- <td align="center" bgcolor="skyblue">YES, informally</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtkfillwindow"><code>nxtk_fillwindow()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtkgetwindow"><code>nxtk_getwindow()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="lightgrey">NO</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtkfilltrapwindow"><code>nxtk_filltrapwindow()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="lightgrey">NO</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtkdrawlinewindow"><code>nxtk_drawlinewindow()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtkdrawcirclewindow"><code>nxtk_drawcirclewindow()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtkfillcirclewindow"><code>nxtk_fillcirclewindow()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtkmovewindow"><code>nxtk_movewindow()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="lightgrey">NO</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtkbitmapwindow"><code>nxtk_bitmapwindow()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtkopentoolbar"><code>nxtk_opentoolbar()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtkclosetoolbar"><code>nxtk_closetoolbar()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtkfilltoolbar"><code>nxtk_filltoolbar()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtkgettoolbar"><code>nxtk_gettoolbar()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="lightgrey">NO</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtkfilltraptoolbar"><code>nxtk_filltraptoolbar()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="lightgrey">NO</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtkdrawlinetoolbar"><code>nxtk_drawlinetoolbar()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="lightgrey">NO</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtkdrawcircletoolbar"><code>nxtk_drawcircletoolbar()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="lightgrey">NO</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtkfillcircletoolbar"><code>nxtk_fillcircletoolbar()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="lightgrey">NO</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtkmovetoolbar"><code>nxtk_movetoolbar()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="lightgrey">NO</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxtkbitmaptoolbar"><code>nxtk_bitmaptoolbar()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="lightgrey">NO</td>
-</tr>
-</table></center>
-
-<center><h2>Table D.5: <a name="nxfontscoverage">NXFONTS API Test Coverage</a></h2></center>
-<center><table border="1" width="80%">
-<tr>
- <th width="40%">Function</th>
- <th width="60%">Special Setup/Notes</th>
- <th width="5%">Verified</th></tr>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxfgetfonthandle"><code>nxf_getfonthandle()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxfgetfontset"><code>nxf_getfontset()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxfgetbitmap"><code>nxf_getbitmap()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxfconvertbpp"><code>nxf_convert_2bpp()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="lightgrey">NO</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxfconvertbpp"><code>nxf_convert_4bpp()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="lightgrey">NO</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxfconvertbpp"><code>nxf_convert_8bpp()</code></a></td>
- <td>Use <code>defconfig</code> when building.</td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxfconvertbpp"><code>nxf_convert_16bpp()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxfconvertbpp"><code>nxf_convert_24bpp()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="lightgrey">NO</td>
-</tr>
-<tr>
- <td align="left" valign="top"><a href="#nxfconvertbpp"><code>nxf_convert_32bpp()</code></a></td>
- <td><br></td>
- <td align="center" bgcolor="skyblue">YES</td>
-</tr>
-</table></center>
-
-</body>
-</html>
diff --git a/Documentation/NfsHowto.html b/Documentation/NfsHowto.html
deleted file mode 100644
index 9de0ee6..0000000
--- a/Documentation/NfsHowto.html
+++ /dev/null
@@ -1,385 +0,0 @@
-<html>
-<head>
-<title>NFS Client How-To</title>
-</head>
-<body background="backgd.gif">
-<hr><hr>
-
-<table width ="100%">
- <tr align="center" bgcolor="#e4e4e4">
- <td>
- <h1><big><font color="#3c34ec"><i>NFS Client How-To</i></font></big></h1>
- <p>Last Updated: June 18, 2012</p>
- </td>
- </tr>
-</table>
-<hr><hr>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <h1>Table of Contents</h1>
- </td>
- </tr>
-</table>
-
-<center><table width ="80%">
-<tr>
-<td>
-<table>
-<tr>
- <td valign="top" width="22"><img height="20" width="20" src="favicon.ico"></td>
- <td>
- <a href="#nfsconfiguration">Adding NFS to the NuttX Configuration</a>
- </td>
-</tr>
-</table>
-<table>
-<tr>
- <td valign="top" width="22"><img height="20" width="20" src="favicon.ico"></td>
- <td>
- <a href="#mountinterface">Mount Interface</a>
- </td>
-</tr>
-</table>
-<table>
-<tr>
- <td valign="top" width="22"><img height="20" width="20" src="favicon.ico"></td>
- <td>
- <a href="#nfsmount">NFS Mount Command</a>
- </td>
-</tr>
-</table>
-<table>
-<tr>
- <td valign="top" width="22"><img height="20" width="20" src="favicon.ico"></td>
- <td>
- <a href="#serverconfig">Configuring the NFS server (Ubuntu)</a>
- </td>
-</tr>
-</table>
-</td>
-</tr>
-</table></center>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="nfsconfiguration"><h1>Adding NFS to the NuttX Configuration</h1></a>
- </td>
- </tr>
-</table>
-
-<p>
- The NFS client is easily added to your configuration:
- You simply need to add <code>CONFIG_NFS</code> to your <code>nuttx/.config</code> file.
- There are, however, a few dependencies on other system settings:
-</p>
-<ol>
- <li>
- First, there are things that you must configure in order to be able to use any file system:
- </li>
- <ul>
- <li>
- <code>CONFIG_DISABLE_MOUNTPOINT=n</code>. You must include support for mount points in the pseudo-file system.
- </li>
- </ul>
- <li>
- And there are several dependencies on the networking configuration.
- At a minimum, you need to have the following selections:
- </li>
- <ul>
- <li>
- <code>CONFIG_NET=y</code>. General networking support.
- </li>
- <li>
- <code>CONFIG_NET_UDP=y</code>. Support for UDP.
- </li>
- </ul>
-</ol>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="mountinterface"><h1>Mount Interface</h1></a>
- </td>
- </tr>
-</table>
-
-<p>
- A low-level, C-callable interface is provided to mount a file system.
- That interface is called <code>mount()</code> and is mentioned in the <a href="NuttxPortingGuide.html#NxFileSystem"><code>porting guide</code></a> and is prototyped in the header file <code>include/sys/mount.h</code>:
-</p>
-<ul><pre>
-int mount(const char *source, const char *target, const char *filesystemtype, unsigned long mountflags, const void *data);
-</pre></ul>
-<p>
- <b>Synopsis</b>:
- <code>mount()</code> attaches the filesystem specified by the <code>source</code> block device name into the root file system at the path specified by <code>target</code>.
-</p>
-<p>
- <b>Input Parameters</b>:
- <ul>
- <li><code>source</code>. A null-terminated string providing the fill path to a block driver in the NuttX pseudo-file system.
- <li><code>target</code>. The location in the NuttX pseudo-file system where the volume will be mounted.
- <li><code>filesystemtype</code>. A string identifying the type of file system to use.
- <li><code>mountflags</code>. Various flags that can be used to qualify how the file system is mounted.
- <li><code>data</code>. Opaque data that is passed to the file system with the mount occurs.
- </ul>
-</p>
-<p>
- <b>Returned Values</b>
- Zero is returned on success; -1 is returned on an error and <code>errno</code> is set appropriately:
- <ul>
- <li><code>EACCES</code>.
- A component of a path was not searchable or mounting a read-only filesystem was attempted without giving the <code>MS_RDONLY</code> flag.
- </li>
- <li><code>EBUSY</code>.
- <code>source</code> is already mounted.
- </li>
- <li><code>EFAULT</code>.
- One of the pointer arguments points outside the user address space.
- </li>
- <li><code>EINVAL</code>.
- <code>source</code> had an invalid superblock.
- </li>
- <li><code>ENODEV</code>.
- <code>filesystemtype</code> not configured
- </li>
- <li><code>ENOENT</code>.
- A pathname was empty or had a nonexistent component.
- </li>
- <li><code>ENOMEM</code>.
- Could not allocate a memory to copy filenames or data into.
- </li>
- <li><code>ENOTBLK</code>.
- <code>source</code> is not a block device
- </li>
- </ul>
-</p>
-<p>
- This same interface can be used to mount a remote, NFS file system using some special parameters.
- The NFS mount differs from the <i>normal</i> file system mount in that: (1) there is no block driver for the NFS file system, and (2) special parameters must be passed as <code>data</code> to describe the remote NFS server.
- Thus the following code snippet might represent how an NFS file system is mounted:
-</p>
-<ul><pre>
-#include <sys/mount.h>
-#include <nuttx/fs/nfs.h>
-
-struct nfs_args data;
-char *mountpoint;
-
-ret = mount(NULL, mountpoint, string "nfs", 0, (FAR void *)&data);
-</pre></ul>
-<p>
- NOTE that: (1) the block driver parameter is <code>NULL</code>.
- The <code>mount()</code> is smart enough to know that no block driver is needed with the NFS file system.
- (2) The NFS file system is identified with the simple string "nfs"
- (3) A reference to <code>struct nfs_args</code> is passed as an NFS-specific argument.
-</p>
-<p>
- The NFS-specific interface is described in the file <code>include/nuttx/fs/nfs.h</code>.
- There you can see that <code>struct nfs_args</code> is defined as:
-</p>
-<ul><pre>
-struct nfs_args
-{
- uint8_t addrlen; /* Length of address */
- uint8_t sotype; /* Socket type */
- uint8_t flags; /* Flags, determines if following are valid: */
- uint8_t timeo; /* Time value in deciseconds (with NFSMNT_TIMEO) */
- uint8_t retrans; /* Times to retry send (with NFSMNT_RETRANS) */
- uint16_t wsize; /* Write size in bytes (with NFSMNT_WSIZE) */
- uint16_t rsize; /* Read size in bytes (with NFSMNT_RSIZE) */
- uint16_t readdirsize; /* readdir size in bytes (with NFSMNT_READDIRSIZE) */
- char *path; /* Server's path of the directory being mount */
- struct sockaddr_storage addr; /* File server address (requires 32-bit alignment) */
-};
-</pre></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="nfsmount"><h1>NFS Mount Command</h1></a>
- </td>
- </tr>
-</table>
-
-<p>
- The <a href="NuttShell.html">NuttShell (NSH)</a> also supports a command called <code>nfsmount</code>
- that can be used to mount a remote file system via the NSH command line.
-</p>
-<p>
- <b>Command Syntax:</b>
-</p>
-<ul><pre>
-nfsmount <server-address> <mount-point> <remote-path>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- The <code>nfsmount</code> command mounts a network file system in the NuttX pseudo filesystem.
- The <code>nfsmount</code> will use NFSv3 UDP protocol to mount the remote file system.
-</p>
-<p>
- <b>Command Line Arguments</b>.
- The <code>nfsmount</code> takes three arguments:
-</p>
-<ol>
- <li>
- The <code><server-address></code> is the IP address of the server exporting the file system you wish to mount.
- This implementation of NFS for the NuttX RTOS is only for a local area network, so the server and client must be in the same network.
- </li>
- <li>
- The <code><mount-point ></code> is the location in the NuttX pseudo filesystem where the mounted volume will appear.
- This mount point can only reside in the NuttX pseudo filesystem.
- By convention, this mount point is a subdirectory under <code>/mnt</code>.
- The mount command will create whatever pseudo directories that may be needed to complete the full path (but the full path must not already exist).
- </li>
- <li>
- The <code><remote-path></code> is the file system <code>/</code> directory being exported from server.
- This <code>/</code> directory must have been configured for exportation on the server before when the NFS server was set up.
- </li>
-</ol>
-
-<p>
- After the volume has been mounted in the NuttX pseudo filesystem, it may be access in the same way as other objects in the file system.
-</p>
-<p>
- <b>Example</b>.
- Suppose that the NFS server has been configured to export the directory <code>/export/shared</code>.
- The the following command would mount that file system (assuming that the target also has privileges to mount the file system).
-</p>
-<ul><pre>
-NuttShell (NSH)
-nsh> ls /mnt
-/mnt:
-nsh: ls: no such directory: /mnt
-nsh> nfsmount 10.0.0.1 /mnt/nfs /export/shared
-nsh> ls -l /mnt/nfs
-/mnt/nfs:
- drwxrwxrwx 4096 ..
- drwxrwxrwx 4096 testdir/
- -rw-rw-rw- 6 ctest.txt
- -rw-r--r-- 15 btest.txt
- drwxrwxrwx 4096 .
-nsh> echo "This is a test" >/mnt/nfs/testdir/testfile.txt
-nsh> ls -l /mnt/nfs/testdir
-/mnt/nfs/testdir:
- -rw-rw-rw- 21 another.txt
- drwxrwxrwx 4096 ..
- drwxrwxrwx 4096 .
- -rw-rw-rw- 16 testfile.txt
-nsh> cat /mnt/nfs/testdir/testfile.txt
-This is a test
-</pre></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="serverconfig"><h1>Configuring the NFS server (Ubuntu)</h1></a>
- </td>
- </tr>
-</table>
-
-<p>
- Setting up the server will be done in two steps:
- First, setting up the configuration file for NFS, and then starting the NFS services.
- But first, you need to install the nfs server on Ubuntu with these two commands:
-</p>
-<ul><pre>
-# sudo apt-get install nfs-common</FONT>
-# sudo apt-get install nfs-kernel-server</FONT>
-</pre></ul>
-
-<p>
- After that, we need to make or choose the directory we want to export from the NFS server.
- In our case, we are going to make a new directory called <code>/export</code>.
-</p>
-<ul><pre>
-# sudo mkdir /export
-</pre></ul>
-<p>
- It is important that <code>/export</code> directory allow access to everyone (777 permissions) as we will be accessing the NFS share from the client with no authentication.
-</p>
-<ul><pre>
-# sudo chmod 777 /export
-</pre></ul>
-<p>
- When all this is done, we will need to edit the configuration file to set up an NFS server: <code>/etc/exports</code>.
- This file contains a list of entries;
- each entry indicates a volume that is shared and how it is shared.
- For more information for a complete description of all the setup options for this file you can check in the man pages (<code>man export</code>).</p>
- An entry in <code>/etc/exports</code> will typically look like this:
-</p>
-<ul><pre>
-directory machine1(option11,option12)
-</pre></ul>
-<p>
- So for our example we export <code>/export</code> to the client 10.0.0.2 add the entry:
-</p>
-<ul><pre>
-/export 10.0.0.2(rw)
-</pre></ul>
-<p>
- In our case we are using all the default options except for the <code>ro</code> that we replaced with <code>rw</code> so that our client will have read and write access to the directory that we are exporting.
-</p>
-</p>
- After we do all the require configurations, we are ready to start the server with the next command:
-</p>
-<ul><pre>
-# sudo /etc/init.d/nfs-kernel-server start
-</pre></ul>
-</p>
- Note: If you later decide to add more NFS exports to the /etc/exports file, you will need to either restart NFS daemon
-or run command exportfs.
-</p>
-<ul><pre>
-# sudo /etc/init.d/nfs-kernel-server start
-</pre></ul>
-<p>Or</p>
-<ul><pre>
-# exportfs -ra
-</pre></ul>
-<p>
- Now we can check if the export directory and our mount point is properly set up.
-</p>
-<ul><pre>
-# sudo showmount -e
-# sudo showmount -a
-</pre></ul>
-<p>
- And also we can verify if NFS is running in the system with:
-</p>
-<P STYLE="margin-left: 0.49in; margin-bottom: 0in; line-height: 100%">
-<ul><pre>
-# rpcinfo –p</FONT>
-program vers proto port
- 100000 2 tcp 111 portmapper
- 100000 2 udp 111 portmapper
- 100011 1 udp 749 rquotad
- 100011 2 udp 749 rquotad
- 100005 1 udp 759 mountd
- 100005 1 tcp 761 mountd
- 100005 2 udp 764 mountd
- 100005 2 tcp 766 mountd
- 100005 3 udp 769 mountd
- 100005 3 tcp 771 mountd
- 100003 2 udp 2049 nfs
- 100003 3 udp 2049 nfs
- 300019 1 tcp 830 amd
- 300019 1 udp 831 amd
- 100024 1 udp 944 status
- 100024 1 tcp 946 status
- 100021 1 udp 1042 nlockmgr
- 100021 3 udp 1042 nlockmgr
- 100021 4 udp 1042 nlockmgr
- 100021 1 tcp 1629 nlockmgr
- 100021 3 tcp 1629 nlockmgr
- 100021 4 tcp 1629 nlockmgr
-</pre></ul>
-<p>
- Now your NFS sever is sharing <code>/export</code> directory to be accessed.
-</p>
-
-</body>
-</html>
diff --git a/Documentation/NuttShell.html b/Documentation/NuttShell.html
deleted file mode 100644
index 11d53e2..0000000
--- a/Documentation/NuttShell.html
+++ /dev/null
@@ -1,6008 +0,0 @@
-<html>
-<head>
-<title>NuttShell</title>
-<link rel="stylesheet" href="style.css">
-</head>
-<body background="backgd.gif">
-<div class="container">
-<div class="toc">
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <h1>Table of Contents</h1>
- </td>
- </tr>
-</table>
-
-<table width ="80%" class="toc_table">
-<tr>
-<td>
-<table>
-<tr>
- <td valign="top" width="22"><img height="20" width="20" src="favicon.ico"></td>
- <td>
- <a href="#overview">1.0 Overview</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#frontend">1.1 Console/NSH Front End</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdoverview">1.2 Command Overview</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#conditional">1.3 Conditional Command Execution</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#looping">1.4 Looping</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#builtinvars">1.5 Built-In Variables</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#currentwd">1.6 Current Working Directory</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#environvars">1.7 Environment Variables</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#startupscript">1.8 NSH Start-Up Script</a>
- </td>
-</tr>
-
-<tr>
- <td valign="top" width="22"><img height="20" width="20" src="favicon.ico"></td>
- <td>
- <a href="#commands">2.0 Commands</a>.
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdtest">2.1 Evaluate Expression (test)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdaddroute">2.2 Add a Routing Table Entry (addroute)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdarp">2.3 Access the ARP table (arp)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdbase64dec">2.4 Base64 Decode (base64dec)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdbase64enc">2.5 Base64 Encode (base64enc)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdbasename">2.6 Extract Base File/Directory Name (basename)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdbreak">2.7 Terminate a Loop (break)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdcat">2.8 Concatenate Files (cat)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdcd">2.9 Change Current Working Directory (cd)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdcmp">2.10 Compare Files (cmp)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdcp">2.11 Copy Files (cp)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmddate">2.12 Show or set the date and time (date)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmddd">2.13 Copy and Convert Files (dd)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmddelroute">2.14 Delete a Routing Table Entry (delroute)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmddf">2.15 Show volume status (df)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmddirname">2.16 Extract Path to a File/Directory (dirname)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmddmesg">2.17 Dump Buffered SYSLOG Output (dmesg)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdecho">2.18 Echo Strings and Variables (echo)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdenv">2.19 Show Environment Variables (env)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdexec">2.20 Execute User Code (exec)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdexit">2.21 Exit NSH (exit)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdexport">2.22 Set an Environment Variable (export)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdfree">2.23 Show Memory Manager Status (free)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdget">2.24 Get File Via TFTP (get)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdhelp">2.25 Show Usage Command Usage (help)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdhexdump">2.26 Hexadecimal Dump of File or Device (hexdump)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdifconfig">2.27 Manage Network Configuration (ifconfig)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdifdown">2.28 Take a network down (ifdown)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdifup">2.29 Bring a network up (ifup)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdinsmod">2.30 Install an OS module (insmod)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdirqinfo">2.31 Show Interrupt Status (irqinfo)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdkill">2.32 Send a signal to a task (kill)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdlosetup">2.33 Setup/teardown the Loop Device (losetup)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdln">2.34 List to a File or Directory (ln)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdls">2.35 List Directory Contents (ls)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdlsmod">2.36 Show information about installed OS modules (lsmod)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdmd5">2.37 Calculate MD5 (md5)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdmbhw">2.38 Access Memory (mb, mh, and mw)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdps">2.39 Show Current Tasks and Threads (ps)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdmkdir">2.40 Create a Directory (mkdir)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdmkfatfs">2.41 Create a FAT File System (mkfatfs)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdmkfifo">2.42 Create a FIFO (mkfifo)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdmkrd">2.43 Create a RAMDISK (mkrd)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdmount">2.44 Mount a File System (mount)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdmv">2.45 Rename a File (mv)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdnfsmount">2.46 Mount an NFS File System (nfsmount)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdnslookup">2.47 Lookup a network address (nslookup)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdpasswd">2.48 Change a User's Password (passwd)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdpmconfig">2.49 Manage Power Management Subsystem (pmconfig)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdpoweroff">2.50 Shut the system down (poweroff)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdput">2.51 Send File Via TFTP (put)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdpwd">2.52 Show Current Working Directory (pwd)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdreadlink">2.53 Show target of a link (readlink)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdreboot">2.54 Reset and reboot the system (reboot)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdrm">2.55 Remove a File (rm)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdrmdir">2.56 Remove a Directory (rmdir)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdrmmod">2.57 Remove on OS Module (rmmod)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdroute">2.58 Show routing table (route)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdrptun">2.59 Start/Stop the OpenAMP RPC Tunnel (rptun)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdset">2.60 Set a Variable (set)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdsh">2.61 Execute an NSH Script (sh)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdshutdown">2.62 Shut the system down (shutdown)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdsleep">2.63 Wait for Seconds (sleep)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdtelnetd">2.64 Start the Telnet Daemon (telnetd)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdtime">2.65 Time execution of another command (time)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdtruncate">2.66 Set the Size of a File (truncate)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdunmount">2.67 Unmount a File System (umount)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmduname">2.68 Print system information (uname)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdunset">2.69 Unset an Environment Variable (unset)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdurldec">2.70 URL Decode (urldecode)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdurlencode">2.71 URL Encode (urlencode)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmduseradd">2.72 Add a New User (useradd)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmduserdel">2.73 Delete a user (userdel)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdusleep">2.74 Wait for Microseconds (usleep)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdwget">2.75 Get File Via HTTP (wget)</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmdxd">2.76 Hexadecimal Dump of Memory (xd)</a>
- </td>
-</tr>
-<tr>
- <td valign="top" width="22"><img height="20" width="20" src="favicon.ico"></td>
- <td>
- <a href="#builtincmds">3.0 Built-In Commands</a>
-</td>
-
-<tr>
- <td><br></td>
- <td>
- <a href="#builtinping">3.1 Check Network Peer (ping/pin6)</a>
- </td>
-</tr>
-
-<tr>
- <td valign="top" width="22"><img height="20" width="20" src="favicon.ico"></td>
- <td>
- <a href="#configuration">4.0 Configuration Settings</a>
-</td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#cmddependencies">4.1 Command Dependencies on Configuration Settings</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#builtinconfig">4.2 Built-In Command Dependencies on Configuration Settings</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#nshconfiguration">4.3 NSH-Specific Configuration Settings</a>
- </td>
-</tr>
-<tr>
- <td valign="top" width="22"><img height="20" width="20" src="favicon.ico"></td>
- <td>
- <a href="#customizingnsh">5.0 Customizing the NuttShell</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#custonshlib">5.1 The NSH Library and NSH Initialization</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#custoncmds">5.2 NSH Commands</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#custapps">5.3 NSH "Built-In" Applications</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#custinit">5.4 Customizing NSH Initialization</a>
- </td>
-</tr>
-<tr>
- <td valign="top" width="22"><img height="20" width="20" src="favicon.ico"></td>
- <td>
- <a href="#nshlogin">6.0 Shell Login</a>
-</td>
-<tr>
- <td><br></td>
- <td>
- <a href="#enablelogin">6.1 Enabling Shell Logins</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#verifymethods">6.2 Verification of Credentials</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#passwdfiles">6.3 Password Files</a>
- </td>
-</tr>
-<tr>
- <td><br></td>
- <td>
- <a href="#passwdromfs">6.4 Creating a Password File for a ROMFS File System</a>
- </td>
-</tr>
-<tr>
- <td valign="top" width="22"><img height="20" width="20" src="favicon.ico"></td>
- <td>
- <a href="#index">Index</a>
- </td>
-</tr>
-</table></table>
-</div>
-
-<div class="main">
-<hr><hr>
-<table width ="100%">
- <tr align="center" bgcolor="#e4e4e4">
- <td>
- <h1><big><font color="#3c34ec"><i>NuttShell (NSH)</i></font></big></h1>
- <p>Last Updated: March 21, 2020</p>
- </td>
- </tr>
-</table>
-<hr><hr>
-
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="overview"><h1>1.0 Overview</h1></a>
- </td>
- </tr>
-</table>
-
-<p>
- <a name="nshlibrary"><b>The NSH Library</b></a>.
- The <code>apps/nshlib</code> sub-directory contains the NuttShell (NSH)
- library.
- This library can easily to linked to produce a NSH application (See as an example <code>apps/examples/nsh</code>).
- The NSH Library provides a simple shell application for NuttX.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="frontend"><h2>1.1 Console/NSH Front End</h2></a>
- </td>
- </tr>
-</table>
-
-<p>
- <a name="nshconsoles"><b>NSH Consoles</b></a>.
- Using settings in the configuration file, NSH may be configured to use
- (1) the serial stdin/out,
- (2) a USB serial device (such as CDC/ACM), or
- (3) a telnet connection as the console.
- Or, perhaps even all at once since or BOTH.
- An indefinite number of telnet sessions are supported.
-</p>
-<p>
- <a name="nshprompt"><b>Start-Up prompt</b></a>.
- When NSH is started, you will see the a welcome message such the following on the selected console:
- <ul><pre>
-NuttShell (NSH)
-nsh>
-</pre></ul>
- The greeting may also include NuttX versioning information if you are using a versioned copy of NuttX.
- <code>nsh></code> is the NSH prompt and indicates that you may enter a command from the console.
-</p>
-<p>
- <a name="usbstartup"><b>USB console startup</b></a>.
- When using a USB console, the start-up sequence differs a little: In this case, you are required to press <i>ENTER</i> three times. Then NSH prompt will appear as described above.
- This is required for the following reasons:
-</p>
-<ol>
- <li>
- This assures that the USB connection is stable.
- The USB connection may be made, broken, and re-established a few times if the USB cable is not yet fully seated.
- Waiting for <i>ENTER</i> to be pressed three times assures that the connection is stable.
- </li>
- <li>
- The establishment of the connection is two step process: First, the USB serial connection is made with the host PC. Then the application that uses the serial interface is started on the host.
- When the serial connection is established on the host, the host operating system may send several <i>AT</i> modem commands to the host depending upon how the host serial port is configured.
- By waiting for <i>ENTER</i> to be pressed three consecutive times, all of these modem commands will go to the bit-bucket and will not be interpreted as NSH command input.
- </li>
- <li>
- Similarly, in the second step when the applications is started, there may be additional <i>AT</i> modem commands sent out the serial port.
- Most serial terminal programs will do this unless they are specifically configured to suppress the modem command output.
- Waiting for the <i>ENTER</i> input eliminates the invalid command errors from both (2) and (3).
- </li>
- <li>
- Finally, if NSH did not wait for some positive indication that the serial terminal program is up and running, then the output of the NSH greeting and initial NSH prompt would be lost.
- </li>
-</ol>
-
-<p>
- <a name="cle"><b>Extended Command Line Editing</b></a>.
- By default, NuttX uses a simple command line editor that allows command entry after the <code>nsh></code> and supports only the <i>backspace</i> key for editing.
- However, a more complete command line editor can be selected by setting <code>CONFIG_NSH_CLE=y</code> in the NuttX configuration file.
- When that option is selected, the following EMACS-like line editing commands are supported:
-</p>
-<center><table width="60%" border="5" bgcolor="f8f8f8" bordercolor="lightgray">
-<tr>
- <td align="center" bgcolor="#e4e4e4">
- <b>Key Binding</b>
- </td>
- <td align="center" bgcolor="#e4e4e4">
- <b>Editor Action</b>
- </td>
-</tr>
-<tr>
- <td align="left" valign="top">
- <code>^A</code>
- </td>
- <td align="left" valign="top">
- Move cursor to start of the line
- </td>
-</tr>
-<tr>
- <td align="left" valign="top">
- <code>^B</code>
- </td>
- <td align="left" valign="top">
- Move left one character
- </td>
-</tr>
-<tr>
- <td align="left" valign="top">
- <code>^D</code> or <i>Del</i>
- </td>
- <td align="left" valign="top">
- Delete a single character at the cursor position
- </td>
-</tr>
-<tr>
- <td align="left" valign="top">
- <code>^E</code>
- </td>
- <td align="left" valign="top">
- Move cursor to end of current line
- </td>
-</tr>
-<tr>
- <td align="left" valign="top">
- <code>^F</code>
- </td>
- <td align="left" valign="top">
- Move right one character
- </td>
-</tr>
-<tr>
- <td align="left" valign="top">
- <code>^H</code> or <i>Backspace</i>
- </td>
- <td align="left" valign="top">
- Delete character, left (backspace)
- </td>
-</tr>
-<tr>
- <td align="left" valign="top">
- <code>^K</code>
- </td>
- <td align="left" valign="top">
- Delete to the end of the line
- </td>
-</tr>
-<tr>
- <td align="left" valign="top">
- <code>^U</code>
- </td>
- <td align="left" valign="top">
- Delete the entire line
- </td>
-</tr>
-</table></center>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdoverview"><h2>1.2 Command Overview</h2></a>
- </td>
- </tr>
-</table>
-
-<p>
- <b>Simple, Re-directed, and Background Commands</b>.
- The NuttShell (NSH) is a simple shell application.
- NSH supports the following commands forms:
-</p>
-<ul><table>
- <tr>
- <td>Simple command:</td>
- <td><code><cmd></code></td>
- </tr>
- <tr>
- <td>Command with re-directed output:</td>
- <td><code>
- <cmd> > <file><br>
- <cmd> >> <file>
- </code></td>
- </tr>
- <tr>
- <td>Background command:</td>
- <td><code><cmd> &</code></td>
- </tr>
- <tr>
- <td>Re-directed background command:</td>
- <td><code>
- <cmd> > <file> &<br>
- <cmd> >> <file> &
- </code></td>
- </tr>
-</table></ul>
-<p>Where:</p>
-<ul><table>
- <tr>
- <td><code><cmd></code></td>
- <td>
- is any one of the simple commands listed later.
- </td>
- </tr>
- <tr>
- <td><code><file></code></td>
- <td>
- 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.
- </td>
- </tr>
-</table></ul>
-<p>
- <b><big><code>nice</code></big>'d Background Commands</b>
- NSH executes at the mid-priority (128). Backgrounded commands can
- be made to execute at higher or lower priorities using <code>nice</code>:
-</p>
-<ul><code>
- [nice [-d <niceness>>]] <cmd> [> <file>|>> <file>] [&]
-</code></ul>
-<p>
- Where <code><niceness></code> is any value between -20 and 19 where lower
- (more negative values) correspond to higher priorities.
- The default niceness is 10.
-</p>
-
-<p>
- <b>Multiple commands per line</b>.
- NSH will accept multiple commands per command line with each command separated with the semi-colon character (;).
-</p>
-
-<p>
- <b>Optional Syntax Extensions</b>
- Because these features commit significant resources, they are disabled by default.
-</p>
-<ul>
-<li>
- <p>
- <b><code>CONFIG_NSH_CMDPARMS</code></b>.
- If selected, then the output from commands, from file applications, and from NSH built-in commands can be used as arguments to other commands.
- The entity to be executed is identified by enclosing the command line in back quotes.
- For example,
- </p>
- <ul><pre>
-set FOO `myprogram $BAR`
-</pre></ul>
- <p>
- Will execute the program named <code>myprogram</code> passing it the value of the environment variable <code>BAR</code>.
- The value of the environment variable <code>FOO</code> is then set output of <code>myprogram</code> on <code>stdout</code>.
- </p>
-</li>
-<li>
- <p>
- <b><code>CONFIG_NSH_ARGCAT</code></b>.
- Support concatenation of strings with environment variables or command output. For example:
- </p>
- <ul><pre>
-set FOO XYZ
-set BAR 123
-set FOOBAR ABC_${FOO}_${BAR}
-</pre></ul>
- <p>
- would set the environment variable <code>FOO</code> to <code>XYZ</code>, <code>BAR</code> to <code>123</code> and <code>FOOBAR</code> to <code>ABC_XYZ_123</code>.
- If <code>CONFIG_NSH_ARGCAT</code> is not selected, then a slightly smaller FLASH footprint results but then also only simple environment variables like <code>$FOO</code> can be used on the command line.
- </p>
-</li>
-<li>
- <p>
- <b><code>CONFIG_NSH_QUOTE</code></b>.
- Enables back-slash quoting of certain characters within the command.
- This option is useful for the case where an NSH script is used to dynamically generate a new NSH script.
- In that case, commands must be treated as simple text strings without interpretation of any special characters.
- Special characters such as <code>$</code>, <code>`</code>, <code>"</code>, and others must be retained intact as part of the test string.
- This option is currently only available is <code>CONFIG_NSH_ARGCAT</code> is also selected.
- </p>
-</li>
-</ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="conditional"><h2>1.3 Conditional Command Execution</h2></a>
- </td>
- </tr>
-</table>
-
-<p>
- An <code>if-then[-else]-fi</code> construct is also supported in order to
- support conditional execution of commands. This works from the
- command line but is primarily intended for use within NSH scripts
- (see the <a href="#cmdsh"><code>sh</code></a> command). The syntax is as follows:
-</p>
-<ul><pre>
-if [!] <cmd>
-then
- [sequence of <cmd>]
-else
- [sequence of <cmd>]
-fi
-</pre></ul>
-
-<p>
- Where <code><cmd></code> is a <a href="#cmdoverview">simple command</a>.
- The command success value of zero is treated true; a non-zero command failure value is treated false.
- The <a href="#cmdtest"><code>test</code></a> command is frequently used for comparisons.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="looping"><h2>1.4 Looping</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Looping Constructs</b>.
- <code>while-do-done</code> and <code>until-do-done</code> looping constructs are also supported.
- These work from the command line but are primarily intended for use within NSH scripts
- (see the <a href="#cmdsh"><code>sh</code></a> command).
-</p>
-<ul>
- <li>
- <p><b><code>while-do-done</code></b>.
- Execute <code>[sequence of <cmd>]</code> as long as <code><cmd></code> has an exit status of zero.
- The syntax is as follows:
- <ul><pre>
-while <cmd>
-do
- [sequence of <cmd>]
-done
-</pre></ul>
- </p>
- </li>
- <li>
- <p><b><code>until-do-done</code></b>
- Execute <code>[sequence of <cmd>]</code> as long as <code><cmd></code> has a non-zero exit status.
- The syntax is as follows:
- <ul><pre>
-until <cmd>
-do
- [sequence of <cmd>]
-done
-</pre></ul>
- </p>
- </li>
-</ul>
-
-<p>
- Where <code><cmd></code> is a <a href="#cmdoverview">simple command</a>.
- The command success value of zero is treated true; a non-zero command failure value is treated false.
- The <a href="#cmdtest"><code>test</code></a> command is frequently used for comparisons.
-</p>
-
-<p><b>The <a href="#cmdbreak"><code>break</code></a> Command</b>.
- A <a href="#cmdbreak"><code>break</code></a> command is also supported.
- The <code>break</code> command is only meaningful within the body of the a while or until loop, between the <code>do</code> and <code>done</code> tokens.
- If the <code>break</code> command is executed within the body of a loop, the loop will immediately terminate and execution will continue with the next command immediately following the <code>done</code> token.
-<p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="builtinvars"><h2>1.5 Built-In Variables</h2></a>
- </td>
- </tr>
-</table>
-
-<ul><table>
- <tr>
- <td valign="top"><b><code>$?</code></b></td>
- <td>
- The result of the last simple command execution.
- On backgrounded commands, this variable holds only the result of spawning the background command.
- </td>
- </tr>
-</table></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="currentwd"><h2>1.6 Current Working Directory</h2></a>
- </td>
- </tr>
-</table>
-
-<p>
- <b><code>cd</code> and <code>pwd</code></b>.
- All path arguments to commands may be either an absolute path or a
- path relative to the current working directory. The current working
- directory is set using the <a href="#cmdcd"><code>cd</code></a> command and can be queried either
- by using the <a href="#cmdpwd"><code>pwd</code></a> command or by
- using the <a href="#cmdecho"><code>echo</code></a> <a href="#environvars"><code>$PWD</code></a>
- command.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="environvars"><h2>1.7 Environment Variables</h2></a>
- </td>
- </tr>
-</table>
-
-<p>
- <b>Environment Variables:</b>
-</p>
-<ul><table>
- <tr>
- <td><b><code>PATH</code></b></td><td>The default path in the file systems to look for executable, binary programs working directory</td>
- </tr>
- <tr>
- <td><b><code>PWD</code></b></td><td>The current working directory</td>
- </tr>
- <tr>
- <td><b><code>OLDPWD</code></b></td><td>The previous working directory</td>
- </tr>
-</table></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="startupscript"><h2>1.8 NSH Start-Up Script</h2></a>
- </td>
- </tr>
-</table>
-
-<p>
- <b>NSH Start-Up Script</b>.
- NSH supports options to provide a start up script for NSH. In general
- this capability is enabled with <code>CONFIG_NSH_ROMFSETC</code>, but has
- several other related configuration options as described with the
- <a href="#nshconfiguration">NSH-specific configuration settings</a>.
- This capability also depends on:
- <ul>
- <li><code>CONFIG_DISABLE_MOUNTPOINT</code> not set
- <li><code>CONFIG_NFILE_DESCRIPTORS</code> > 4
- <li><code>CONFIG_FS_ROMFS</code> enabled
- </ul>
-</p>
-
-<p>
- <b>Default Start-Up Behavior</b>.
- The implementation that is provided is intended to provide great flexibility
- for the use of Start-Up files. This paragraph will discuss the general
- behavior when all of the configuration options are set to the default
- values.
-</p>
-<p>
- In this default case, enabling <code>CONFIG_NSH_ROMFSETC</code> will cause
- NSH to behave as follows at NSH startup time:
- <ul>
- <li>
- NSH will create a read-only RAM disk (a ROM disk), containing a tiny
- ROMFS file system containing the following:
-<ul><pre>
-`--init.d/
- `-- rcS
-</pre></ul>
- Where rcS is the NSH start-up script.
- </li>
- <li>
- NSH will then mount the ROMFS file system at <code>/etc</code>, resulting in:
-<ul><pre>
-|--dev/
-| `-- ram0
-`--etc/
- `--init.d/
- `-- rcS
-</pre></ul>
- </li>
- <li>
- By default, the contents of rcS script are:
-<ul><pre>
-# Create a RAMDISK and mount it at XXXRDMOUNTPOINTXXX
-
-mkrd -m 1 -s 512 1024
-mkfatfs /dev/ram1
-mount -t vfat /dev/ram1 /tmp
-</pre></ul>
- </li>
- <li>
- NSH will execute the script at <code>/etc/init.d/rcS</code> at start-up (before the
- first NSH prompt). After execution of the script, the root FS will look
- like:
-<ul><pre>
-|--dev/
-| |-- ram0
-| `-- ram1
-|--etc/
-| `--init.d/
-| `-- rcS
-`--tmp/
-</pre></ul>
- </li>
- </ul>
-</p>
-<p>
- <b>Modifying the ROMFS Image</b>.
- The contents of the <code>/etc</code> directory are retained in the file <code>apps/nshlib/nsh_romfsimg.h</code> OR, if <code>CONFIG_NSH_ARCHROMFS</code> is defined, <code>include/arch/board/rcs.template</code>).
- In order to modify the start-up behavior, there are three things to study:
- <ol>
- <li>
- <b>Configuration Options.</b>
- The additional <code>CONFIG_NSH_ROMFSETC</code> configuration options
- discussed with the other <a href="#nshconfiguration">NSH-specific configuration settings</a>.
- </li>
- <li>
- <p>
- <b><code>tools/mkromfsimg.sh</code> Script</b>.
- The script <code>tools/mkromfsimg.sh</code> creates <code>nsh_romfsimg.h</code>.
- It is not automatically executed. If you want to change the
- configuration settings associated with creating and mounting
- the <code>/tmp</code> directory, then it will be necessary to re-generate
- this header file using the <code>tools/mkromfsimg.sh</code> script.
- </p>
- <p>
- The behavior of this script depends upon three things:
- <ul>
- <li>The configuration settings then installed configuration.
- <li>The <code>genromfs</code> tool (available from <a href="http://romfs.sourceforge.net">http://romfs.sourceforge.net</a>).
- <li>The file <code>apps/nshlib/rcS.template</code>
- (OR, if <code>CONFIG_NSH_ARCHROMFS</code> is defined <code>include/arch/board/rcs.template</code>.
- </ul>
- </p>
- </li>
- <li>
- <b><code>rcS.template</code></b>.
- The file <code>apps/nshlib/rcS.template</code> contains the general form
- of the <code>rcS</code> file; configured values are plugged into this
- template file to produce the final <code>rcS</code> file.
- </li>
- </ol>
-</p>
-<p>
- <b>NOTE</b>:
- <code>apps/nshlib/rcS.template</code> generates the standard, default <code>nsh_romfsimg.h</code> file.
- If <code>CONFIG_NSH_ARCHROMFS</code> is defined in the NuttX configuration file, then a custom, board-specific <code>nsh_romfsimg.h</code> file residing in the <code>boards/<arch>/<chip>/<board>/include</code> directory will be used.
- NOTE when the OS is configured, <code>include/arch/board</code> will be linked to <code>boards/<arch>/<chip>/<board>/include</code>.
-</p>
-<p>
- All of the startup-behavior is contained in <code>rcS.template</code>. The
- role of <code>mkromfsimg.sh</code> is to (1) apply the specific configuration
- settings to <code>rcS.template</code> to create the final <code>rcS</code>, and (2) to
- generate the header file <code>nsh_romfsimg.h</code> containing the ROMFS
- file system image.
-</p>
-
-<p>
- <b>Further Information</b>.
- See the section on <a href="#customizingnsh">Customizing the NuttShell</a> for additional, more detailed information about the NSH start-up script and how to modify it.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="commands"><h1>2.0 Commands</h1></a>
- </td>
- </tr>
-</table>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdtest"><h2>2.1 Evaluate Expression (test)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-[ <expression> ]
-test <expression>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- These are two alternative forms of the same command. They support
- evaluation of a boolean expression which sets <a href="#builtinvars"><code>$?</code></a>.
- This command is used most frequently as the conditional command following the
- <code>if</code> in the <a href="#conditional"><code>if-then[-else]-fi</code></a> construct.
-</p>
-<p><b>Expression Syntax:</b></p>
-<ul>
- <p>
- expression = simple-expression | !expression | expression -o expression | expression -a expression
- </p>
- <p>
- simple-expression = unary-expression | binary-expression
- </p>
- <p>
- unary-expression = string-unary | file-unary
- </p>
- <p>
- string-unary = -n string | -z string
- </p>
- <p>
- file-unary = -b file | -c file | -d file | -e file | -f file | -r file | -s file | -w file
- </p>
- <p>
- binary-expression = string-binary | numeric-binary
- </p>
- <p>
- string-binary = string = string | string == string | string != string
- </p>
- <p>
- numeric-binary = integer -eq integer | integer -ge integer | integer -gt integer | integer -le integer |
- integer -lt integer | integer -ne integer
- </p>
-</ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdaddroute"><h2>2.2 Add a Routing Table Entry (addroute)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-addroute <target> [<netmask>] <router>
-addroute default <ipaddr> <interface>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- This command adds an entry in the routing table.
- The new entry will map the IP address of a router on a local network (<router>) to an external network characterized by the <target> IP address and a network mask <netmask>
-</p>
-<p>
- The netmask may also be expressed using IPv4 CIDR or IPv6 slash notation.
- In that case, the netmask need not be provided.
-</p>
-<p>
- <b>Example:</b>
-</p>
-<ul><pre>
-nsh> addroute addroute 11.0.0.0 255.255.255.0 10.0.0.2
-</pre></ul>
-<p>
- which is equivalent to
-</p>
-<ul><pre>
-nsh> addroute 11.0.0.0/24 10.0.0.2
-</pre></ul>
-<p>
- The second form of the addroute command can be used to set the default gateway.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdarp"><h2>2.3 Access the ARP table (arp)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-arp [-t|-a <ipaddr> |-d <ipaddr> |-s <ipaddr> <hwaddr>]
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Access the OS ARP table.
-</p>
-<ul><dl>
- <dt>-a <ipaddr>
- <dd>Will show the hardware address that the IP address <ipaddr> is mapped to.
-
- <dt>-d <ipaddr>
- <dd>Will delete the mapping for the IP address <ipaddr> from the ARP table.
-
- <dt>-s <ipaddr> <hwaddr>
- <dd>Will set (or replace) the mapping of the IP address <ipaddr> to the hardware address <hwaddr>.
-
- <dt>-t
- <dd>Will dump the entire content of the ARP table. This option is only available if <code>CONFIG_NETLINK_ROUTE</code> is enabled.
-</dl></ul>
-<p>
- <b>Example:</b>
-</p>
-<ul><pre>
-nsh> arp -a 10.0.0.1
-nsh: arp: no such ARP entry: 10.0.0.1
-
-nsh> arp -s 10.0.0.1 00:13:3b:12:73:e6
-nsh> arp -a 10.0.0.1
-HWAddr: 00:13:3b:12:73:e6
-
-nsh> arp -d 10.0.0.1
-nsh> arp -a 10.0.0.1
-nsh: arp: no such ARP entry: 10.0.0.1
-</pre></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdbase64dec"><h2>2.4 Base64 Decode (base64dec)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-base64dec [-w] [-f] <string or filepath>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- <i>To be provided.</i>
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdbase64enc"><h2>2.5 Base64 Encode (base64enc)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-base64enc [-w] [-f] <string or filepath>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- <i>To be provided.</i>
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdbasename"><h2>2.6 Extract Base File/Directory Name (basename)</h2></a>
- </td>
- </tr>
-</table>
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-basename <path> [<suffix>]
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Extract the final string from a <code><path></code> by removing the preceding path
- segments and (optionally) removing any trailing <code><suffix></code>.
-<p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdbreak"><h2>2.7 Terminate a Loop (break)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-break
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- The <code>break</code> command is only meaningful within the body of the a <a href="#looping">while</a> or <a href="#looping">until</a> loop, between the <code>do</code> and <code>done</code> tokens.
- Outside of a loop, <code>break</code> command does nothing.
- If the <code>break</code> command is executed within the body of a loop, the loop will immediately terminate and execution will continue with the next command immediately following the <code>done</code> token.
-<p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdcat"><h2>2.8 Concatenate Files (cat)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-cat <code><path></code> [<code><path></code> [<code><path></code> ...]]
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- This command copies and concatenates all of the files at <code><path></code>
- to the console (or to another file if the output is redirected).
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdcd"><h2>2.9 Change Current Working Directory (cd)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-cd [<dir-path>|-|~|..]
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Changes the current working directory (<code>PWD</code>). Also sets the
- previous working directory environment variable (<code>OLDPWD</code>).
-<p>
-<p><b>Forms:</b></p>
-<ul><table>
- <tr>
- <td><b><code>cd <dir-path></code></b></td>
- <td>sets the current working directory to <code><dir-path></code>.</td>
- </tr>
- <tr>
- <td><b><code>cd -</code></b></td>
- <td>sets the current working directory to the previous
- working directory ($<a href="#environvars"><code>OLDPWD</code></a>).
- Equivalent to <code><a href="#cmdcd">cd</a> $<a href="#environvars">OLDPWD</a></code>.</td>
- </tr>
- <tr>
- <td><b><code>cd</code> or <b><code>cd ~</code></b></td>
- <td>set the current working directory to the 'home'
- directory. The <i>home</i> directory can be configured by setting
- <code>CONFIG_LIB_HOMEDIR</code> in the configuration file. The default
- <i>home</i> directory is <code>/</code>.</td>
- </tr>
- <tr>
- <td><b><code>cd ..</code></td>
- <td>sets the current working directory to the parent directory.</td>
- </tr>
-</table></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdcmp"><h2>2.10 Compare Files (cmp)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-cmp <path1> <path2>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Compare of the contents of the file at <code><path1></code> with the contents of the file at <code><path2></code>. Returns an indication only if the files differ.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdcp"><h2>2.11 Copy Files (cp)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-cp <source-path> <dest-path>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Copy of the contents of the file at <code><source-path></code> to the location
- in the file system indicated by <code><dest-path></code>.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmddate"><h2>2.12 Show or set the date and time (date)</h2></a>
- </td>
- </tr>
-</table>
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-date [-s "MMM DD HH:MM:SS YYYY"]
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Show or set the current date and time.
-</p>
-<p>
- Only one format is used both on display and when setting the date/time:
- <code>MMM DD HH:MM:SS YYYY</code>. For example,
-<ul><pre>
-date -s "Sep 1 11:30:00 2011"
-</pre></ul>
-</p>
-<p>
- 24-hour time is used.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmddd"><h2>2.13 Copy and Convert Files (dd)</h2></a>
- </td>
- </tr>
-</table>
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-dd if=<infile> of=<outfile> [bs=<sectsize>] [count=<sectors>] [skip=<sectors>]
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Copy blocks from <infile> to <outfile>.
- <infile> or <outfile> may be the path to a standard file, a character device, or a block device.
- Examples follow:
-</p>
-<ol>
- <li>
- Read from character device, write to regular file.
- This will create a new file of the specified size filled with zero.
-<ul><pre>
-nsh> ls -l /dev
-/dev:
- crw-rw-rw- 0 zero
-nsh> dd if=/dev/zero of=/tmp/zeros bs=64 count=16
-nsh> ls -l /tmp
-/tmp:
- -rw-rw-rw- 1024 ZEROS
-</pre></ul>
- </li>
- <li>
- Read from character device, write to block device.
- This will fill the entire block device with zeros.
- </li>
-<ul><pre>
-nsh> ls -l /dev
-/dev:
- brw-rw-rw- 0 ram0
- crw-rw-rw- 0 zero
-nsh> dd if=/dev/zero of=/dev/ram0
-</pre></ul>
- </li>
- <li>
- Read from a block device, write to a character device. This
- will read the entire block device and dump the contents in
- the bit bucket.
- </li>
-<ul><pre>
-nsh> ls -l /dev
-/dev:
- crw-rw-rw- 0 null
- brw-rw-rw- 0 ram0
-nsh> dd if=/dev/ram0 of=/dev/null
-</pre></ul>
- </li>
-</ol>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmddelroute"><h2>2.14 Delete a Routing Table Entry (delroute)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-delroute <target> [<netmask>]
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- The entry removed will be the first entry in the routing table that matches
- the external network characterized by the <target> IP address and the network mask <netmask>
-</p>
-<p>
- The netmask may also be expressed using IPv4 CIDR or IPv6 slash
- notation. In that case, the netmask need not be provided.
-</p>
-<p>
- <b>Example:</b>
-</p>
-<ul><pre>
-nsh> delroute 11.0.0.0 255.255.255.0
-</pre></ul>
-<p>
- which is equivalent to
-</p>
-<ul><pre>
-nsh> delroute 11.0.0.0/24
-</pre></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmddf"><h2>2.15 Show Volume Status (df)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-df [-h]
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Show the state of each mounted volume.
- As an example:
-</p>
-<ul><pre>
-nsh> mount
- /etc type romfs
- /tmp type vfat
-nsh> df
- Block Number
- Size Blocks Used Available Mounted on
- 64 6 6 0 /etc
- 512 985 2 983 /tmp
-nsh>
-</pre></ul>
-<p>
- If <code>CONFIG_NSH_CMDOPT_DF_H</code> is defined in the NuttX configuration, then the <code>df</code> will also support an option <code>-h</code> which may be used to show the volume information in <i>human readable</i> format.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmddirname"><h2>2.16 Extract Path to a File/Directory (dirname)</h2></a>
- </td>
- </tr>
-</table>
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-dirname <path>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Extract the path string leading up to the full <code><path></code> by removing
- the final directory or file name.
-<p>
-
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmddmesg"><h2>2.17 Dump Buffered SYSLOG Output (dmesg)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-dmesg
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- This command can be used to dump (and clear) the content of any buffered syslog output messages.
- This command is only available if <code>CONFIG_RAMLOG_SYSLOG</code> is enabled.
- In that case, syslog output will be collected in an in-memory, circular buffer.
- Entering the <code>dmesg</code> command will dump the content of that in-memory, circular buffer to the NSH console output.
- <code>dmesg</code> has the side effect of clearing the buffered data so that entering <code>dmesg</code> again will show only newly buffered data.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdecho"><h2>2.18 Echo Strings and Variables (echo)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-echo [-n] [<string|$name> [<string|$name>...]]
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Copy the sequence of strings and expanded environment variables to
- console output (or to a file if the output is re-directed).
-</p>
-<p>
- The <code>-n</code> option suppresses the trailing newline character.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdenv"><h2>2.19 Show Environment Variables (env)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-env
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Show the current name-value pairs in the environment. Example:.
-</p>
-<ul><pre>
-nsh> env
-PATH=/bin
-
-nsh> set foo bar
-nsh> env
-PATH=/bin
-foo=bar
-
-nsh> unset PATH
-nsh> env
-foo=bar
-
-nsh>
-</pre></ul>
-<p>
- <b>NOTE:</b> NSH local variables are <i>not</i> shown by the <code>env</code> command.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdexec"><h2>2.20 Execute User Code (exec)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-exec <hex-address>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Execute the user logic at address <code><hex-address></code>. NSH will pause
- until the execution unless the user logic is executed in background
- via <code><a href="#cmdexec">exec</a> <hex-address> &</code>.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdexit"><h2>2.21 Exit NSH (exit)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-exit
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Exit NSH. Only useful for the serial front end if you have started some other tasks (perhaps
- using the <code><a href="#cmdexec">exec</a></code> command) and you would like to have NSH out of the
- way. For the telnet front-end, <code>exit</code> terminates the telnet session.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdexport"><h2>2.22 Set an Environment Variable (export)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-export <name> [<value>]
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- The <code>export</code> command sets an environment variable, or promotes an NSH variable to an environment variable. As examples:
-</p>
-<ol>
- <li>
- <p>
- Using <code>export</code> to promote an NSH variable to an environment variable.
- </p>
- <ul><pre>
-nsh> env
-PATH=/bin
-
-nsh> set foo bar
-nsh> env
-PATH=/bin
-
-nsh> export foo
-nsh> env
-PATH=/bin
-foo=bar
-</pre></ul>
- <p>
- A group-wide environment variable is created with the same value as the local NSH variable; the local NSH variable is removed.
- </p>
- <blockquote><small>
- <b>NOTE:</b> This behavior differs from the <i>Bash</i> shell.
- <i>Bash</i> would retain the local Bash variable which will shadow the environment variable of the same name and same value.
- </small></blockquote>
- </li>
- <li>
- <p>
- Using <code>export</code> to set an environment variable
- </p>
- <ul><pre>
-nsh> export dog poop
-nsh> env
-PATH=/bin
-foo=bar
-dog=poop
-</pre></ul>
- </li>
-</ol>
-<p>
- The <code>export</code> command is not supported by NSH unless both <code>CONFIG_NSH_VARS=y</code> and <code>CONFIG_DISABLE_ENVIRON</code>is not set.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdfree"><h2>2.23 Show Memory Manager Status (free)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-free
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Show the current state of the memory allocator. For example,
-</p>
-<ul><pre>
-nsh> free
- total used free largest
-Mem: 4194288 1591552 2602736 2601584
-nsh>
-</pre></ul>
-<p><b>Where:</b></p>
-<ul><table>
- <tr>
- <td><b><code>total</code></b></td>
- <td>This is the total size of memory allocated for use by malloc in bytes.</td>
- </tr>
- <tr>
- <td><b><code>used</code></b></td>
- <td>This is the total size of memory occupied by chunks handed out by malloc.</td>
- </tr>
- <tr>
- <td><b><code>free</code></b></td>
- <td>This is the total size of memory occupied by free (not in use) chunks.</td>
- </tr>
- <tr>
- <td><b><code>largest</code></b></td>
- <td>Size of the largest free (not in use) chunk.</td>
- </tr>
-</table></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdget"><h2>2.24 Get File Via TFTP (get)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-get [-b|-n] [-f <local-path>] -h <ip-address> <remote-path>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Copy the file at <code><remote-address></code> from the host whose IP address is
- identified by <code><ip-address></code>.
-</p>
-<p><b>Other options:</b></p>
-<ul><table>
- <tr>
- <td><b><code>-f <local-path></code></b></td>
- <td>
- The file will be saved relative to the current working directory
- unless <code><local-path></code> is provided.
- </td>
- </tr>
- <tr>
- <td><b><code>-b|-n</code></b></td>
- <td>
- Selects either binary ("octet") or text ("netascii") transfer
- mode. Default: text.
- </td>
- </tr>
-</table></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdhelp"><h2>2.25 Show Usage Command Usage (help)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-help [-v] [<cmd>]
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Presents summary information about NSH commands to console.
-</p>
-<p><b>Options:</b></p>
-<ul><table>
- <tr>
- <td><b><code>-v</code></b></td>
- <td>
- how verbose output will full command usage.
- </td>
- </tr>
- <tr>
- <td><b><code><cmd></code></b></td>
- <td>
- Show full command usage only for this command.
- </td>
- </tr>
-</table></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdhexdump"><h2>2.26 Hexadecimal Dump of File or Device (hexdump)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-hexdump <file or device> [skip=<bytes>] [count=<bytes>]
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Dump data in hexadecimal format from a file or character device.
-</p>
-<ul><table>
- <tr>
- <td><b><code>skip=<bytes></code></b></td>
- <td>Will skip <code><bytes></code> number of bytes from the beginning.
- </tr>
- <tr>
- <td><b><code>count=<bytes></code></b></td>
- <td>Will stop after dumping <code><bytes></code> number of bytes.
- </tr>
-</table></ul>
-<p>
-The <code>skip</code> and <code>count</code> options are only available if <code>CONFIG_NSH_CMDOPT_HEXDUMP</code> is defined in the NuttX configuration.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdifconfig"><h2>2.27 Manage Network Configuration (ifconfig)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-ifconfig [nic_name [<ip-address>|dhcp]] [dr|gw|gateway <dr-address>] [netmask <net-mask>] [dns <dns-address>] [hw <hw-mac>]]
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Multiple forms of the <code>ifconfig</code> command are supported:
-</p>
-<ol>
- <li>
- <p>
- With one or no arguments, <code>ifconfig</code> will shows the
- current configuration of the network and, perhaps, the status of Ethernet
- device:
- </p>
- <ul><pre>
-ifconfig
-ifconfig [nic_name]
-</pre></ul>
- <p>
- As an example:
- </p>
- <ul><pre>
-nsh> ifconfig
-eth0 HWaddr 00:18:11:80:10:06
- IPaddr:10.0.0.2 DRaddr:10.0.0.1 Mask:255.255.255.0
-</pre></ul>
- <p>
- If network statistics are enabled (<code>CONFIG_NET_STATISTICS</code>), then
- this command will also show the detailed state of network.
- </p>
- </li>
- <li>
- <p>
- If both the network interface name and an IP address are supplied as arguments,
- then <code>ifconfig</code> will set the address of the Ethernet device:
- </p>
- <ul><pre>
-ifconfig nic_name ip_address
-</pre></ul>
- </li>
- <li>
- Other forms <i>to be provided</i>
- </li>
-</ol>
-<p>
-NOTE: This commands depends upon having the <i>procfs</i> file system configured into the system.
-The <i>procfs</i> file system must also have been mounted with a command like:
-</p>
-<ul><pre>
-nsh> mount -t procfs /proc
-</pre></ul>
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdifdown"><h2>2.28 Take a network down (ifdown)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-ifdown <interface>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Take down the interface identified by the name <interface>.
-</p>
-<p>
- <b>Example:</b>
-</p>
-<ul><pre>
-ifdown eth0
-</pre></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdifup"><h2>2.29 Bring a network up (ifup)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-ifup <interface>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Bring up down the interface identified by the name <interface>.
-</p>
-<p>
- <b>Example:</b>
-</p>
-<ul><pre>
-ifup eth0
-</pre></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdinsmod"><h2>2.30 Install an OS module (insmod)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-insmod <file-path> <module-name>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Install the loadable OS module at <file-path> as module <module-name>.
-</p>
-<p><b>Example:</b></p>
-<ul><pre>
-nsh> ls -l /mnt/romfs
-/mnt/romfs:
- dr-xr-xr-x 0 .
- -r-xr-xr-x 9153 chardev
-nsh> ls -l /dev
-/dev:
- crw-rw-rw- 0 console
- crw-rw-rw- 0 null
- brw-rw-rw- 0 ram0
- crw-rw-rw- 0 ttyS0
-nsh> lsmod
-NAME INIT UNINIT ARG TEXT SIZE DATA SIZE
-nsh> insmod /mnt/romfs/chardev mydriver
-nsh> ls -l /dev
-/dev:
- crw-rw-rw- 0 chardev
- crw-rw-rw- 0 console
- crw-rw-rw- 0 null
- brw-rw-rw- 0 ram0
- crw-rw-rw- 0 ttyS0
-nsh> lsmod
-NAME INIT UNINIT ARG TEXT SIZE DATA SIZE
-mydriver 20404659 20404625 0 20404580 552 204047a8 0
-</pre></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdirqinfo"><h2>2.31 Show Interrupt Status (irqinfo)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-irqinfo
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Show the current count of interrupts taken on all attached interrupts.
-</p>
-<p>
- <b>Example:</b>.
-</p>
-<ul><pre>
-nsh> irqinfo
-IRQ HANDLER ARGUMENT COUNT RATE
- 3 00001b3d 00000000 156 19.122
- 15 0000800d 00000000 817 100.000
- 30 00000fd5 20000018 20 2.490
-</pre></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdkill"><h2>2.32 Send a signal to a task (kill)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-kill -<signal> <pid>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Send the <signal> to the task identified by <pid>.
-</p>
-<p><b>Example:</b></p>
-<ul><pre>
-nsh> mkfifo /dev/fifo
-nsh> cat /dev/fifo &
-cat [2:128]
-nsh> ps
-PID PRI POLICY TYPE NPX STATE EVENT SIGMASK COMMAND
- 0 0 FIFO Kthread --- Ready 00000000 Idle Task
- 1 128 RR Task --- Running 00000000 init
- 2 128 FIFO pthread --- Waiting Semaphore 00000000 <pthread>(51ea50)
-nsh> kill -9 2
-nsh> ps
-PID PRI POLICY TYPE NPX STATE EVENT SIGMASK COMMAND
- 0 0 FIFO Kthread --- Ready 00000000 Idle Task
- 1 128 RR Task --- Running 00000000 init
-nsh>
-</pre></ul>
-<p><small>
- <b>NOTE</b>:
- NuttX does not support a FULL POSIX signaling system.
- A few standard signal names like <code>SIGCHLD</code>, <code>SIGUSR1</code>, <code>SIGUSR2</code>, <code>SIGALRM</code>, and <code>SIGPOLL</code> exist in the system.
- However, they do not have the default actions that you might expect.
- Rather, NuttX supports only what are referred to as POSIX real-time signals.
- These signals may be used to communicate with running tasks, may be use to waiting waiting tasks, etc.
-</p>
-<p>
- If the configuration option <code>CONFIG_SIG_DEFAULT</code> is enabled, then default actions for the <code>SIGINT</code> and <code>SIGKILL</code> signals (only) will be supported.
- In that case, as an example, <code>kill -9</code> (SIGKILL) will, indeed, terminate a task.
- Caution should be exercised, however, because this is likely to cause memory leaks and to strand resource since there is insufficient clean-up in certain build configurations.
-</p></small>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdlosetup"><h2>2.33 Setup/teardown the Loop Device (losetup)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax 1:</b></p>
-<ul><pre>
-losetup [-o <offset>] [-r] <dev-path> <file-path>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Setup the loop device at <dev-path> to access the file at <file-path> as a block device.
- In the following example a 256K file is created (<code>dd</code>) and <code>losetup</code> is
- used to make the file accessible as a block device.
- A FAT file system is created (<code>mkfatfs</code>) and mounted (<code>mount</code>).
- Files can then be managed on the loop-mounted file.
-<ul><pre>
-nsh> dd if=/dev/zero of=/tmp/image bs=512 count=512
-nsh> ls -l /tmp
-/tmp:
- -rw-rw-rw- 262144 IMAGE
-nsh> losetup /dev/loop0 /tmp/image
-nsh> ls -l /dev
-/dev:
- brw-rw-rw- 0 loop0
-nsh> mkfatfs /dev/loop0
-nsh> mount -t vfat /dev/loop0 /mnt/example
-nsh> ls -l /mnt
-ls -l /mnt
-/mnt:
- drw-rw-rw- 0 example/
-nsh> echo "This is a test" >/mnt/example/atest.txt
-nsh> ls -l /mnt/example
-/mnt/example:
- -rw-rw-rw- 16 ATEST.TXT
-nsh> cat /mnt/example/atest.txt
-This is a test
-nsh>
-</pre></ul>
-</p>
-
-<p><b>Command Syntax 2:</b></p>
-<ul><pre>
-losetup d <dev-path>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Teardown the setup for the loop device at <dev-path>.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdln"><h2>2.34 Link to a File or Directory (ln)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-ln [-s] <target> <link>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- The <code>ln</code> command will create a new symbolic link at <link> for the existing file or directory, <target>.
- This implementation is simplified for use with NuttX in these ways:
-</p>
-<ul>
- <li>Links may be created only within the NuttX top-level, <a href="NuttxUserGuide.html#FileSystemOverview"><i>pseudo</i> file system</a>.
- No file system currently supported by NuttX provides symbolic links.</li>
- <li>For the same reason, only soft links are implemented.</li>
- <li>File privileges are ignored.</li>
- <li><code>c_time</code> is not updated.</li>
-</ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdls"><h2>2.35 List Directory Contents (ls)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-ls [-lRs] <dir-path>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Show the contents of the directory at <code><dir-path></code>. NOTE:
- <code><dir-path></code> must refer to a directory and no other file system
- object.
-</p>
-<p><b>Options:</b></p>
-<ul><table>
- <tr>
- <td><b><code>-R</code></b></td>
- <td>Show the contents of specified directory and all of its
- sub-directories.</td>
- </tr>
- <tr>
- <td><b><code>-s</code></b></td>
- <td>Show the size of the files along with the filenames in the
- listing</td>
- </tr>
- <tr>
- <td><b><code>-l</code></b></td>
- <td>Show size and mode information along with the filenames
- in the listing.</td>
- </tr>
-</table></ul>
-
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdlsmod"><h2>2.36 Show information about installed OS modules (lsmod)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-lsmod
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Show information about the currently installed OS modules. This information includes:
-</p>
-<ul>
- <li>The module name assigned to the module when it was installed (<code>NAME</code>, string).</li>
- <li>The address of the module initialization function (<code>INIT</code>, hexadecimal).</li>
- <li>The address of the module un-initialization function (<code>UNINIT</code>, hexadecimal).</li>
- <li>An argument that will be passed to the module un-initialization function (<code>ARG</code>, hexadecimal).</li>
- <li>The start of the .text memory region (<code>TEXT</code>, hexadecimal).</li>
- <li>The size of the .text memory region size (<code>SIZE</code>, decimal).</li>
- <li>The start of the .bss/.data memory region (<code>DATA</code>, hexadecimal).</li>
- <li>The size of the .bss/.data memory region size (<code>SIZE</code>, decimal).</li>
-</ul>
-<p><b>Example:</b></p>
-<ul><pre>
-nsh> lsmod
-NAME INIT UNINIT ARG TEXT SIZE DATA SIZE
-mydriver 20404659 20404625 0 20404580 552 204047a8 0
-</pre></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdmd5"><h2>2.37 Calculate MD5 (md5)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-md5 [-f] <string or filepath>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- <i>To be provided.</i>
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdmbhw"><h2>2.38 Access Memory (mb, mh, and mw)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-mb <hex-address>[=<hex-value>][ <hex-byte-count>]
-mh <hex-address>[=<hex-value>][ <hex-byte-count>]
-mw <hex-address>[=<hex-value>][ <hex-byte-count>]
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Access memory using byte size access (mb), 16-bit accesses (mh),
- or 32-bit access (mw). In each case,
-</p>
-<ul><table>
- <tr>
- <td><code><hex-address></code></td>
- <td>Specifies the address to be accessed. The current
- value at that address will always be read and displayed.
- </tr>
- <tr>
- <td><code><hex-address>=<hex-value></code></td>
- <td>Read the value, then write <code><hex-value></code>
- to the location.
- </tr>
- <tr>
- <td><code><hex-byte-count></code></td>
- <td>Perform the mb, mh, or mw operation on a total
- of <code><hex-byte-count></code> bytes, increment the <code><hex-address></code> appropriately after each access.
- </tr>
-</table></ul>
-<p><b>Example:</b><p>
-<ul><pre>
-nsh> mh 0 16
- 0 = 0x0c1e
- 2 = 0x0100
- 4 = 0x0c1e
- 6 = 0x0110
- 8 = 0x0c1e
- a = 0x0120
- c = 0x0c1e
- e = 0x0130
- 10 = 0x0c1e
- 12 = 0x0140
- 14 = 0x0c1e
-nsh>
-</pre></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdps"><h2>2.39 Show Current Tasks and Threads (ps)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-ps
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Show the currently active threads and tasks. For example,
-</p>
-<ul><pre>
-nsh> ps
-PID PRI POLICY TYPE NPX STATE EVENT SIGMASK COMMAND
- 0 0 FIFO Kthread --- Ready 00000000 Idle Task
- 1 128 RR Task --- Running 00000000 init
- 2 128 FIFO Task --- Waiting Semaphore 00000000 nsh_telnetmain()
- 3 100 RR pthread --- Waiting Semaphore 00000000 <pthread>(21)
-nsh>
-</pre></ul>
-<p>
-NOTE: This commands depends upon having the <i>procfs</i> file system configured into the system.
-The <i>procfs</i> file system must also have been mounted with a command like:
-</p>
-<ul><pre>
-nsh> mount -t procfs /proc
-</pre></ul>
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdmkdir"><h2>2.40 Create a Directory (mkdir)</h2></a>
- </td>
-</tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-mkdir <path>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Create the directory at <code><path></code>.
- All components of <code><path></code> except the final directory name must exist on a mounted file
- system; the final directory must not.
-</p>
-<p>
- <b>Limited to Mounted File Systems</b>.
- Recall that NuttX uses a <a href="NuttxUserGuide.html#FileSystemOverview"><i>pseudo</i> file system</a> for its root file
- system.
- The <code>mkdir</code> command can only be used to create directories in volumes set up with the
- <a href="#cmdmount"><code>mount</code></a> command; it cannot be used to create directories in the <i>pseudo</i> file system.
-</p>
-<p><b>Example:</b></p>
-<ul><pre>
-nsh> mkdir /mnt/fs/tmp
-nsh> ls -l /mnt/fs
-/mnt/fs:
- drw-rw-rw- 0 TESTDIR/
- drw-rw-rw- 0 TMP/
-nsh>
-</pre></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdmkfatfs"><h2>2.41 Create a FAT File System (mkfatfs)</h2></a>
- </td>
-</tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-mkfatfs [-F <fatsize>] [-r <rootdirentries>] <block-driver>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Format a fat file system on the block device specified by <code><block-driver></code> path.
- The FAT size may be provided as an option.
- Without the <code><fatsize></code> option, <code>mkfatfs</code> will select either the FAT12 or FAT16 format.
- For historical reasons, if you want the FAT32 format, it must be explicitly specified on the command line.
-</p>
-<p>
- The <code>-r</code> option may be specified to select the the number of entries in the root directory for FAT12 and FAT16 file systems.
- Typical values for small volumes would be 112 or 224; 512 should be used for large volumes, such as hard disks or very large SD cards. The default is 512 entries in all cases.
-</p>
-<p>
- The reported number of root directory entries used with FAT32 is zero because the FAT32 root directory is a cluster chain.
-</p>
-<p>
- NSH provides this command to access the <a href="mkfatfs"><code>mkfatfs()</code></a> NuttX API.
- This block device must reside in the NuttX <a href="NuttxUserGuide.html#FileSystemOverview"><i>pseudo</i> file system</a> and
- must have been created by some call to <code>register_blockdriver()</code> (see <code>include/nuttx/fs/fs.h</code>).
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdmkfifo"><h2>2.42 Create a FIFO (mkfifo)</h2></a>
- </td>
-</tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-mkfifo <path>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Creates a FIFO character device anywhere in the pseudo file system, creating
- whatever pseudo directories that may be needed to complete the <code><path></code>.
- By convention, however, device drivers are place in the standard <code>/dev</code> directory.
- After it is created, the FIFO device may be used as any other device driver.
- NSH provides this command to access the <a href="NuttxUserGuide.html#mkfifo"><code>mkfifo()</code></a> NuttX API.
-</p>
-<p><b>Example</b></p>
-<ul><pre>
-nsh> ls -l /dev
-/dev:
- crw-rw-rw- 0 console
- crw-rw-rw- 0 null
- brw-rw-rw- 0 ram0
-nsh> mkfifo /dev/fifo
-nsh> ls -l /dev
-ls -l /dev
-/dev:
- crw-rw-rw- 0 console
- crw-rw-rw- 0 fifo
- crw-rw-rw- 0 null
- brw-rw-rw- 0 ram0
-nsh>
-</pre></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdmkrd"><h2>2.43 Create a RAMDISK (mkrd)</h2></a>
- </td>
-</tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-mkrd [-m <minor>] [-s <sector-size>] <nsectors>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Create a ramdisk consisting of <code><nsectors></code>, each of size
- <code><sector-size></code> (or 512 bytes if <code><sector-size></code> is not specified.
- The ramdisk will be registered as <code>/dev/ram<minor></code>. If <code><minor></code> is not
- specified, <code>mkrd</code> will attempt to register the ramdisk as <code>/dev/ram0</code>.
-</p>
-<p><b>Example</b></p>
-<ul><pre>
-nsh> ls /dev
-/dev:
- console
- null
- ttyS0
- ttyS1
-nsh> mkrd 1024
-nsh> ls /dev
-/dev:
- console
- null
- ram0
- ttyS0
- ttyS1
-nsh>
-</pre></ul>
-<p>
- Once the ramdisk has been created, it may be formatted using
- the <code>mkfatfs</code> command and mounted using the <code>mount</code> command.
-</p>
-<p><b>Example</b></p>
-<ul><pre>
-nsh> mkrd 1024
-nsh> mkfatfs /dev/ram0
-nsh> mount -t vfat /dev/ram0 /tmp
-nsh> ls /tmp
-/tmp:
-nsh>
-</pre></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdmount"><h2>2.44 Mount a File System (mount)</h2></a>
- </td>
-</tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-mount -t <fstype> [-o <options>] <block-device> <code><dir-path></code>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- The <code>mount</code> command performs one of two different operations.
- If no parameters are provided on the command line after the <code>mount</code> command, then the <code>mount</code> command will enumerate all of the current mountpoints on the console.
-</p>
-<p>
- If the mount parameters are provided on the command after the <code>mount</code> command, then the <code>mount</code> command will mount a file system in the NuttX pseudo-file system.
- <code>mount</code> performs a three way association, binding:
-</p>
-<ol>
- <li><b>File System.</b>
- The '-t <code><fstype></code>' option identifies the type of
- file system that has been formatted on the <code><block-device></code>.
- As of this writing, <code>vfat</code> is the only supported value for <code><fstype></code>
- </li>
- <li><b>Block Device.</b>
- The <code><block-device></code> argument is the full or relative
- path to a block driver inode in the <a href="NuttxUserGuide.html#FileSystemOverview"><i>pseudo</i> file system</a>.
- By convention, this is a name under the <code>/dev</code> sub-directory.
- This <code><block-device></code> must have been previously formatted with the same file system
- type as specified by <code><fstype></code>
- </li>
- <li><b>Mount Point.</b>
- The mount point, <code><dir-path></code>, is the location in the
- <a href="NuttxUserGuide.html#FileSystemOverview"><i>pseudo</i> file system</a> where the mounted volume will appear.
- This mount point can only reside in the NuttX <a href="NuttxUserGuide.html#FileSystemOverview"><i>pseudo</i> file system</a>.
- By convention, this mount point is a subdirectory under <code>/mnt</code>.
- The mount command will create whatever pseudo directories that may be needed to complete the
- full path but the full path must not already exist.
- </li>
-</ol>
-<p>
- After the volume has been mounted in the NuttX
- <a href="NuttxUserGuide.html#FileSystemOverview"><i>pseudo</i> file system</a>,
- it may be access in the same way as other objects in the file system.
-</p>
-<p><b>Examples</b>:</p>
-<p>Using <code>mount</code> to mount a file system:</p>
-<ul><pre>
-nsh> ls -l /dev
-/dev:
- crw-rw-rw- 0 console
- crw-rw-rw- 0 null
- brw-rw-rw- 0 ram0
-nsh> ls /mnt
-nsh: ls: no such directory: /mnt
-nsh> mount -t vfat /dev/ram0 /mnt/fs
-nsh> ls -l /mnt/fs/testdir
-/mnt/fs/testdir:
- -rw-rw-rw- 15 TESTFILE.TXT
-nsh> echo "This is a test" >/mnt/fs/testdir/example.txt
-nsh> ls -l /mnt/fs/testdir
-/mnt/fs/testdir:
--rw-rw-rw- 15 TESTFILE.TXT
- -rw-rw-rw- 16 EXAMPLE.TXT
-nsh> cat /mnt/fs/testdir/example.txt
-This is a test
-nsh>
-</pre></ul>
-<p>Using <code>mount</code> to enumerate mounts:</p>
-<ul><pre>
-nsh> mount
- /etc type romfs
- /mnt/fs type vfat
- /tmp type vfat
-</pre></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdmv"><h2>2.45 Rename a File (mv)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-mv <old-path> <new-path>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Rename the file object at <code><old-path></code> to <code><new-path></code>.
- Both paths must reside in the same mounted file system.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdnfsmount"><h2>2.46 Mount an NFS file system (nfsmount)</h2></a>
- </td>
- </tr>
-</table>
- <a href="#"></a>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-nfsmount <server-address> <mount-point> <remote-path>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Mount the remote NFS server directory<remote-path> at <mount-point> on the target machine.
- <server-address> is the IP address of the remote server.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdnslookup"><h2>2.47 Lookup a network address (nslookup)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-nslookup <host-name>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Lookup and print the IP address associated with <code><host-name></code>.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdpasswd"><h2>2.48 Change a User's Password (passwd)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-passwd <username> <password>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Set the password for the existing user <username> to <password>.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdpmconfig"><h2>2.49 Manage Power Management Subsystem (pmconfig)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-pmconfig [stay|relax] [normal|idle|standby|sleep]
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Control power management subsystem.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdpoweroff"><h2>2.50 Shut the system down (poweroff)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-poweroff [<n>]
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Shutdown and power off the system immediately.
- This command depends on board-specific hardware support to power down the system.
- The optional,decimal numeric argument <n> may be included to provide power off
- mode to board-specific power off logic.
-</p>
-<p>
- NOTE: Supporting both the <code>poweroff</code> and <code>shutdown</code> commands is redundant.
-</p>
-
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdput"><h2>2.51 Send File Via TFTP (put)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-put [-b|-n] [-f <remote-path>] -h <ip-address> <local-path>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Copy the file at <code><local-address></code> to the host whose IP address is
- identified by <code><ip-address></code>.
-</p>
-<p><b>Other options:</b></p>
-<ul><table>
- <tr>
- <td><b><code>-f <remote-path></code></b></td>
- <td>
- The file will be saved relative with the same name on the host
- unless <code><remote-path></code> is provided.
- </td>
- </tr>
- <tr>
- <td><b><code>-b|-n</code></b></td>
- <td>
- Selects either binary ("octet") or text ("netascii") transfer
- mode. Default: text.
- </td>
- </tr>
-</table></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdpwd"><h2>2.52 Show Current Working Directory (pwd)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-pwd
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Show the current working directory.
-</p>
-<ul><pre>
-nsh> cd /dev
-nsh> pwd
-/dev
-nsh>
-</pre></ul>
-
-<p>Same as <code><a href="#cmdecho">echo</a> <a href="#environvars">$PWD</a></code>.</p>
-<ul><pre>
-nsh> echo $PWD
-/dev
-nsh>
-</pre></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdreadlink"><h2>2.53 Show target of a link (readlink)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-readlink <link>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Show the target of the soft link at the path <code><link></code>.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdreboot"><h2>2.54 Reboot the system (reboot)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-reboot [<n>]
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Reset and reboot the system immediately.
- This command depends on hardware support to reset the system.
- The optional, decimal numeric argument <n> may be included to provide a reboot mode to board-specific reboot logic.
-</p>
-<p>
- NOTE: Supporting both the <code>reboot</code> and <code>shutdown</code> commands is redundant.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdrm"><h2>2.55 Remove a File (rm)</h2></a>
- </td>
-</tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-rm <file-path>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Remove the specified <code><file-path></code> name from the mounted file system.
- Recall that NuttX uses a <a href="NuttxUserGuide.html#FileSystemOverview"><i>pseudo</i> file system</a> for its root file
- system.
- The <code>rm</code> command can only be used to remove (unlink) files in volumes set up with the
- <a href="#cmdmount"><code>mount</code></a> command;
- it cannot be used to remove names in the <i>pseudo</i> file system.
-</p>
-<p><b>Example:</b></p>
-<ul><pre>
-nsh> ls /mnt/fs/testdir
-/mnt/fs/testdir:
- TESTFILE.TXT
- EXAMPLE.TXT
-nsh> rm /mnt/fs/testdir/example.txt
-nsh> ls /mnt/fs/testdir
-/mnt/fs/testdir:
- TESTFILE.TXT
-nsh>
-</pre></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdrmdir"><h2>2.56 Remove a Directory (rmdir)</h2></a>
- </td>
-</tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-rmdir <dir-path>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Remove the specified <code><dir-path></code> directory from the mounted file system.
- Recall that NuttX uses a <a href="NuttxUserGuide.html#FileSystemOverview"><i>pseudo</i> file system</a> for its root file
- system.
- The <code>rmdir</code> command can only be used to remove directories from volumes set up with the
- <a href="#cmdmount"><code>mount</code></a> command;
- it cannot be used to remove directories from the <i>pseudo</i> file system.
-</p>
-<p><b>Example:</b></p>
-<ul><pre>
-nsh> mkdir /mnt/fs/tmp
-nsh> ls -l /mnt/fs
-/mnt/fs:
- drw-rw-rw- 0 TESTDIR/
- drw-rw-rw- 0 TMP/
-nsh> rmdir /mnt/fs/tmp
-nsh> ls -l /mnt/fs
-/mnt/fs:
- drw-rw-rw- 0 TESTDIR/
-nsh>
-</pre></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdrmmod"><h2>2.57 Remove on OS Module (rmmod)</h2></a>
- </td>
-</tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-rmmod <module-name>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Remove the loadable OS module with the <module-name>.
- NOTE: An OS module can only be removed if it is not busy.
-</p>
-<p><b>Example:</b></p>
-<ul><pre>
-nsh> lsmod
-NAME INIT UNINIT ARG TEXT SIZE DATA SIZE
-mydriver 20404659 20404625 0 20404580 552 204047a8 0
-nsh> rmmod mydriver
-nsh> lsmod
-NAME INIT UNINIT ARG TEXT SIZE DATA SIZE
-nsh>
-</pre></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdroute"><h2>2.58 Show routing table (route)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-route ipv4|ipv6
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Show the contents of routing table for IPv4 or IPv6.
-</p>
-<p>
- If only IPv4 or IPv6 is enabled, then the argument is optional but, if provided, must match the enabled internet protocol version.
-</p>
-
-<table width ="100%">
-<tr>
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdrptun"><h2>2.59 Start/Stop the OpenAMP RPC Tunnel (rptun)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-rptun start|stop <dev-path>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Start or stop the OpenAMP RPC tunnel device at <dev-path>.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdset"><h2>2.60 Set a Variable (set)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-set [{+|-}{e|x|xe|ex}] [<name> <value>]
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Set the variable <code><name></code> to the string <code><value></code> and or set NSH parser control options.
-</p>
-<p>
- For example, a variable may be set like this:
-</p>
-<ul><pre>
-nsh> echo $foobar
-
-nsh> set foobar foovalue
-nsh> echo $foobar
-foovalue
-nsh>
-</pre></ul>
-<p>
- If <code>CONFIG_NSH_VARS</code> is selected, the effect of this <code>set</code> command is to set the local NSH variable. Otherwise, the group-wide environment variable will be set.
-</p>
- If the local NSH variable has already been <i>promoted</i> to an environment variable via the <a href="#cmdexport"><code>export</code></a>, then the <code>set</code> command will set the value of the environment variable rather than the local NSH variable.
-</p>
-<p>
- <blockquote><small>
- <b>NOTE:</b> The <i>Bash</i> shell does not work this way.
- <i>Bash</i> would set the value of both the local <i>Bash</i> variable and the environment variable of the same name to the same value.
- </small></blockquote>
-</p>
-<p>
- If <code>CONFIG_NSH_VARS=y</code> is selected and no arguments are provided, then the <code>set</code> command will list all of the local NSH variables.
-</p>
-<ul><pre>
-nsh> set
-foolbar=foovalue
-</pre></ul>
-<p>
- Set the <i>exit on error control</i> and/or <i>print a trace</i> of commands when parsing scripts in NSH.
- The settings are in effect from the point of execution, until they are changed again, or in the case of the initialization script, the settings are returned to the default settings when it exits.
- Included child scripts will run with the parents settings and changes made in the child script will effect the parent on return.
-</p>
-<ul>
-<li><p>
- Use <code>set -e</code> to enable and <code>set +e</code> to disable (ignore) the exit condition on commands.
- The default is -e. Errors cause script to exit.
-</p></li>
-<li><p>
- Use <code>set -x</code> to enable and <code>set +x</code> to disable (silence) printing a trace of the script commands as they are executed.
- The default is <code>+x</code>: no printing of a trace of script commands as they are executed.
-</p></li>
-</ul>
-<p>
- Example 1 - no exit on command not found
-</p>
-<ul><pre>
-set +e
-notacommand
-</pre></ul>
-<p>
- Example 2 - will exit on command not found
-</p>
-<ul><pre>
-set -e
-notacommand
-</pre></ul>
-<p>
- Example 3 - will exit on command not found, and print a trace of the script commands
-</p>
-<ul><pre>
-set -ex
-</pre></ul>
-<p>
- Example 4 - will exit on command not found, and print a trace of the script commands and set foobar to foovalue.
-</p>
-<ul><pre>
-set -ex foobar foovalue
-nsh> echo $foobar
-foovalue
-</pre></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdsh"><h2>2.61 Execute an NSH Script (sh)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-sh <script-path>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Execute the sequence of NSH commands in the file referred
- to by <code><script-path></code>.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdshutdown"><h2>2.62 Shut the system down (shutdown)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-shutdown [--reboot]
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Shutdown and power off the system or, optionally, reset and reboot the system immediately.
- This command depends on hardware support to power down or reset the system; one, both, or neither behavior may be supported.
-</p>
-<p>
- NOTE: The <code>shutdown</code> command duplicates the behavior of the <code>poweroff</code> and <code>eboot</code> commands.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdsleep"><h2>2.63 Wait for Seconds (sleep)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-sleep <sec>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Pause execution (sleep) for <code><sec></code> seconds.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdtelnetd"><h2>2.64 Time Start the Telnet Daemon (telnetd)</h2></a>
- </td>
-</tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-telnetd
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Start the Telnet daemon if it is not already running.
-</p>
-<p>
- The Telnet daemon may be started either programmatically by calling <code>nsh_telnetstart()</code> or it may be started from the NSH command line using this <code>telnetd</code> command.
-</p>
-<p>
- Normally this command would be suppressed with <code>CONFIG_NSH_DISABLE_TELNETD</code> because the Telnet daemon is automatically started in <code>nsh_main.c</code>. The exception is when <code>CONFIG_NSH_NETLOCAL</code> is selected. In that case, the network is not enabled at initialization but rather must be enabled from the NSH command line or via other applications.
-</p>
-<p>
- In that case, when <code>nsh_telnetstart()</code> is called before the the network is initialized, it will fail.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdtime"><h2>2.65 Time execution of another command (time)</h2></a>
- </td>
-</tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-time "<command>"
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Perform command timing.
- This command will execute the following <command> string and then show how much time was required to execute the command.
- Time is shown with a resolution of 100 microseconds which may be beyond the resolution of many configurations.
- Note that the <command> must be enclosed in quotation marks if it contains spaces or other delimiters.
-</p>
-<p><b>Example:</b></p>
-<ul><pre>
-nsh> time "sleep 2"
-
-2.0100 sec
-nsh>
-</pre></ul>
-<p>
- The additional 10 milliseconds in this example is due to the way that the sleep command works: It always waits one system clock tick longer than requested and this test setup used a 10 millisecond periodic system timer.
- Sources of error could include various quantization errors, competing CPU usage, and the additional overhead of the time command execution itself which is included in the total.
-</p>
-<p>
- The reported time is the elapsed time from starting of the command to completion of the command.
- This elapsed time may not necessarily be just the processing time for the command.
- It may included interrupt level processing, for example.
- In a busy system, command processing could be delayed if pre-empted by other, higher priority threads competing for CPU time.
- So the reported time includes all CPU processing from the start of the command to its finish possibly including unrelated processing time during that interval.
-</p>
-<p>
- Notice that:
-</p>
-<ul><pre>
-nsh> time "sleep 2 &"
-sleep [3:100]
-
-0.0000 sec
-nsh>
-</pre></ul>
-<p>
- Since the sleep command is executed in background, the sleep command completes almost immediately.
- As opposed to the following where the time command is run in background with the sleep command:
-</p>
-<ul><pre>
-nsh> time "sleep 2" &
-time [3:100]
-nsh>
-2.0100 sec
-</pre></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdtruncate"><h2>2.66 Set the Size of a File (truncate)</h2></a>
- </td>
-</tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-truncate -s <length> <file-path>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Shrink or extend the size of the regular file at <file-path> to the
- specified<length>.
-</p>
-<p>
- A <file-path> argument that does not exist is created. The <length>
- option is NOT optional.
-</p>
-<p>
- If a <file-path> is larger than the specified size, the extra data is
- lost. If a <file-path> is shorter, it is extended and the extended part
- reads as zero bytes.
-</p>
-</pre></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdunmount"><h2>2.67 Unmount a File System (umount)</h2></a>
- </td>
-</tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-umount <dir-path>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Un-mount the file system at mount point <code><dir-path></code>.
- The <code>umount</code> command can only be used to un-mount volumes previously mounted using
- <a href="#cmdmount"><code>mount</code></a> command.
-</p>
-<p><b>Example:</b></p>
-<ul><pre>
-nsh> ls /mnt/fs
-/mnt/fs:
- TESTDIR/
-nsh> umount /mnt/fs
-nsh> ls /mnt/fs
-/mnt/fs:
-nsh: ls: no such directory: /mnt/fs
-nsh>
-</pre></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmduname"><h2>2.68 Print system information (uname)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-uname [-a | -imnoprsv]
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Print certain system information. With no options, the output is the same as -s.
-<p>
-<ul><table>
- <tr>
- <td><code>-a</code></td>
- <td>
- Print all information, in the following order, except omit -p and -i if unknown:
- </td>
- </tr>
- <tr>
- <td><code>-s, -o</code></td>
- <td>
- Print the operating system name (NuttX)
- </td>
- </tr>
- <tr>
- <td><code>-n</code></td>
- <td>
- Print the network node hostname (only available if <code>CONFIG_NET=y</code>)
- </td>
- </tr>
- <tr>
- <td><code>-r</code></td>
- <td>
- Print the kernel release
- </td>
- </tr>
- <tr>
- <td><code>-v</code></td>
- <td>
- Print the kernel version
- </td>
- </tr>
- <tr>
- <td><code>-m</code></td>
- <td>
- Print the machine hardware name
- </td>
- </tr>
- <tr>
- <td><code>-i</code></td>
- <td>
- Print the machine platform name
- </td>
- </tr>
- <tr>
- <td><code>-p</code></td>
- <td>
- Print "unknown"
- </td>
- </tr>
-</table></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdunset"><h2>2.69 Unset an Environment Variable (unset)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-unset <name>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Remove the value associated with the variable <code><name></code>.
- This will remove the name-value pair from both the NSH local variables and the group-wide environment variables. For example:
-</p>
-<ul><pre>
-nsh> echo $foobar
-foovalue
-nsh> unset foobar
-nsh> echo $foobar
-
-nsh>
-</pre></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdurldec"><h2>2.70 URL Decode (urldecode)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-urldecode [-f] <string or filepath>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- <i>To be provided.</i>
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdurlencode"><h2>2.71 URL Encode (urlencode)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-urlencode [-f] <string or filepath>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- <i>To be provided.</i>
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmduseradd"><h2>2.72 Add a New User (useradd)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-useradd <username> <password>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Add a new user with <username> and <password>.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmduserdel"><h2>2.73 Delete a user (userdel)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-userdel <username>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Delete the user with the name <username>.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdusleep"><h2>2.74 Wait for Microseconds (usleep)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-usleep <usec>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Pause execution (sleep) of <code><usec></code> microseconds.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdwget"><h2>2.75 Get File Via HTTP (wget)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-wget [-o <local-path>] <url>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Use HTTP to copy the file at <code><url></code> to the current directory.
-</p>
-<p><b>Options:</b></p>
-<ul><table>
- <tr>
- <td><b><code>-o <local-path></code></b></td>
- <td>
- The file will be saved relative to the current working directory
- and with the same name as on the HTTP server unless <code><local-path></code> is provided.
- </td>
- </tr>
-</table></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmdxd"><h2>2.76 Hexadecimal Dump of Memory (xd)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-xd <hex-address> <byte-count>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Dump <code><byte-count></code> bytes of data from address <code><hex-address></code>.
-</p>
-<p><b>Example:</b></p>
-<ul><pre>
-nsh> xd 410e0 512
-Hex dump:
-0000: 00 00 00 00 9c 9d 03 00 00 00 00 01 11 01 10 06 ................
-0010: 12 01 11 01 25 08 13 0b 03 08 1b 08 00 00 02 24 ....%..........$
-...
-01f0: 08 3a 0b 3b 0b 49 13 00 00 04 13 01 01 13 03 08 .:.;.I..........
-nsh>
-</pre></ul>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="builtincmds"><h1>3.0 Built-In Commands</h1></a>
- </td>
- </tr>
-</table>
-
-<p>
- In addition to the commands that are part of NSH listed in the previous section above, there can be additional, external <i>built-in</i> applications that can be added to NSH.
- These are separately excecuble programs but will appear much like the commands that are a part of NSH.
- The primary difference from the user's perspective is that help information about the built-in applications is not available directly from NSH.
- Rather, you will need to execute the application with the <code>-h</code> option to get help about using the built-in applications.
-</p>
-
-<p>
- There are several built-in applications in the <code>apps/</code> repository.
- No attempt is made here to enumerate all of them.
- But a few of the more common, useful built-in applications are listed below.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="builtinping"><h2>3.1 Check Network Peer (ping/ping6)</h2></a>
- </td>
- </tr>
-</table>
-
-<p><b>Command Syntax:</b></p>
-<ul><pre>
-ping [-c <count>] [-i <interval>] <ip-address>
-ping6 [-c <count>] [-i <interval>] <ip-address>
-</pre></ul>
-<p>
- <b>Synopsis</b>.
- Test the network communication with a remote peer. Example,
-</p>
-<ul><pre>
-nsh> ping 10.0.0.1
-PING 10.0.0.1 56 bytes of data
-56 bytes from 10.0.0.1: icmp_seq=1 time=0 ms
-56 bytes from 10.0.0.1: icmp_seq=2 time=0 ms
-56 bytes from 10.0.0.1: icmp_seq=3 time=0 ms
-56 bytes from 10.0.0.1: icmp_seq=4 time=0 ms
-56 bytes from 10.0.0.1: icmp_seq=5 time=0 ms
-56 bytes from 10.0.0.1: icmp_seq=6 time=0 ms
-56 bytes from 10.0.0.1: icmp_seq=7 time=0 ms
-56 bytes from 10.0.0.1: icmp_seq=8 time=0 ms
-56 bytes from 10.0.0.1: icmp_seq=9 time=0 ms
-56 bytes from 10.0.0.1: icmp_seq=10 time=0 ms
-10 packets transmitted, 10 received, 0% packet loss, time 10190 ms
-nsh>
-</pre></ul>
-</p>
- <code>ping6</code> differs from <code>ping</code> in that it uses IPv6 addressing.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="configuration"><h1>4.0 Configuration Settings</h1></a>
- </td>
- </tr>
-</table>
-
-<p>
- The availability of the above commands depends upon features that
- may or may not be enabled in the NuttX configuration file. The
- following <a href="#cmddependencies">table</a> indicates the dependency of each command on NuttX
- configuration settings. General configuration settings are discussed
- in the <a href="NuttxPortingGuide.html">NuttX Porting Guide.</a>
- Configuration settings specific to NSH as discussed at the <a href="#nshconfiguration">bottom</a> of this document.
-</p>
-
-<p>
- Note that in addition to general NuttX configuration settings, each NSH command can be
- individually disabled via the settings in the rightmost column.
- All of these settings make the configuration of NSH potentially complex but also allow it to
- squeeze into very small memory footprints.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="cmddependencies"><h2>4.1 Command Dependencies on Configuration Settings</h2></a>
- </td>
- </tr>
-</table>
-
-<center><p>Table. Command Dependencies on Configuration Settings</p>
-<table width="100%">
- <tr bgcolor="#e4e4e4">
- <th align="left" width="25%">Command</th>
- <th align="left">Depends on Configuration</th>
- <th align="left">Can Be Disabled with</th>
- </tr>
- <tr>
- <td><b><code>[</code></b></td>
- <td>!<code>CONFIG_NSH_DISABLESCRIPT</code></td>
- <td><code>CONFIG_NSH_DISABLE_TEST</code></td>
- </tr>
- <tr>
- <td><b><code>addroute</code></b></td>
- <td><code>CONFIG_NET</code> && <code>CONFIG_NET_ROUTE</code></td>
- <td><code>CONFIG_NSH_DISABLE_ADDROUTE</code></td>
- </tr>
- <tr>
- <td><b><code>arp</code></b></td>
- <td><code>CONFIG_NET</code> && <code>CONFIG_NET_ARP</code></td>
- <td><code>CONFIG_NSH_DISABLE_ARP</code></td>
- </tr>
- <tr>
- <td><b><code>base64dec</code></b></td>
- <td><code>CONFIG_NETUTILS_CODECS</code> && <code>CONFIG_CODECS_BASE64</code></td>
- <td><code>CONFIG_NSH_DISABLE_BASE64DEC</code></td>
- </tr>
- <tr>
- <td><b><code>base64enc</code></b></td>
- <td><code>CONFIG_NETUTILS_CODECS</code> && <code>CONFIG_CODECS_BASE64</code></td>
- <td><code>CONFIG_NSH_DISABLE_BASE64ENC</code></td>
- </tr>
- <tr>
- <td><b><code>basename</code></b></td>
- <td> </td>
- <td><code>CONFIG_NSH_DISABLE_BASENAME</code></td>
- </tr>
- <tr>
- <td><b><code>break</code></b></td>
- <td>!<code>CONFIG_NSH_DISABLESCRIPT</code> && !<code>CONFIG_NSH_DISABLE_LOOPS</code></td>
- <td> </td>
- </tr>
- <tr>
- <td><b><code>cat</code></b></td>
- <td> </td>
- <td><code>CONFIG_NSH_DISABLE_CAT</code></td>
- </tr>
- <tr>
- <td><b><code>cd</code></b></td>
- <td>!<code>CONFIG_DISABLE_ENVIRON</code></td>
- <td><code>CONFIG_NSH_DISABLE_CD</code></td>
- </tr>
- <tr>
- <td><b><code>cmp</code></b></td>
- <td> </td>
- <td><code>CONFIG_NSH_DISABLE_CMP</code></td>
- </tr>
- <tr>
- <td><b><code>cp</code></b></td>
- <td> </td>
- <td><code>CONFIG_NSH_DISABLE_CP</code></td>
- </tr>
- <tr>
- <td><b><code>date</code></b></td>
- <td><br></td>
- <td><code>CONFIG_NSH_DISABLE_DATE</code></td>
- </tr>
- <tr>
- <td><b><code>dd</code></b></td>
- <td> </td>
- <td><code>CONFIG_NSH_DISABLE_DD</code></td>
- </tr>
- <tr>
- <td><b><code>delroute</code></b></td>
- <td><code>CONFIG_NET</code> && <code>CONFIG_NET_ROUTE</code></td>
- <td><code>CONFIG_NSH_DISABLE_DELROUTE</code></td>
- </tr>
- <tr>
- <td><b><code>df</code></b></td>
- <td>!<code>CONFIG_DISABLE_MOUNTPOINT</code></code></td>
- <td><code>CONFIG_NSH_DISABLE_DF</code></td>
- </tr>
- <tr>
- <td><b><code>dirname</code></b></td>
- <td> </td>
- <td><code>CONFIG_NSH_DISABLE_DIRNAME</code></td>
- </tr>
- <tr>
- <td><b><code>dmesg</code></b></td>
- <td><code>CONFIG_RAMLOG_SYSLOG</code></td>
- <td><code>CONFIG_NSH_DISABLE_DMESG</code></td>
- </tr>
- <tr>
- <td><b><code>echo</code></b></td>
- <td><br></td>
- <td><code>CONFIG_NSH_DISABLE_ECHO</code></td>
- </tr>
- <tr>
- <td><b><code>env</code></b></td>
- <td><code>CONFIG_FS_PROCFS</code> && !<code>CONFIG_DISABLE_ENVIRON</code> && !<code>CONFIG_PROCFS_EXCLUDE_ENVIRON</code>
- <td><code>CONFIG_NSH_DISABLE_ENV</code></td>
- </tr>
- <tr>
- <td><b><code>exec</code></b></td>
- <td><br></td>
- <td><code>CONFIG_NSH_DISABLE_EXEC</code></td>
- </tr>
- <tr>
- <td><b><code>exit</code></b></td>
- <td><br></td>
- <td><code>CONFIG_NSH_DISABLE_EXIT</code></td>
- </tr>
- <tr>
- <td><b><code>export</code></b></td>
- <td><code>CONFIG_NSH_VARS</code> && !<code>CONFIG_DISABLE_ENVIRON</code></td>
- <td><code>CONFIG_NSH_DISABLE_EXPORT</code></td>
- </tr>
- <tr>
- <td><b><code>free</code></b></td>
- <td><br></td>
- <td><code>CONFIG_NSH_DISABLE_FREE</code></td>
- </tr>
- <tr>
- <td><b><code>get</code></b></td>
- <td><code>CONFIG_NET</code> && <code>CONFIG_NET_UDP</code> && <i>MTU</i> >= 558<sup>1</sup></td>
- <td><code>CONFIG_NSH_DISABLE_GET</code></td>
- </tr>
- <tr>
- <td><b><code>help</code></b><sup>3</sup></td>
- <td><br></td>
- <td><code>CONFIG_NSH_DISABLE_HELP</code></td>
- </tr>
- <tr>
- <td><b><code>hexdump</code></b></td>
- <td> </td>
- <td><code>CONFIG_NSH_DISABLE_HEXDUMP</code></td>
- </tr>
- <tr>
- <td><b><code>ifconfig</code></b></td>
- <td><code>CONFIG_NET</code> && <code>CONFIG_FS_PROCFS</code> && !<code>CONFIG_FS_PROCFS_EXCLUDE_NET</code></td>
- <td><code>CONFIG_NSH_DISABLE_IFCONFIG</code></td>
- </tr>
- <tr>
- <td><b><code>ifdown</code></b></td>
- <td><code>CONFIG_NET</code> && <code>CONFIG_FS_PROCFS</code> && !<code>CONFIG_FS_PROCFS_EXCLUDE_NET</code></td>
- <td><code>CONFIG_NSH_DISABLE_IFUPDOWN</code></td>
- </tr>
- <tr>
- <td><b><code>ifup</code></b></td>
- <td><code>CONFIG_NET</code> && <code>CONFIG_FS_PROCFS</code> && !<code>CONFIG_FS_PROCFS_EXCLUDE_NET</code></td>
- <td><code>CONFIG_NSH_DISABLE_IFUPDOWN</code></td>
- </tr>
- <tr>
- <td><b><code>insmod</code></b></td>
- <td><code>CONFIG_MODULE</code></td>
- <td><code>CONFIG_NSH_DISABLE_MODCMDS</code></td>
- </tr>
- <tr>
- <td><b><code>irqinfo</code></b></td>
- <td>!<code>CONFIG_DISABLE_MOUNTPOINT</code> && <code>CONFIG_FS_PROCFS</code> && <code>CONFIG_SCHED_IRQMONITOR</code></td>
- <td><br></td>
- </tr>
- <tr>
- <td><b><code>kill</code></b></td>
- <td> </td>
- <td><code>CONFIG_NSH_DISABLE_KILL</code></td>
- </tr>
- <tr>
- <td><b><code>losetup</code></b></td>
- <td>!<code>CONFIG_DISABLE_MOUNTPOINT</code> && <code>CONFIG_DEV_LOOP</code></td>
- <td><code>CONFIG_NSH_DISABLE_LOSETUP</code></td>
- </tr>
- <tr>
- <td><b><code>ln</code></b></td>
- <td><code>CONFIG_PSEUDOFS_SOFTLINKS</code></td>
- <td><code>CONFIG_NSH_DISABLE_LN</code></td>
- </tr>
- <tr>
- <td><b><code>ls</code></b></td>
- <td> </td>
- <td><code>CONFIG_NSH_DISABLE_LS</code></td>
- </tr>
- <tr>
- <td><b><code>lsmod</code></b></td>
- <td><code>CONFIG_MODULE</code> && <code>CONFIG_FS_PROCFS</code> && !<code>CONFIG_FS_PROCFS_EXCLUDE_MODULE</code></td>
- <td><code>CONFIG_NSH_DISABLE_MODCMDS</code></td>
- </tr>
- <tr>
- <td><b><code>md5</code></b></td>
- <td><code>CONFIG_NETUTILS_CODECS</code> && <code>CONFIG_CODECS_HASH_MD5</code></td>
- <td><code>CONFIG_NSH_DISABLE_MD5</code></td>
- </tr>
- <tr>
- <td><b><code>mb,mh,mw</code></b></td>
- <td><br></td>
- <td>
- <code>CONFIG_NSH_DISABLE_MB</code>,<br>
- <code>CONFIG_NSH_DISABLE_MH</code>,<br>
- <code>CONFIG_NSH_DISABLE_MW</code>
- </td>
- </tr>
- <tr>
- <td><b><code>mkdir</code></b></td>
- <td>(!<code>CONFIG_DISABLE_MOUNTPOINT</code> || !<code>CONFIG_DISABLE_PSEUDOFS_OPERATIONS</code>)</td>
- <td><code>CONFIG_NSH_DISABLE_MKDIR</code></td>
- </tr>
- <tr>
- <td><b><code>mkfatfs</code></b></td>
- <td>!<code>CONFIG_DISABLE_MOUNTPOINT</code> && <code>CONFIG_FSUTILS_MKFATFS</code></td>
- <td><code>CONFIG_NSH_DISABLE_MKFATFS</code></td>
- </tr>
- <tr>
- <td><b><code>mkfifo</code></b></td>
- <td><code>CONFIG_PIPES</code> && <code>CONFIG_DEV_FIFO_SIZE</code> > 0</td>
- <td><code>CONFIG_NSH_DISABLE_MKFIFO</code></td>
- </tr>
- <tr>
- <td><b><code>mkrd</code></b></td>
- <td>!<code>CONFIG_DISABLE_MOUNTPOINT</code></code></td>
- <td><code>CONFIG_NSH_DISABLE_MKRD</code></td>
- </tr>
- <tr>
- <td><b><code>mount</code></b></td>
- <td>!<code>CONFIG_DISABLE_MOUNTPOINT</code></code></td>
- <td><code>CONFIG_NSH_DISABLE_MOUNT</code></td>
- </tr>
- <tr>
- <td><b><code>mv</code></b></td>
- <td>!<code>CONFIG_DISABLE_MOUNTPOINT</code> || !<code>CONFIG_DISABLE_PSEUDOFS_OPERATIONS</code></td>
- <td><code>CONFIG_NSH_DISABLE_MV</code></td>
- </tr>
- <tr>
- <td><b><code>nfsmount</code></b></td>
- <td>!<code>CONFIG_DISABLE_MOUNTPOINT</code> && <code>CONFIG_NET</code> && <code>CONFIG_NFS</code></td>
- <td><code>CONFIG_NSH_DISABLE_NFSMOUNT</code></td>
- </tr>
- <tr>
- <td><b><code>nslookup</code></b></td>
- <td><code>CONFIG_LIBC_NETDB</code> && <code>CONFIG_NETDB_DNSCLIENT</code></td>
- <td><code>CONFIG_NSH_DISABLE_NSLOOKUP</code></td>
- </tr>
- <tr>
- <td><b><code>passwd</code></b></td>
- <td>!<code>CONFIG_DISABLE_MOUNTPOINT</code> && <code>CONFIG_NSH_LOGIN_PASSWD</code></td>
- <td><code>CONFIG_NSH_DISABLE_PASSWD</code></td>
- </tr>
- <tr>
- <td><b><code>pmconfig</code></b></td>
- <td><code>CONFIG_PM</td>
- <td><code>CONFIG_NSH_DISABLE_PMCONFIG</code></td>
- </tr>
- <tr>
- <td><b><code>poweroff</code></b></td>
- <td><code>CONFIG_BOARDCTL_POWEROFF</td>
- <td><code>CONFIG_NSH_DISABLE_POWEROFF</code></td>
- </tr>
- <tr>
- <td><b><code>ps</code></b></td>
- <td><code>CONFIG_FS_PROCFS</code> && !<code>CONFIG_FS_PROCFS_EXCLUDE_PROC</code></td>
- <td><code>CONFIG_NSH_DISABLE_PS</code></td>
- </tr>
- <tr>
- <td><b><code>put</code></b></td>
- <td><code>CONFIG_NET</code> && <code>CONFIG_NET_UDP</code> &&
- <code><i>MTU</i> >= 558<sup>1,2</sup></td>
- <td><code>CONFIG_NSH_DISABLE_PUT</code></td>
- </tr>
- <tr>
- <td><b><code>pwd</code></b></td>
- <td>!<code>CONFIG_DISABLE_ENVIRON</code></td>
- <td><code>CONFIG_NSH_DISABLE_PWD</code></td>
- </tr>
- <tr>
- <td><b><code>readlink</code></b></td>
- <td><code>CONFIG_PSEUDOFS_SOFTLINKS</code></td>
- <td><code>CONFIG_NSH_DISABLE_READLINK</code></td>
- </tr>
- <tr>
- <td><b><code>reboot</code></b></td>
- <td><code>CONFIG_BOARD_RESET</code></td>
- <td><code>CONFIG_NSH_DISABLE_REBOOT</code></td>
- </tr>
- <tr>
- <td><b><code>rm</code></b></td>
- <td>!<code>CONFIG_DISABLE_MOUNTPOINT</code> || !<code>CONFIG_DISABLE_PSEUDOFS_OPERATIONS</code></td>
- <td><code>CONFIG_NSH_DISABLE_RM</code></td>
- </tr>
- <tr>
- <td><b><code>rmdir</code></b></td>
- <td>!<code>CONFIG_DISABLE_MOUNTPOINT</code> || !<code>CONFIG_DISABLE_PSEUDOFS_OPERATIONS</code></td>
- <td><code>CONFIG_NSH_DISABLE_RMDIR</code></td>
- </tr>
- <tr>
- <td><b><code>rmmod</code></b></td>
- <td><code>CONFIG_MODULE</code></td>
- <td><code>CONFIG_NSH_DISABLE_MODCMDS</code></td>
- </tr>
- <tr>
- <td><b><code>route</code></b></td>
- <td><code><code>CONFIG_FS_PROCFS</code> && <code>CONFIG_FS_PROCFS_EXCLUDE_NET</code> && !<code>CONFIG_FS_PROCFS_EXCLUDE_ROUTE</code> && <code>CONFIG_NET_ROUTE</code> && !<code>CONFIG_NSH_DISABLE_ROUTE</code> && (<code>CONFIG_NET_IPv4</code> || <code>CONFIG_NET_IPv6</code>)</code></td>
- <td><code>CONFIG_NSH_DISABLE_ROUTE</code></td>
- </tr>
- <tr>
- <td><b><code>rptun</code></b></td>
- <td><code><code>CONFIG_RPTUN</code>
- <td><code>CONFIG_NSH_DISABLE_RPTUN</code></td>
- </tr>
- <tr>
- <td><b><code>set</code></b></td>
- <td><code>CONFIG_NSH_VARS</code> || !<code>CONFIG_DISABLE_ENVIRON</code></td>
- <td><code>CONFIG_NSH_DISABLE_SET</code></td>
- </tr>
- <tr>
- <td><b><code>shutdown</code></b></td>
- <td><code>CONFIG_BOARDCTL_POWEROFF || CONFIG_BOARD_RESET</code></td>
- <td><code>CONFIG_NSH_DISABLE_SHUTDOWN</code></td>
- </tr>
- <tr>
- <td><b><code>sleep</code></b></td>
- <td> </td>
- <td><code>CONFIG_NSH_DISABLE_SLEEP</code></td>
- </tr>
- <tr>
- <td><b><code>source</code></b></td>
- <td><code>CONFIG_NFILE_STREAMS > 0 && !<code>CONFIG_NSH_DISABLESCRIPT</code></td>
- <td><code>CONFIG_NSH_DISABLE_SOURCE</code></td>
- </tr>
- <tr>
- <td><b><code>telnetd</code></b></td>
- <td><code>CONFIG_NSH_TELNET</code></td>
- <td><code>CONFIG_NSH_DISABLE_TELNETD</code></td>
- </tr>
- <tr>
- <td><b><code>test</code></b></td>
- <td>!<code>CONFIG_NSH_DISABLESCRIPT</code></td>
- <td><code>CONFIG_NSH_DISABLE_TEST</code></td>
- </tr>
- <tr>
- <td><b><code>time</code></b></td>
- <td> </td>
- <td><code>CONFIG_NSH_DISABLE_TIME</code></td>
- </tr>
- <tr>
- <td><b><code>truncate</code></b></td>
- <td>!<code>CONFIG_DISABLE_MOUNTPOINT</code></td>
- <td><code>CONFIG_NSH_DISABLE_TRUNCATE</code></td>
- </tr>
- <tr>
- <td><b><code>umount</code></b></td>
- <td>!<code>CONFIG_DISABLE_MOUNTPOINT</code></code></td>
- <td><code>CONFIG_NSH_DISABLE_UMOUNT</code></td>
- </tr>
- <tr>
- <td><b><code>uname</code></b></td>
- <td> </td>
- <td><code>CONFIG_NSH_DISABLE_UNAME</code></td>
- </tr>
- <tr>
- <td><b><code>unset</code></b></td>
- <td><code>CONFIG_NSH_VARS</code> || !<code>CONFIG_DISABLE_ENVIRON</code></td>
- <td><code>CONFIG_NSH_DISABLE_UNSET</code></td>
- </tr>
- <tr>
- <td><b><code>urldecode</code></b></td>
- <td>!<code>CONFIG_NETUTILS_CODECS</code> && <code>CONFIG_CODECS_URLCODE</code>
- <td><code>CONFIG_NSH_DISABLE_URLDECODE</code></td>
- </tr>
- <tr>
- <td><b><code>urlencode</code></b></td>
- <td>!<code>CONFIG_NETUTILS_CODECS</code> && <code>CONFIG_CODECS_URLCODE</code>
- <td><code>CONFIG_NSH_DISABLE_URLENCODE</code></td>
- </tr>
- <tr>
- <td><b><code>useradd</code></b></td>
- <td>!<code>CONFIG_DISABLE_MOUNTPOINT</code> && <code>CONFIG_NSH_LOGIN_PASSWD</code></td>
- <td><code>CONFIG_NSH_DISABLE_USERADD</code></td>
- </tr>
- <tr>
- <td><b><code>userdel</code></b></td>
- <td>!<code>CONFIG_DISABLE_MOUNTPOINT</code> && <code>CONFIG_NSH_LOGIN_PASSWD</code></td>
- <td><code>CONFIG_NSH_DISABLE_USERDEL</code></td>
- </tr>
- <tr>
- <td><b><code>usleep</code></b></td>
- <td> </td>
- <td><code>CONFIG_NSH_DISABLE_USLEEP</code></td>
- </tr>
- <tr>
- <td><b><code>wget</code></b></td>
- <td><code>CONFIG_NET</code> && <code>CONFIG_NET_TCP</code></td>
- <td><code>CONFIG_NSH_DISABLE_WGET</code></td>
- </tr>
- <tr>
- <td><b><code>xd</code></b></td>
- <td><br></td>
- <td><code>CONFIG_NSH_DISABLE_XD</code></td>
- </tr>
-</table></center>
-
-<p><sup>1</sup><small>
- Because of hardware padding, the actual required packet size may be larger</small><br>
- <sup>2</sup><small>
- Special TFTP server start-up options will probably be required to permit
- creation of files for the correct operation of the <code>put</code> command.</small><br>
- <sup>3</sup><small>
- Verbose help output can be suppressed by defining <code>CONFIG_NSH_HELP_TERSE</code>.
- In that case, the help command is still available but will be slightly smaller.
- </small>
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="builtinconfig"><h2>4.2 Built-In Command Dependencies on Configuration Settings</h2></a>
- </td>
- </tr>
-</table>
-
-<p>
- All built-in applications require that support for NSH built-in applications has been enabled.
- This support is enabled with <code>CONFIG_BUILTIN=y</code> and <code>CONFIG_NSH_BUILTIN_APPS=y</code>.
-</p>
-
-<center><p>Table. Built-In Command Dependencies on Configuration Settings</p>
-<table width="100%">
- <tr bgcolor="#e4e4e4">
- <th align="left" width="25%">Command</th>
- <th align="left">Depends on Configuration</th>
- </tr>
- <tr>
- <td><b><code>ping</code></b></td>
- <td><code>CONFIG_NET</code> && <code>CONFIG_NET_ICMP</code> &&
- <code>CONFIG_NET_ICMP_SOCKET</code> && <code>CONFIG_SYSTEM_PING</code></td>
- </tr>
- <tr>
- <td><b><code>ping6</code></b></td>
- <td><code>CONFIG_NET</code> && <code>CONFIG_NET_ICMPv6</code> &&
- <code>CONFIG_NET_ICMPv6_SOCKET</code> && <code>CONFIG_SYSTEM_PING6</code></td>
- </tr>
-</table></center>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="nshconfiguration"><h2>4.3 NSH-Specific Configuration Settings</h2></a>
- </td>
- </tr>
-</table>
-
-<p>
- The behavior of NSH can be modified with the following settings in
- the <code>boards/<arch>/<chip>/<board>/defconfig</code> file:
-</p>
-
-<center><table width="100%">
- <tr bgcolor="#e4e4e4">
- <th align="left" width="25%">Configuration</th>
- <th align="left">Description</th>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_READLINE</code></b></td>
- <td>
- Selects the minimal implementation of <code>readline()</code>.
- This minimal implementation provides on backspace for command line editing.
- It expects some minimal VT100 command support from the terminal.
- </td>
- </tr>
-
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_CLE</code></b></td>
- <td>
- Selects the more extensive, EMACS-like command line editor.
- Select this option only if
- (1) you don't mind a modest increase in the FLASH footprint, and
- (2) you work with a terminal that supports extensive VT100 editing commands.
- Selecting this option will add probably 1.5-2KB to the FLASH footprint.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_BUILTIN_APPS</code></b></td>
- <td>
- Support external registered, "builtin" applications that can be
- executed from the NSH command line (see apps/README.txt for
- more information).
- This required <code>CONFIG_BUILTIN</code> to enable NuttX support for
- "builtin" applications.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_FILEIOSIZE</code></b></td>
- <td>
- Size of a static I/O buffer used for file access (ignored if
- there is no file system). Default is 1024.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_STRERROR</code></b></td>
- <td>
- <code>strerror(errno)</code> makes more readable output but <code>strerror()</code> is
- very large and will not be used unless this setting is <i>y</i>.
- This setting depends upon the <code>strerror()</code> having been enabled with <code>CONFIG_LIBC_STRERROR</code>.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_LINELEN</code></b></td>
- <td>
- The maximum length of one command line and of one output line.
- Default: 80
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_DISABLE_SEMICOLON</code></b></td>
- <td>
- By default, you can enter multiple NSH commands on a line with each command separated by a semicolon.
- You can disable this feature to save a little memory on FLASH challenged platforms.
- Default: n
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_CMDPARMS</code></b></td>
- <td>
- If selected, then the output from commands, from file applications, and from NSH built-in commands can be used as arguments to other commands.
- The entity to be executed is identified by enclosing the command line in back quotes.
- For example,
- <ul><pre>
-set FOO `myprogram $BAR`
-</pre></ul>
- will execute the program named <code>myprogram </code> passing it the value of the environment variable <code>BAR</code>.
- The value of the environment variable <code>FOO</code> is then set output of <code>myprogram</code> on <code>stdout</code>. Because this feature commits significant resources, it is disabled by default.
-
- The <code>CONFIG_NSH_CMDPARMS</code> interim output will be retained in a temporary file.
- Full path to a directory where temporary files can be created is taken from <code>CONFIG_LIBC_TMPDIR</code> and it defaults to <code>/tmp</code> if <code>CONFIG_LIBC_TMPDIR</code> is not set.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_MAXARGUMENTS</code></b></td>
- <td>
- The maximum number of NSH command arguments. Default: 6
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_ARGCAT</code></b></td>
- <td>
- Support concatenation of strings with environment variables or command output.
- For example:
- <ul><pre>
-set FOO XYZ
-set BAR 123
-set FOOBAR ABC_${FOO}_${BAR}
-</pre></ul>
- would set the environment variable <code>FOO</code> to <code>XYZ</code>, <code>BAR</code> to <code>123</code> and <code>FOOBAR</code> to <code>ABC_XYZ_123</code>.
- If <code>CONFIG_NSH_ARGCAT</code> is not selected, then a slightly small FLASH footprint results but then also only simple environment variables like <code>$FOO</code> can be used on the command line.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_VARS</code></b></td>
- <td>
- By default, there are no internal NSH variables. NSH will use OS
- environment variables for all variable storage. If this option, NSH
- will also support local NSH variables. These variables are, for the
- most part, transparent and work just like the OS environment
- variables. The difference is that when you create new tasks, all of
- environment variables are inherited by the created tasks. NSH local
- variables are not.
- </p>
- <p>
- If this option is enabled (and CONFIG_DISABLE_ENVIRON is not), then a
- new command called 'export' is enabled. The export command works very
- must like the set command except that is operates on environment
- variables. When CONFIG_NSH_VARS is enabled, there are changes in the
- behavior of certain commands
- </p>
- <table border="1">
- <tr>
- <td valign="top" width="15%"><b>CMD</b></td>
- <td valign="top" width="30%"><b>w/o <code>CONFIG_NSH_VARS</code></b></td>
- <td valign="top" width="45%"><b>w/ <code>CONFIG_NSH_VARS</code></b></td>
- </tr>
- <tr>
- <td valign="top"><code>set <a> <b></code></td>
- <td valign="top">Set environment variable <a> to <b></td>
- <td valign="top">Set NSH variable <a> to <b>
- (Unless the NSH variable has been <i>promoted</i> via <code>export</code>, in which case the environment variable of the same name is set to <b>).
- </td>
- </tr>
- <tr>
- <td valign="top"><code>set</code></td>
- <td valign="top">Causes an error.</td>
- <td valign="top">Lists all NSH variables.</td>
- </tr>
- <tr>
- <td valign="top"><code>unset <a></code></td>
- <td valign="top">Unsets environment variable <a></td>
- <td valign="top">Unsets both environment variable <i>and</i> NSH variable with and name <a></td>
- </tr>
- <tr>
- <td valign="top"><code>export <a> <b></code></td>
- <td valign="top">Causes an error,</td>
- <td valign="top">Unsets NSH variable <a>. Sets environment variable <a> to <b>.</td>
- </tr>
- <tr>
- <td valign="top"><code>export <a></code></td>
- <td valign="top">Causes an error.</td>
- <td valign="top">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>.</td>
- </tr>
- <tr>
- <td valign="top"><code>env</code></td>
- <td valign="top">Lists all environment variables</td>
- <td valign="top">Lists all environment variables (<i>only</i>)</td>
- </tr>
- </table>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_QUOTE</code></b></td>
- <td>
- Enables back-slash quoting of certain characters within the command.
- This option is useful for the case where an NSH script is used to dynamically generate a new NSH script.
- In that case, commands must be treated as simple text strings without interpretation of any special characters.
- Special characters such as <code>$</code>, <code>`</code>, <code>"</code>, and others must be retained intact as part of the test string.
- This option is currently only available is <code>CONFIG_NSH_ARGCAT</code> is also selected.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_NESTDEPTH</code></b></td>
- <td>
- The maximum number of nested <a href="#conditional"><code>if-then[-else]-fi</code></a> sequences that
- are permissible. Default: 3
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_DISABLESCRIPT</code></b></td>
- <td>
- This can be set to <i>y</i> to suppress support for scripting. This
- setting disables the <a href="#cmdsh"><code>sh</code></a>, <a href="#cmdtest"><code>test</code></a>, and <a href="#cmtest"><code>[</code></a> commands and the
- <a href="#conditional"><code>if-then[-else]-fi</code></a> construct. This would only be set on systems
- where a minimal footprint is a necessity and scripting is not.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_DISABLE_ITEF</code></b></td>
- <td>
- If scripting is enabled, then then this option can be selected to suppress support for <code>if-then-else-fi</code> sequences in scripts.
- This would only be set on systems where some minimal scripting is required but <code>if-then-else-fi</code> is not.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_DISABLE_LOOPS</code></b></td>
- <td>
- If scripting is enabled, then then this option can be selected suppress support <code>for while-do-done</code> and <code>until-do-done</code> sequences in scripts.
- This would only be set on systems where some minimal scripting is required but looping is not.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_DISABLEBG</code></b></td>
- <td>
- This can be set to <i>y</i> to suppress support for background
- commands. This setting disables the <a href="#cmdoverview"><code>nice</code></a> command prefix and
- the <a href="#cmdoverview"><code>&</code></a> command suffix. This would only be set on systems
- where a minimal footprint is a necessity and background command execution is not.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_MMCSDMINOR</code></b></td>
- <td>
- If the architecture supports an MMC/SD slot and if the NSH
- architecture specific logic is present, this option will provide
- the MMC/SD minor number, i.e., the MMC/SD block driver will
- be registered as <code>/dev/mmcsd</code><i>N</i> where <i>N</i> is the minor number.
- Default is zero.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_ROMFSETC</code></b></td>
- <td>
- Mount a ROMFS file system at <code>/etc</code> and provide a startup script
- at <code>/etc/init.d/rcS</code>. The default startup script will mount
- a FAT FS RAMDISK at <code>/tmp</code> but the logic is
- <a href="#startupscript">easily extensible</a>.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_CONSOLE</code></b></td>
- <td>
- <p>
- If <code>CONFIG_NSH_CONSOLE</code> is set to <i>y</i>, then a serial
- console front-end is selected.
- </p>
- <p>
- Normally, the serial console device is a UART and RS-232 interface.
- However, if <code>CONFIG_USBDEV</code> is defined, then a USB serial device may, instead, be used if the one of the following are defined:
- </p>
- <ul>
- <li>
- <code>CONFIG_PL2303</code> and <code>CONFIG_PL2303_CONSOLE</code>.
- Sets up the Prolifics PL2303 emulation as a console device at <code>/dev/console</code>.
- </li>
- <li>
- <code>CONFIG_CDCACM</code> and <code>CONFIG_CDCACM_CONSOLE</code>.
- Sets up the CDC/ACM serial device as a console device at <code>/dev/console</code>.
- </li>
- <li>
- <code>CONFIG_NSH_USBCONSOLE</code>.
- If defined, then an arbitrary USB device may be used to as the NSH console.
- In this case, <code>CONFIG_NSH_USBCONDEV</code> must be defined to indicate which USB device to use as the console.
- The advantage of using a device other that <code>/dev/console</code> is that normal debug output can then use <code>/dev/console</code> while NSH uses <code>CONFIG_NSH_USBCONDEV</code>.
- <p>
- <code>CONFIG_NSH_USBCONDEV</code>.
- If <code>CONFIG_NSH_USBCONSOLE</code> is set to 'y', then <code>CONFIG_NSH_USBCONDEV</code> must also be set to select the USB device used to support the NSH console.
- This should be set to the quoted name of a readable/write-able USB driver such as: <code>CONFIG_NSH_USBCONDEV="/dev/ttyACM0"</code>.
- </p>
- </li>
- </ul>
- <p>
- If there are more than one USB slots, then a USB device minor number may also need to be provided:
- </p>
- <ul>
- <li>
- <code>CONFIG_NSH_UBSDEV_MINOR</code>.
- The minor device number of the USB device. Default: 0
- </li>
- </ul>
- <p>
- If USB tracing is enabled (<code>CONFIG_USBDEV_TRACE</code>), then NSH will initialize USB tracing as requested by the following.
- Default: Only USB errors are traced.
- </p>
- <ul>
- <li>
- <code>CONFIG_NSH_USBDEV_TRACEINIT</code>.
- Show initialization events
- </li>
- <li>
- <code>CONFIG_NSH_USBDEV_TRACECLASS</code>.
- Show class driver events
- </li>
- <li>
- <code>CONFIG_NSH_USBDEV_TRACETRANSFERS</code>.
- Show data transfer events
- </li>
- <li>
- <code>CONFIG_NSH_USBDEV_TRACECONTROLLER</code>.
- Show controller events
- <li>
- <code>CONFIG_NSH_USBDEV_TRACEINTERRUPTS</code>.
- Show interrupt-related events.
- </li>
- </ul>
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_ALTCONDEV</code></b> and <b><code>CONFIG_NSH_CONDEV</code></b></td>
- <td>
- If <code>CONFIG_NSH_CONSOLE</code> is set to <i>y</i>, then <code>CONFIG_NSH_ALTCONDEV</code>
- may also be selected to enable use of an alternate character device to support the NSH console.
- If <code>CONFIG_NSH_ALTCONDEV</code> is selected, then <code>CONFIG_NSH_CONDEV</code> holds the quoted name of a readable/write-able character driver such as:
- <code>CONFIG_NSH_CONDEV="/dev/ttyS1"</code>.
- This is useful, for example, to separate the NSH command line from the system console
- when the system console is used to provide debug output.
- Default: <code>stdin</code> and <code>stdout</code> (probably "<code>/dev/console</code>")
- <ul><small>
- <li>
- <b>NOTE 1:</b>
- When any other device other than <code>/dev/console</code> is used for a user interface,
- (1) linefeeds (<code>\n</code>) will not be expanded to carriage return / linefeeds (<code>\r\n</code>).
- You will need to configure your terminal program to account for this.
- And (2) input is not automatically echoed so you will have to turn local echo on.
- </li>
- <li>
- <b>NOTE 2:</b>
- This option forces the console of all sessions to use NSH_CONDEV.
- Hence, this option only makes sense for a system that supports only a single session.
- This option is, in particular, incompatible with Telnet sessions because each Telnet session must use a different console device.
- </li>
- </small></ul>
- </td>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_TELNET</code></b></td>
- <td>
- If <code>CONFIG_NSH_TELNET</code> is set to <i>y</i>, then a TELNET
- server front-end is selected. When this option is provided,
- you may log into NuttX remotely using telnet in order to
- access NSH.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_ARCHINIT</code></b></td>
- <td>
- Set <code>CONFIG_NSH_ARCHINIT</code> if your board provides architecture
- specific initialization via the board-specific function <code>board_app_initialize()</code>.
- This function will be called early in NSH initialization to allow board logic to
- do such things as configure MMC/SD slots.
- </td>
- </tr>
-</table></center>
-
-<p>
- If Telnet is selected for the NSH console, then we must configure
- the resources used by the Telnet daemon and by the Telnet clients.
-</p>
-
-<center><table width="100%">
- <tr bgcolor="#e4e4e4">
- <th align="left" width="25%">Configuration</th>
- <th align="left">Description</th>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_TELNETD_PORT</code></b></td>
- <td>
- The telnet daemon will listen on this TCP port number for connections. Default: 23
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_TELNETD_DAEMONPRIO</code></b></td>
- <td>
- Priority of the Telnet daemon.
- Default: <code>SCHED_PRIORITY_DEFAULT</code>
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_TELNETD_DAEMONSTACKSIZE</code></b></td>
- <td>
- Stack size allocated for the
- Telnet daemon. Default: 2048
- </td>
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_TELNETD_CLIENTPRIO</code></b></td>
- <td>
- Priority of the Telnet client.
- Default: <code>SCHED_PRIORITY_DEFAULT</code>
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_TELNETD_CLIENTSTACKSIZE</code></b></td>
- <td>
- Stack size allocated for the Telnet client. Default: 2048
- </td>
- </tr>
-</table></center>
-
-<p>
- One or both of <code>CONFIG_NSH_CONSOLE</code> and <code>CONFIG_NSH_TELNET</code>
- must be defined. If <code>CONFIG_NSH_TELNET</code> is selected, then there some
- other configuration settings that apply:
-</p>
-
-<center><table width="100%">
- <tr bgcolor="#e4e4e4">
- <th align="left" width="25%">Configuration</th>
- <th align="left">Description</th>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NET=y</code></b></td>
- <td>
- Of course, networking must be enabled.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSOCKET_DESCRIPTORS</code></b></td>
- <td>
- And, of course, you must allocate some socket descriptors.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NET_TCP=y</code></b></td>
- <td>
- TCP/IP support is required for telnet (as well as various other TCP-related configuration settings).
- </td>
- </tr>
- <td valign="top"><b><code>CONFIG_NSH_IOBUFFER_SIZE</code></b></td>
- <td>
- Determines the size of the I/O buffer to use for sending/
- receiving TELNET commands/responses
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_DHCPC</code></b></td>
- <td>
- Obtain the IP address via DHCP.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_IPADDR</code></b></td>
- <td>
- If <code>CONFIG_NSH_DHCPC</code> is NOT set, then the static IP
- address must be provided.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_DRIPADDR</code></b></td>
- <td>
- Default router IP address
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_NETMASK</code></b></td>
- <td>
- Network mask
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_NOMAC</code></b></td>
- <td>
- Set if your Ethernet hardware has no built-in MAC address.
- If set, a bogus MAC will be assigned.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_MAX_ROUNDTRIP</code></b></td>
- <td>
- This is the maximum round trip for a response to a ICMP ECHO request.
- It is in units of deciseconds. The default is 20 (2 seconds).
- </td>
- </tr>
-</table></center>
-
-<p>
- If you use DHCPC, then some special configuration network options are
- required. These include:
-</p>
-
-<center><table width="100%">
- <tr bgcolor="#e4e4e4">
- <th align="left" width="25%">Configuration</th>
- <th align="left">Description</th>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NET=y</code></b></td>
- <td>
- Of course, networking must be enabled.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSOCKET_DESCRIPTORS</code></b></td>
- <td>
- And, of course, you must allocate some socket descriptors.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NET_UDP=y</code></b></td>
- <td>
- UDP support is required for DHCP (as well as various other UDP-related configuration settings).
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NET_BROADCAST=y</code></b></td>
- <td>
- UDP broadcast support is needed.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NET_ETH_PKTSIZE=650</code></b> (or larger)</td>
- <td>
- Per RFC2131 (p. 9), the DHCP client must be prepared to receive DHCP messages of up to
- 576 bytes (excluding Ethernet, IP, or UDP headers and FCS).
- NOTE: Note that the actual MTU setting will depend upon the specific link protocol.
- Here Ethernet is indicated.
- </td>
- </tr>
-</table></center>
-
-<p>
- If <code>CONFIG_NSH_ROMFSETC</code> is selected, then the following additional
- configuration setting apply:
-</p>
-
-<center><table width="100%">
- <tr bgcolor="#e4e4e4">
- <th align="left" width="25%">Configuration</th>
- <th align="left">Description</th>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_ARCHROMFS</code></b></td>
- <td>
- May be defined to specify an alternative ROMFS image that can be found at <code>boards/<arch>/<chip>/<board>/include/nsh_romfsimg.h</code>.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_ROMFSMOUNTPT</code></b></td>
- <td>
- The default mountpoint for the ROMFS volume is <code>"/etc"</code>, but that
- can be changed with this setting. This must be a absolute path
- beginning with '<code>/</code>' and enclosed in quotes.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_INITSCRIPT</code></b></td>
- <td>
- This is the relative path to the startup script within the mountpoint.
- The default is <code>"init.d/rcS"</code>. This is a relative path and must not
- start with '<code>/</code>' but must be enclosed in quotes.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_ROMFSDEVNO</code></b></td>
- <td>
- This is the minor number of the ROMFS block device. The default is
- '<code>0</code>' corresponding to <code>/dev/ram0</code>.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_ROMFSSECTSIZE</code></b></td>
- <td>
- This is the sector size to use with the ROMFS volume. Since the
- default volume is very small, this defaults to 64 but should be
- increased if the ROMFS volume were to be become large. Any value
- selected must be a power of 2.
- </td>
- </tr>
-</table></center>
-
-<p>
- When the default <code>rcS</code> file used when <code>CONFIG_NSH_ROMFSETC</code> is
- selected, it will mount a FAT FS under <code>/tmp</code>. The following selections
- describe that FAT FS.
-</p>
-
-<center><table width="100%">
- <tr bgcolor="#e4e4e4">
- <th align="left" width="25%">Configuration</th>
- <th align="left">Description</th>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_FATDEVNO</code></b></td>
- <td>
- This is the minor number of the FAT FS block device. The default is
- '<code>1</code>' corresponding to <code>/dev/ram1</code>.
- </td>
- </tr>
- <tr>
- <td valign="top"><b><code>CONFIG_NSH_FATSECTSIZE</code></b></td>
- <td>
- This is the sector size use with the FAT FS. Default is 512.
- </td>
- </tr>
-</table></center>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="customizingnsh"><h1>5.0 Customizing the NuttShell</h1></a>
- </td>
- </tr>
-</table>
-
-<p>
- <b>Overview.</b>
- The NuttShell (NSH) is a simple shell application that may be used with NuttX.
- It supports a variety of commands and is (very) loosely based on the Bash shell and the common utilities used with Bash shell programming.
- The paragraphs in this appendix will focus on customizing NSH: Adding new commands, changing the initialization sequence, etc.
-</p>
-
-<table width ="100%">
- <tr bgcolor="#e4e4e4">
- <td>
- <a name="custonshlib"><h2>5.1 The NSH Library and NSH Initialization</h2></a>
- </td>
- </tr>
-</table>
-
-<p>
- <b>Overview.</b>
- NSH is implemented as a library that can be found at <code>apps/nshlib</code>.
- As a library, it can be custom built into any application that follows the NSH initialization sequence described below.
- As an example, the code at <code>apps/examples/nsh/nsh_main.c</code> illustrates how to start NSH and the logic there was intended to be incorporated into your own custom code.
- Although code was generated simply as an example, in the end most people just use this example code as their application <code>main()</code> function.
- That initialization performed by that example is discussed in the following paragraphs.
-</p>
-
-<h3>5.1.1 NSH Initialization sequence</h3>
-
-<p>
- The NSH start-up sequence is very simple.
- As an example, the code at <code>apps/system/nsh/nsh_main.c</code> illustrates how to start NSH.
- It simple does the following:
-</p>
-
-<ol>
- <li>
- <p>
- This function calls <code>nsh_initialize()</code> which initializes the NSH library.
- <code>nsh_initialize()</code> is described in more detail below.
- </p>
- <li>
- <p>
... 29417 lines suppressed ...