You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@nuttx.apache.org by gi...@apache.org on 2020/08/25 03:02:19 UTC
[incubator-nuttx-website] branch asf-site updated: Publishing web:
9462e9ee2bcf356dcf5958d35d8e72cb930f9f72 docs:
407667480a99f40bb9c9158719705a3463e096cd
This is an automated email from the ASF dual-hosted git repository.
github-bot pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx-website.git
The following commit(s) were added to refs/heads/asf-site by this push:
new c54f3f1 Publishing web: 9462e9ee2bcf356dcf5958d35d8e72cb930f9f72 docs: 407667480a99f40bb9c9158719705a3463e096cd
c54f3f1 is described below
commit c54f3f14ba5fa6a42a07fcce9f84e152a6b5bf0f
Author: Brennan <ba...@brennanashton.com>
AuthorDate: Tue Aug 25 03:01:52 2020 +0000
Publishing web: 9462e9ee2bcf356dcf5958d35d8e72cb930f9f72 docs: 407667480a99f40bb9c9158719705a3463e096cd
---
content/community-members/index.html | 1 +
content/community/index.html | 1 +
content/docs/latest/.buildinfo | 4 +
content/docs/latest/_images/NXOrganization.gif | Bin 0 -> 34880 bytes
content/docs/latest/_images/NuttXScreenShot.jpg | Bin 0 -> 5872 bytes
content/docs/latest/_images/pm.png | Bin 0 -> 32504 bytes
.../latest/_sources/applications/index.rst.txt | 10 +
content/docs/latest/_sources/boards/index.rst.txt | 14 +
.../docs/latest/_sources/components/binfmt.rst.txt | 372 +
.../_sources/components/drivers/index.rst.txt | 941 ++
.../latest/_sources/components/filesystem.rst.txt | 43 +
.../docs/latest/_sources/components/index.rst.txt | 20 +
.../latest/_sources/components/nsh/builtin.rst.txt | 204 +
.../_sources/components/nsh/commands.rst.txt | 1692 +++
.../latest/_sources/components/nsh/config.rst.txt | 486 +
.../_sources/components/nsh/customizing.rst.txt | 213 +
.../latest/_sources/components/nsh/index.rst.txt | 19 +
.../_sources/components/nsh/installation.rst.txt | 187 +
.../latest/_sources/components/nsh/login.rst.txt | 261 +
.../latest/_sources/components/nsh/nsh.rst.txt | 361 +
.../docs/latest/_sources/components/nxflat.rst.txt | 469 +
.../components/nxgraphics/appendix.rst.txt | 657 ++
.../_sources/components/nxgraphics/index.rst.txt | 174 +
.../_sources/components/nxgraphics/nx.rst.txt | 740 ++
.../components/nxgraphics/nxcursor.rst.txt | 50 +
.../_sources/components/nxgraphics/nxfonts.rst.txt | 127 +
.../_sources/components/nxgraphics/nxgl.rst.txt | 259 +
.../_sources/components/nxgraphics/nxtk.rst.txt | 653 ++
.../_sources/components/nxgraphics/sample.rst.txt | 30 +
.../latest/_sources/components/nxwidgets.rst.txt | 59 +
.../docs/latest/_sources/components/paging.rst.txt | 423 +
.../docs/latest/_sources/components/power.rst.txt | 241 +
.../latest/_sources/components/socketcan.rst.txt | 66 +
.../docs/latest/_sources/components/syslog.rst.txt | 511 +
.../_sources/contributing/coding_style.rst.txt | 2656 +++++
.../_sources/contributing/documentation.rst.txt | 180 +
.../latest/_sources/contributing/index.rst.txt | 13 +
.../latest/_sources/contributing/workflow.rst.txt | 42 +
content/docs/latest/_sources/glossary.rst.txt | 368 +
content/docs/latest/_sources/guides/index.rst.txt | 9 +
content/docs/latest/_sources/guides/nfs.rst.txt | 285 +
.../docs/latest/_sources/guides/usbtrace.rst.txt | 214 +
content/docs/latest/_sources/index.rst.txt | 34 +
.../latest/_sources/introduction/about.rst.txt | 285 +
.../_sources/introduction/detailed_support.rst.txt | 3191 ++++++
.../introduction/development_environments.rst.txt | 155 +
.../latest/_sources/introduction/index.rst.txt | 17 +
.../latest/_sources/introduction/licensing.rst.txt | 11 +
.../latest/_sources/introduction/resources.rst.txt | 23 +
.../introduction/supported_platforms.rst.txt | 349 +
.../_sources/introduction/trademarks.rst.txt | 32 +
.../_sources/quickstart/config_build.rst.txt | 131 +
.../docs/latest/_sources/quickstart/index.rst.txt | 16 +
.../_sources/quickstart/organization.rst.txt | 501 +
.../docs/latest/_sources/reference/index.rst.txt | 14 +
.../latest/_sources/reference/os/addrenv.rst.txt | 305 +
.../latest/_sources/reference/os/app_vs_os.rst.txt | 103 +
.../docs/latest/_sources/reference/os/arch.rst.txt | 329 +
.../latest/_sources/reference/os/board.rst.txt | 74 +
.../latest/_sources/reference/os/boardctl.rst.txt | 40 +
.../_sources/reference/os/conventions.rst.txt | 101 +
.../latest/_sources/reference/os/index.rst.txt | 25 +
.../docs/latest/_sources/reference/os/iob.rst.txt | 310 +
.../docs/latest/_sources/reference/os/led.rst.txt | 122 +
.../latest/_sources/reference/os/nuttx.rst.txt | 50 +
.../latest/_sources/reference/os/paging.rst.txt | 13 +
.../docs/latest/_sources/reference/os/shm.rst.txt | 38 +
.../docs/latest/_sources/reference/os/smp.rst.txt | 99 +
.../_sources/reference/os/time_clock.rst.txt | 593 +
.../latest/_sources/reference/os/wqueue.rst.txt | 307 +
.../reference/user/01_task_control.rst.txt | 887 ++
.../reference/user/02_task_scheduling.rst.txt | 180 +
.../reference/user/03_task_control.rst.txt | 458 +
.../reference/user/04_message_queue.rst.txt | 375 +
.../reference/user/05_counting_semaphore.rst.txt | 455 +
.../reference/user/06_clocks_timers.rst.txt | 360 +
.../_sources/reference/user/07_signals.rst.txt | 514 +
.../_sources/reference/user/08_pthread.rst.txt | 1710 +++
.../_sources/reference/user/09_env_vars.rst.txt | 95 +
.../_sources/reference/user/10_filesystem.rst.txt | 573 +
.../_sources/reference/user/11_network.rst.txt | 417 +
.../reference/user/12_shared_memory.rst.txt | 202 +
.../latest/_sources/reference/user/index.rst.txt | 28 +
.../_sources/reference/user/structures.rst.txt | 168 +
.../docs/latest/_sources/releases/index.rst.txt | 6 +
content/docs/latest/_sources/substitutions.rst.txt | 5 +
content/docs/latest/_static/NuttX.png | Bin 0 -> 4961 bytes
content/docs/latest/_static/NuttX320.png | Bin 0 -> 4151 bytes
content/docs/latest/_static/basic.css | 855 ++
content/docs/latest/_static/css/badge_only.css | 1 +
.../latest/_static/css/fonts/Roboto-Slab-Bold.woff | Bin 0 -> 87624 bytes
.../_static/css/fonts/Roboto-Slab-Bold.woff2 | Bin 0 -> 67312 bytes
.../_static/css/fonts/Roboto-Slab-Regular.woff | Bin 0 -> 86288 bytes
.../_static/css/fonts/Roboto-Slab-Regular.woff2 | Bin 0 -> 66444 bytes
.../_static/css/fonts/fontawesome-webfont.eot | Bin 0 -> 165742 bytes
.../_static/css/fonts/fontawesome-webfont.svg | 2671 +++++
.../_static/css/fonts/fontawesome-webfont.ttf | Bin 0 -> 165548 bytes
.../_static/css/fonts/fontawesome-webfont.woff | Bin 0 -> 98024 bytes
.../_static/css/fonts/fontawesome-webfont.woff2 | Bin 0 -> 77160 bytes
.../latest/_static/css/fonts/lato-bold-italic.woff | Bin 0 -> 323344 bytes
.../_static/css/fonts/lato-bold-italic.woff2 | Bin 0 -> 193308 bytes
.../docs/latest/_static/css/fonts/lato-bold.woff | Bin 0 -> 309728 bytes
.../docs/latest/_static/css/fonts/lato-bold.woff2 | Bin 0 -> 184912 bytes
.../_static/css/fonts/lato-normal-italic.woff | Bin 0 -> 328412 bytes
.../_static/css/fonts/lato-normal-italic.woff2 | Bin 0 -> 195704 bytes
.../docs/latest/_static/css/fonts/lato-normal.woff | Bin 0 -> 309192 bytes
.../latest/_static/css/fonts/lato-normal.woff2 | Bin 0 -> 182708 bytes
content/docs/latest/_static/css/theme.css | 4 +
content/docs/latest/_static/custom.css | 60 +
content/docs/latest/_static/doctools.js | 315 +
.../docs/latest/_static/documentation_options.js | 12 +
content/docs/latest/_static/favicon.ico | Bin 0 -> 4286 bytes
content/docs/latest/_static/file.png | Bin 0 -> 286 bytes
content/docs/latest/_static/fonts/FontAwesome.otf | Bin 0 -> 134808 bytes
.../docs/latest/_static/fonts/Lato/lato-bold.eot | Bin 0 -> 256056 bytes
.../docs/latest/_static/fonts/Lato/lato-bold.ttf | Bin 0 -> 600856 bytes
.../docs/latest/_static/fonts/Lato/lato-bold.woff | Bin 0 -> 309728 bytes
.../docs/latest/_static/fonts/Lato/lato-bold.woff2 | Bin 0 -> 184912 bytes
.../latest/_static/fonts/Lato/lato-bolditalic.eot | Bin 0 -> 266158 bytes
.../latest/_static/fonts/Lato/lato-bolditalic.ttf | Bin 0 -> 622572 bytes
.../latest/_static/fonts/Lato/lato-bolditalic.woff | Bin 0 -> 323344 bytes
.../_static/fonts/Lato/lato-bolditalic.woff2 | Bin 0 -> 193308 bytes
.../docs/latest/_static/fonts/Lato/lato-italic.eot | Bin 0 -> 268604 bytes
.../docs/latest/_static/fonts/Lato/lato-italic.ttf | Bin 0 -> 639388 bytes
.../latest/_static/fonts/Lato/lato-italic.woff | Bin 0 -> 328412 bytes
.../latest/_static/fonts/Lato/lato-italic.woff2 | Bin 0 -> 195704 bytes
.../latest/_static/fonts/Lato/lato-regular.eot | Bin 0 -> 253461 bytes
.../latest/_static/fonts/Lato/lato-regular.ttf | Bin 0 -> 607720 bytes
.../latest/_static/fonts/Lato/lato-regular.woff | Bin 0 -> 309192 bytes
.../latest/_static/fonts/Lato/lato-regular.woff2 | Bin 0 -> 182708 bytes
.../latest/_static/fonts/Roboto-Slab-Bold.woff | Bin 0 -> 87624 bytes
.../latest/_static/fonts/Roboto-Slab-Bold.woff2 | Bin 0 -> 67312 bytes
.../latest/_static/fonts/Roboto-Slab-Light.woff | Bin 0 -> 88600 bytes
.../latest/_static/fonts/Roboto-Slab-Light.woff2 | Bin 0 -> 67884 bytes
.../latest/_static/fonts/Roboto-Slab-Regular.woff | Bin 0 -> 86288 bytes
.../latest/_static/fonts/Roboto-Slab-Regular.woff2 | Bin 0 -> 66444 bytes
.../latest/_static/fonts/Roboto-Slab-Thin.woff | Bin 0 -> 87452 bytes
.../latest/_static/fonts/Roboto-Slab-Thin.woff2 | Bin 0 -> 66328 bytes
.../fonts/RobotoSlab/roboto-slab-v7-bold.eot | Bin 0 -> 79520 bytes
.../fonts/RobotoSlab/roboto-slab-v7-bold.ttf | Bin 0 -> 170616 bytes
.../fonts/RobotoSlab/roboto-slab-v7-bold.woff | Bin 0 -> 87624 bytes
.../fonts/RobotoSlab/roboto-slab-v7-bold.woff2 | Bin 0 -> 67312 bytes
.../fonts/RobotoSlab/roboto-slab-v7-regular.eot | Bin 0 -> 78331 bytes
.../fonts/RobotoSlab/roboto-slab-v7-regular.ttf | Bin 0 -> 169064 bytes
.../fonts/RobotoSlab/roboto-slab-v7-regular.woff | Bin 0 -> 86288 bytes
.../fonts/RobotoSlab/roboto-slab-v7-regular.woff2 | Bin 0 -> 66444 bytes
.../latest/_static/fonts/fontawesome-webfont.eot | Bin 0 -> 165742 bytes
.../latest/_static/fonts/fontawesome-webfont.svg | 2671 +++++
.../latest/_static/fonts/fontawesome-webfont.ttf | Bin 0 -> 165548 bytes
.../latest/_static/fonts/fontawesome-webfont.woff | Bin 0 -> 98024 bytes
.../latest/_static/fonts/fontawesome-webfont.woff2 | Bin 0 -> 77160 bytes
.../latest/_static/fonts/lato-bold-italic.woff | Bin 0 -> 323344 bytes
.../latest/_static/fonts/lato-bold-italic.woff2 | Bin 0 -> 193308 bytes
content/docs/latest/_static/fonts/lato-bold.woff | Bin 0 -> 309728 bytes
content/docs/latest/_static/fonts/lato-bold.woff2 | Bin 0 -> 184912 bytes
.../latest/_static/fonts/lato-normal-italic.woff | Bin 0 -> 328412 bytes
.../latest/_static/fonts/lato-normal-italic.woff2 | Bin 0 -> 195704 bytes
content/docs/latest/_static/fonts/lato-normal.woff | Bin 0 -> 309192 bytes
.../docs/latest/_static/fonts/lato-normal.woff2 | Bin 0 -> 182708 bytes
content/docs/latest/_static/jquery-3.5.1.js | 10872 +++++++++++++++++++
content/docs/latest/_static/jquery.js | 2 +
content/docs/latest/_static/js/badge_only.js | 1 +
.../latest/_static/js/html5shiv-printshiv.min.js | 4 +
content/docs/latest/_static/js/html5shiv.min.js | 4 +
content/docs/latest/_static/js/modernizr.min.js | 4 +
content/docs/latest/_static/js/theme.js | 1 +
content/docs/latest/_static/language_data.js | 297 +
content/docs/latest/_static/minus.png | Bin 0 -> 90 bytes
content/docs/latest/_static/plus.png | Bin 0 -> 90 bytes
content/docs/latest/_static/pygments.css | 69 +
content/docs/latest/_static/searchtools.js | 515 +
content/docs/latest/_static/underscore-1.3.1.js | 999 ++
content/docs/latest/_static/underscore.js | 31 +
content/docs/latest/applications/index.html | 241 +
content/docs/latest/boards/index.html | 246 +
content/docs/latest/components/binfmt.html | 688 ++
content/docs/latest/components/drivers/index.html | 1169 ++
content/docs/latest/components/filesystem.html | 284 +
content/docs/latest/components/index.html | 314 +
content/docs/latest/components/nsh/builtin.html | 468 +
content/docs/latest/components/nsh/commands.html | 1976 ++++
content/docs/latest/components/nsh/config.html | 1149 ++
.../docs/latest/components/nsh/customizing.html | 451 +
content/docs/latest/components/nsh/index.html | 309 +
.../docs/latest/components/nsh/installation.html | 449 +
content/docs/latest/components/nsh/login.html | 532 +
content/docs/latest/components/nsh/nsh.html | 676 ++
content/docs/latest/components/nxflat.html | 747 ++
.../latest/components/nxgraphics/appendix.html | 1231 +++
.../docs/latest/components/nxgraphics/index.html | 467 +
content/docs/latest/components/nxgraphics/nx.html | 1248 +++
.../latest/components/nxgraphics/nxcursor.html | 332 +
.../docs/latest/components/nxgraphics/nxfonts.html | 427 +
.../docs/latest/components/nxgraphics/nxgl.html | 561 +
.../docs/latest/components/nxgraphics/nxtk.html | 1024 ++
.../docs/latest/components/nxgraphics/sample.html | 289 +
content/docs/latest/components/nxwidgets.html | 304 +
content/docs/latest/components/paging.html | 733 ++
content/docs/latest/components/power.html | 540 +
content/docs/latest/components/socketcan.html | 315 +
content/docs/latest/components/syslog.html | 711 ++
content/docs/latest/contributing/coding_style.html | 2903 +++++
.../docs/latest/contributing/documentation.html | 423 +
content/docs/latest/contributing/index.html | 264 +
content/docs/latest/contributing/workflow.html | 281 +
content/docs/latest/genindex.html | 1641 +++
content/docs/latest/glossary.html | 477 +
content/docs/latest/guides/index.html | 255 +
content/docs/latest/guides/nfs.html | 506 +
content/docs/latest/guides/usbtrace.html | 629 ++
content/docs/latest/index.html | 302 +
content/docs/latest/introduction/about.html | 548 +
.../docs/latest/introduction/detailed_support.html | 3277 ++++++
.../introduction/development_environments.html | 394 +
content/docs/latest/introduction/index.html | 256 +
content/docs/latest/introduction/licensing.html | 737 ++
content/docs/latest/introduction/resources.html | 272 +
.../latest/introduction/supported_platforms.html | 639 ++
content/docs/latest/introduction/trademarks.html | 277 +
content/docs/latest/objects.inv | Bin 0 -> 17663 bytes
content/docs/latest/quickstart/config_build.html | 360 +
content/docs/latest/quickstart/index.html | 251 +
content/docs/latest/quickstart/organization.html | 727 ++
content/docs/latest/reference/index.html | 251 +
content/docs/latest/reference/os/addrenv.html | 687 ++
content/docs/latest/reference/os/app_vs_os.html | 352 +
content/docs/latest/reference/os/arch.html | 646 ++
content/docs/latest/reference/os/board.html | 327 +
content/docs/latest/reference/os/boardctl.html | 300 +
content/docs/latest/reference/os/conventions.html | 351 +
content/docs/latest/reference/os/index.html | 320 +
content/docs/latest/reference/os/iob.html | 615 ++
content/docs/latest/reference/os/led.html | 388 +
content/docs/latest/reference/os/nuttx.html | 314 +
content/docs/latest/reference/os/paging.html | 268 +
content/docs/latest/reference/os/shm.html | 307 +
content/docs/latest/reference/os/smp.html | 384 +
content/docs/latest/reference/os/time_clock.html | 887 ++
content/docs/latest/reference/os/wqueue.html | 602 +
.../latest/reference/user/01_task_control.html | 1304 +++
.../latest/reference/user/02_task_scheduling.html | 505 +
.../latest/reference/user/03_task_control.html | 777 ++
.../latest/reference/user/04_message_queue.html | 706 ++
.../reference/user/05_counting_semaphore.html | 802 ++
.../latest/reference/user/06_clocks_timers.html | 758 ++
content/docs/latest/reference/user/07_signals.html | 934 ++
content/docs/latest/reference/user/08_pthread.html | 1928 ++++
.../docs/latest/reference/user/09_env_vars.html | 394 +
.../docs/latest/reference/user/10_filesystem.html | 933 ++
content/docs/latest/reference/user/11_network.html | 678 ++
.../latest/reference/user/12_shared_memory.html | 493 +
content/docs/latest/reference/user/index.html | 290 +
content/docs/latest/reference/user/structures.html | 473 +
content/docs/latest/releases/index.html | 240 +
content/docs/latest/search.html | 248 +
content/docs/latest/searchindex.js | 1 +
content/docs/latest/substitutions.html | 230 +
content/download/index.html | 1 +
content/feed.xml | 4 +-
content/history/index.html | 1 +
content/index.html | 3 +-
content/publish.sh | 14 +-
content/releases/7.13/index.html | 1 +
content/releases/7.14/index.html | 1 +
content/releases/7.15/index.html | 1 +
content/releases/7.16/index.html | 1 +
content/releases/7.17/index.html | 1 +
content/releases/7.18/index.html | 1 +
content/releases/7.19/index.html | 1 +
content/releases/7.20/index.html | 1 +
content/releases/7.21/index.html | 1 +
content/releases/7.22/index.html | 1 +
content/releases/7.23/index.html | 1 +
content/releases/7.24/index.html | 1 +
content/releases/7.25/index.html | 1 +
content/releases/7.26/index.html | 1 +
content/releases/7.27/index.html | 1 +
content/releases/7.28/index.html | 1 +
content/releases/7.29/index.html | 1 +
content/releases/7.30/index.html | 1 +
content/releases/7.31/index.html | 1 +
content/releases/8.1/index.html | 1 +
content/releases/8.2/index.html | 1 +
content/releases/9.0.0/index.html | 1 +
content/releases/9.1.0/index.html | 1 +
285 files changed, 98177 insertions(+), 6 deletions(-)
diff --git a/content/community-members/index.html b/content/community-members/index.html
index 314bce6..ba937a7 100644
--- a/content/community-members/index.html
+++ b/content/community-members/index.html
@@ -55,6 +55,7 @@
<li><a href="/community-members">Who we are</a></li>
</ul>
</li>
+ <li><a href="/docs/latest">Documentation</a></li>
<li><a href="https://github.com/apache/incubator-nuttx">GitHub</a></li>
<li id="apache">
<a href="#" data-toggle="dropdown" class="dropdown-toggle">Apache<b class="caret"></b></a>
diff --git a/content/community/index.html b/content/community/index.html
index afef672..2ecda69 100644
--- a/content/community/index.html
+++ b/content/community/index.html
@@ -55,6 +55,7 @@
<li><a href="/community-members">Who we are</a></li>
</ul>
</li>
+ <li><a href="/docs/latest">Documentation</a></li>
<li><a href="https://github.com/apache/incubator-nuttx">GitHub</a></li>
<li id="apache">
<a href="#" data-toggle="dropdown" class="dropdown-toggle">Apache<b class="caret"></b></a>
diff --git a/content/docs/latest/.buildinfo b/content/docs/latest/.buildinfo
new file mode 100644
index 0000000..83fc9fd
--- /dev/null
+++ b/content/docs/latest/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 7b84be7f3b7b52e0e2a3ceb6a0703303
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/content/docs/latest/_images/NXOrganization.gif b/content/docs/latest/_images/NXOrganization.gif
new file mode 100644
index 0000000..6bae8e5
Binary files /dev/null and b/content/docs/latest/_images/NXOrganization.gif differ
diff --git a/content/docs/latest/_images/NuttXScreenShot.jpg b/content/docs/latest/_images/NuttXScreenShot.jpg
new file mode 100644
index 0000000..f5a9dc1
Binary files /dev/null and b/content/docs/latest/_images/NuttXScreenShot.jpg differ
diff --git a/content/docs/latest/_images/pm.png b/content/docs/latest/_images/pm.png
new file mode 100644
index 0000000..d84d864
Binary files /dev/null and b/content/docs/latest/_images/pm.png differ
diff --git a/content/docs/latest/_sources/applications/index.rst.txt b/content/docs/latest/_sources/applications/index.rst.txt
new file mode 100644
index 0000000..a718161
--- /dev/null
+++ b/content/docs/latest/_sources/applications/index.rst.txt
@@ -0,0 +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
+============
+
+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/content/docs/latest/_sources/boards/index.rst.txt b/content/docs/latest/_sources/boards/index.rst.txt
new file mode 100644
index 0000000..fa73bd1
--- /dev/null
+++ b/content/docs/latest/_sources/boards/index.rst.txt
@@ -0,0 +1,14 @@
+.. 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/content/docs/latest/_sources/components/binfmt.rst.txt b/content/docs/latest/_sources/components/binfmt.rst.txt
new file mode 100644
index 0000000..1267153
--- /dev/null
+++ b/content/docs/latest/_sources/components/binfmt.rst.txt
@@ -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/content/docs/latest/_sources/components/drivers/index.rst.txt b/content/docs/latest/_sources/components/drivers/index.rst.txt
new file mode 100644
index 0000000..28af15d
--- /dev/null
+++ b/content/docs/latest/_sources/components/drivers/index.rst.txt
@@ -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/content/docs/latest/_sources/components/filesystem.rst.txt b/content/docs/latest/_sources/components/filesystem.rst.txt
new file mode 100644
index 0000000..5794dc3
--- /dev/null
+++ b/content/docs/latest/_sources/components/filesystem.rst.txt
@@ -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/content/docs/latest/_sources/components/index.rst.txt b/content/docs/latest/_sources/components/index.rst.txt
new file mode 100644
index 0000000..57ac542
--- /dev/null
+++ b/content/docs/latest/_sources/components/index.rst.txt
@@ -0,0 +1,20 @@
+OS Components
+=============
+
+NuttX is very feature-rich RTOS and is thus composed of various different subsystems. The following sections explain how each of these main RTOS components work and can be used. For detailed documentation on the specific API used in this case, you can head to the :doc:`reference <../reference/index>`.
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Contents:
+
+ nsh/index.rst
+ power.rst
+ socketcan.rst
+ syslog.rst
+ binfmt.rst
+ drivers/index.rst
+ filesystem.rst
+ nxflat.rst
+ nxgraphics/index.rst
+ nxwidgets.rst
+ paging.rst
diff --git a/content/docs/latest/_sources/components/nsh/builtin.rst.txt b/content/docs/latest/_sources/components/nsh/builtin.rst.txt
new file mode 100644
index 0000000..338a539
--- /dev/null
+++ b/content/docs/latest/_sources/components/nsh/builtin.rst.txt
@@ -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/content/docs/latest/_sources/components/nsh/commands.rst.txt b/content/docs/latest/_sources/components/nsh/commands.rst.txt
new file mode 100644
index 0000000..3e125ee
--- /dev/null
+++ b/content/docs/latest/_sources/components/nsh/commands.rst.txt
@@ -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/content/docs/latest/_sources/components/nsh/config.rst.txt b/content/docs/latest/_sources/components/nsh/config.rst.txt
new file mode 100644
index 0000000..563f460
--- /dev/null
+++ b/content/docs/latest/_sources/components/nsh/config.rst.txt
@@ -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 following :ref:`table <nsh_vars_table>`.
+
+ ``CONFIG_NSH_QUOTE`` Enables back-slash quoting of certain characters within the
+ command. This option is useful for the case where an NSH script
+ is used to dynamically generate a new NSH script. In that case,
+ commands must be treated as simple text strings without
+ interpretation of any special characters. Special characters
+ such as ``$``, :literal:`\``, ``"``, and others must be
+ retained intact as part of the test string. This option is
+ currently only available is ``CONFIG_NSH_ARGCAT`` is also
+ selected.
+
+ ``CONFIG_NSH_NESTDEPTH`` The maximum number of nested ``if-then[-else]-fi`` <#conditional>`__
+ sequences that are permissible. Default: 3
+
+ ``CONFIG_NSH_DISABLESCRIPT`` This can be set to *y* to suppress support for scripting.
+ This setting disables the ```sh`` <#cmdsh>`__,
+ ```test`` <#cmdtest>`__, and ```[`` <#cmtest>`__ commands and
+ the ```if-then[-else]-fi`` <#conditional>`__
+ construct. This would only be set on systems where a minimal
+ footprint is a necessity and scripting is not.
+
+ ``CONFIG_NSH_DISABLE_ITEF`` If scripting is enabled, then then this option can be selected
+ to suppress support for ``if-then-else-fi`` sequences in
+ scripts. This would only be set on systems where some minimal
+ 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/content/docs/latest/_sources/components/nsh/customizing.rst.txt b/content/docs/latest/_sources/components/nsh/customizing.rst.txt
new file mode 100644
index 0000000..fcd293b
--- /dev/null
+++ b/content/docs/latest/_sources/components/nsh/customizing.rst.txt
@@ -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/content/docs/latest/_sources/components/nsh/index.rst.txt b/content/docs/latest/_sources/components/nsh/index.rst.txt
new file mode 100644
index 0000000..7f7a4ef
--- /dev/null
+++ b/content/docs/latest/_sources/components/nsh/index.rst.txt
@@ -0,0 +1,19 @@
+===============
+NuttShell (NSH)
+===============
+
+The NuttShell is a very complete shell system to be used in NuttX, similar to bash and other similar options. It supports a rich set of included commands, scripting and the ability to run your own applications as "builtin" (part of the same NuttX binary). NSH is implemented as an application where most of the functionality is part of the library called `nshlib`.
+
+As such, NSH is completely optional and can be disabled so that NuttX directly starts a given task instead of the main ``nsh`` application.
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Contents
+
+ nsh.rst
+ commands.rst
+ config.rst
+ customizing.rst
+ builtin.rst
+ installation.rst
+ login.rst
diff --git a/content/docs/latest/_sources/components/nsh/installation.rst.txt b/content/docs/latest/_sources/components/nsh/installation.rst.txt
new file mode 100644
index 0000000..60ed8e6
--- /dev/null
+++ b/content/docs/latest/_sources/components/nsh/installation.rst.txt
@@ -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/content/docs/latest/_sources/components/nsh/login.rst.txt b/content/docs/latest/_sources/components/nsh/login.rst.txt
new file mode 100644
index 0000000..76b2390
--- /dev/null
+++ b/content/docs/latest/_sources/components/nsh/login.rst.txt
@@ -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/content/docs/latest/_sources/components/nsh/nsh.rst.txt b/content/docs/latest/_sources/components/nsh/nsh.rst.txt
new file mode 100644
index 0000000..8984192
--- /dev/null
+++ b/content/docs/latest/_sources/components/nsh/nsh.rst.txt
@@ -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/content/docs/latest/_sources/components/nxflat.rst.txt b/content/docs/latest/_sources/components/nxflat.rst.txt
new file mode 100644
index 0000000..0a494e9
--- /dev/null
+++ b/content/docs/latest/_sources/components/nxflat.rst.txt
@@ -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/content/docs/latest/_sources/components/nxgraphics/appendix.rst.txt b/content/docs/latest/_sources/components/nxgraphics/appendix.rst.txt
new file mode 100644
index 0000000..4d51083
--- /dev/null
+++ b/content/docs/latest/_sources/components/nxgraphics/appendix.rst.txt
@@ -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.
+
+``CONFIG_NXTERM``:
+ Enables building of the NxTerm driver.
+
+NxTerm output text/graphics options:
+
+``CONFIG_NXTERM_BPP``:
+ Currently, NxTerm supports only a single pixel depth. This
+ configuration setting must be provided to support that single pixel
+ depth. Default: The smallest enabled pixel depth. (see
+ ``CONFIG_NX_DISABLE_*BPP``)
+``CONFIG_NXTERM_CURSORCHAR``:
+ The bitmap code to use as the cursor. Default '_'
+``CONFIG_NXTERM_MXCHARS``:
+ NxTerm needs to remember every character written to the console so
+ that it can redraw the window. This setting determines the size of
+ some internal memory allocations used to hold the character data.
+ Default: 128.
+``CONFIG_NXTERM_CACHESIZE``:
+ 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 ``CONFIG_NXTERM_CACHESIZE`` 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.
+
+ 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 ``CONFIG_NXTERM_CACHESIZE`` is something
+ that you should try. Alternatively, you can reduce the size of
+ ``CONFIG_MQ_MAXMSGSIZE`` which will force NxTerm task to pace the
+ server task. ``CONFIG_NXTERM_CACHESIZE`` should be larger than
+ ``CONFIG_MQ_MAXMSGSIZE`` in any event.
+
+``CONFIG_NXTERM_LINESEPARATION``:
+ This the space (in rows) between each row of test. Default: 0
+``CONFIG_NXTERM_NOWRAP``:
+ By default, lines will wrap when the test reaches the right hand side
+ of the window. This setting can be defining to change this behavior
+ so that the text is simply truncated until a new line is encountered.
+
+NxTerm input options:
+
+``CONFIG_NXTERM_NXKBDIN``:
+ Take input from the NX keyboard input callback. By default, keyboard
+ input is taken from stdin (``/dev/console``). If this option is set,
+ then the interface\ ``nxterm_kdbin()`` is enabled. That interface may
+ be driven by window callback functions so that keyboard input *only*
+ goes to the top window.
+``CONFIG_NXTERM_KBDBUFSIZE``:
+ If ``CONFIG_NXTERM_NXKBDIN`` is enabled, then this value may be used
+ to define the size of the per-window keyboard input buffer. Default:
+ 16
+``CONFIG_NXTERM_NPOLLWAITERS``:
+ The number of threads that can be waiting for read data available.
+ Default: 4
+
+Installing New Fonts
+====================
+
+**The BDF Font Converter**. There is a tool called *bdf-converter* in
+the directory ``tools/.``. The *bdf-converter* 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.
+
+ 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.
+
+**Font Installation Steps**, 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.
+
+#. Locate a font in BDF format. There are many good BDF bitmap fonts
+ bundled with X-11. See `this
+ link <http://www.cl.cam.ac.uk/~mgk25/ucs-fonts.html>`__, as an
+ example,
+
+#. Use the *bdf-converter* 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,
+ ``graphics/nxfonts/nxfonts_myfont.h``.
+
+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:
+``CONFIG_NXFONT_MYFONT``. Then you would need to:
+
+3. Define ``CONFIG_NXFONT_MYFONT=y`` in your NuttX configuration file.
+
+A font ID number has to be assigned for each new font. The font IDs are
+defined in the file ``include/nuttx/nx/nxfonts.h``. Those definitions
+have to be extended to support your new font. Look at how the font ID
+enabled by ``CONFIG_NXFONT_SANS23X27`` is defined and add an ID for
+yournew font in a similar fashion:
+
+4. ``include/nuttx/nx/nxfonts.h``. Add you new font as a possible
+ system default font:
+
+ .. code-block:: c
+
+ #if defined(CONFIG_NXFONT_SANS23X27)
+ # define NXFONT_DEFAULT FONTID_SANS23X27
+ #elif defined(CONFIG_NXFONT_MYFONT)
+ # define NXFONT_DEFAULT FONTID_MYFONT
+ #endif
+
+ Then define the actual font ID. Make sure that the font ID value is
+ unique:
+
+ .. code-block:: c
+
+ #if defined(CONFIG_NXFONT_SANS23X27)
+ # define NXFONT_DEFAULT FONTID_SANS23X27
+ #elif defined(CONFIG_NXFONT_MYFONT)
+ # define NXFONT_DEFAULT FONTID_MYFONT
+ #endif
+
+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:
+
+5. ``nuttx/graphics/Makefile``. This file needs logic to
+ auto-generate a C source file from the header file that you generated
+ with the *bdf-converter* program. Notice ``NXFONTS_FONTID=2``; this
+ must be set to the same font ID value that you defined in the
+ ``include/nuttx/nx/nxfonts.h`` file.
+
+ .. code-block:: makefile
+
+ genfontsources:
+ ifeq ($(CONFIG_NXFONT_SANS23X27),y)
+ @$(MAKE) -C nxfonts -f Makefile.sources 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
+
+6. ``nuttx/graphics/nxfonts/Make.defs``. Set the make variable
+ ``NXFSET_CSRCS``. ``NXFSET_CSRCS`` determines the name of the font C
+ file to build when ``NXFONTS_FONTID=2``:
+
+ .. code-block:: makefile
+
+ ifeq ($(CONFIG_NXFONT_SANS23X27),y)
+ NXFSET_CSRCS += nxfonts_bitmaps_sans23x27.c
+ endif
+ ifeq ($(CONFIG_NXFONT_MYFONT),y)
+ NXFSET_CSRCS += nxfonts_bitmaps_myfont.c
+ endif
+
+7. ``nuttx/graphics/nxfonts/Makefile.sources``. This is the Makefile
+ used in step 5 that will actually generate the font C file. So, given
+ your NXFONTS_FONTID=2, 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 ``nuttx/graphics/nxfonts/Make.defs``):
+
+ .. code-block:: makefile
+
+ 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
+
+8. ``graphics/nxfonts/nxfonts_bitmaps.c``. This is the file that
+ contains the generic font structures. It is used as a "template&qout;
+ file by ``nuttx/graphics/nxfonts/Makefile.sources``\ to create your
+ customized font data set at build time.
+
+ .. code-block:: c
+
+ #if NXFONTS_FONTID == 1
+ # include "nxfonts_sans23x27.h"
+ #elif NXFONTS_FONTID == 2
+ # include "nxfonts_myfont.h"
+ #else
+ # error "No font ID specified"
+ #endif
+
+ Where ``nxfonts_myfont.h`` is the NuttX font file that we generated
+ in step 2 using the *bdf-converter* tool.
+
+9. ``graphics/nxfonts/nxfonts_getfont.c``. 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
+ ```NXHANDLE nxf_getfonthandle(enum nx_fontid_e fontid)`` <#nxfgetfonthandle>`__.
+ Note that the lookup is based on the font ID that was defined in step
+ 4. The new font information needs to be added to data structures used
+ by that function:
+
+ .. code-block:: c
+
+ #ifdef CONFIG_NXFONT_SANS23X27
+ extern const struct nx_fontpackage_s g_sans23x27_package;
+ #endif
+ #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
+ };
+
+
+NX Test Coverage
+================
+
+``apps/examples/nx``. The primary test tool for debugging NX resides
+at ``apps/examples/nx``.
+
+**Building** ``apps/examples/nx``. NX testing was performed using
+``apps/examples/nx`` with the Linux/Cygwin-based NuttX simulator.
+Configuration files for building this test can be found in
+``boards/sim/sim/sim/configs/nx`` and
+``boards/sim/sim/sim/configs/nx11``. There are two alternative
+configurations for building the simulation:
+
+#. The configuration using the configuration file at
+ ``boards/sim/sim/sim/configs/nx/defconfig``. 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::
+
+ tools/configure.sh sim:nx
+ make
+ ./nuttx
+
+#. The preferred configuration is at
+ ``boards/sim/sim/sim/configs/nx11/defconfig``. 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::
+
+ tools/configure sim:nx11
+ make
+ ./nuttx
+
+ *Update:* The sim target has suffered some bit-rot over the years and
+ so the following caveats need to be added:
+
+ - The X target builds under recent Cygwin configurations, but does
+ not execute. (It fails inside of ``XOpenDisplay()``.
+
+ - The X target does not build under current (9.09) Ubuntu
+ distributions. I needed to make the following changes:
+
+ The build will also fail to locate the X header files unless you
+ install an X11 development package.
+
+ - 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.
+
+ NOTE: There is a workaround in this case: You can build for 32-bit
+ execution on a 64-bit machine by adding ``-m3`` to the ``CFLAGS``
+ and ``-m32 -m elf_i386`` to the ``LDFLAGS``. The
+ configuration/build system will do this for you; you simply need
+ to select ``CONFIG_SIM_M32=y`` in your configuration file.
+
+ - Refer to the readme file in sim configuration
+ `README.txt <https://bitbucket.org/nuttx/nuttx/src/master/boards/sim/sim/sim/README.txt>`__
+ file for additional information.
+
+**Test Coverage**. At present, ``apps/examples/nx``\ t only exercises a
+subset of NX; the remainder is essentially untested. The following table
+describes the testing performed on each NX API:
+
+NXGLIB API Test Coverage
+------------------------
+
+================================ ==================================== ========
+Function Special Setup/Notes Verified
+================================ ==================================== ========
+``nxgl_rgb2yuv()`` . NO
+``nxgl_yuv2rgb()`` . NO
+``nxgl_rectcopy()`` . YES
+``nxgl_rectoffset()`` . YES
+``nxgl_vectoradd()`` . YES
+``nxgl_vectorsubtract()`` . YES
+``nxgl_rectintersect()`` . YES
+``nxgl_rectunion()`` . YES
+``nxgl_nonintersecting()`` . YES
+``nxgl_rectoverlap()`` . YES
+``nxgl_rectinside()`` . YES
+``nxgl_rectsize()`` . YES
+``nxgl_nullrect()`` . YES
+``nxgl_runoffset()`` Verified by apps/examples/nxlines. YES
+``nxgl_runcopy()`` . NO
+``nxgl_trapoffset()`` Verified by apps/examples/nxlines. YES
+``nxgl_trapcopy()`` Verified by apps/examples/nxlines. YES
+``nxgl_colorcopy`` . YES
+``nxgl_splitline`` Verified using apps/examples/nxlines YES
+ 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.
+``nxgl_circlepts`` Verified by apps/examples/nxlines. YES
+``nxgl_circletraps`` Verified by apps/examples/nxlines. YES
+================================ ==================================== ========
+
+NX Server Callbacks Test Coverage
+---------------------------------
+
+============== ==================== ========
+Function Special Setup/Notes Verified
+============== ==================== ========
+``redraw()`` . YES
+``position()`` . YES
+``mousein()`` . YES
+``kbdin()`` . YES
+============== ==================== ========
+
+NX API Test Coverage
+--------------------
+
+========================= =============================================================== ========
+Function Special Setup/Notes Verified
+========================= =============================================================== ========
+``nx_runinstance()`` . YES
+``nx_connectinstance()`` . YES
+``nx_disconnect()`` . YES
+``nx_eventhandler()`` . YES
+``nx_eventnotify()`` This is not used in the current version of apps/examples/nx, NO
+ was tested in a previous version)
+``nx_openwindow()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES
+ ``<NuttX-Directory>/.config file``
+``nx_closewindow()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` YES
+ in the ``<NuttX-Directory>/.config`` file
+``nx_requestbkgd()`` Verified by ``apps/examples/nxtext`` and YES
+ ``apps/examples/nxhello``.
+``nx_releasebkgd()`` Verified by ``apps/examples/nxtext`` and YES
+ ``apps/examples/nxhello``.
+``nx_getposition()`` . NO
+``nx_setposition()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES
+ ``<NuttX-Directory>/.config`` file
+``nx_setsize()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES
+ ``<NuttX-Directory>/.config`` file
+``nx_raise()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES
+ ``<NuttX-Directory>/.config`` file
+``nx_lower()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES
+ ``<NuttX-Directory>/.config`` file
+``nx_modal()`` . NO
+``nx_setvisibility()`` Exercized using Twm4Nx YES, Informally
+``nx_ishidden()`` Exercized using Twm4Nx YES, Informally
+``nx_fill()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES
+ ``<NuttX-Directory>/.config`` file
+``nx_getrectangle()`` . YES
+``nx_filltrapezoid()`` Verified by ``apps/examples/nxlines``. YES
+``nx_drawline()`` by ``apps/examples/nxlines``. YES
+``nx_drawcircle()`` Verified by ``apps/examples/nxlines``. YES
+``nx_fillcircle()`` Verified by ``apps/examples/nxlines``. YES
+``nx_setbgcolor()`` . YES
+``nx_move()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES
+ ``<NuttX-Directory>/.config`` file
+``nx_bitmap()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES
+ ``<NuttX-Directory>/.config`` file.
+``nx_kbdin()`` . YES
+``nx_mousein()`` . YES
+========================= =============================================================== ========
+
+NXTK API Test Coverage
+----------------------
+
+============================ ========================= ========
+Function Special Setup/Notes Verified
+============================ ========================= ========
+``nxtk_openwindow()`` . YES
+``nxtk_closewindow()`` . YES
+``nxtk_getposition()`` . NO
+``nxtk_setposition()`` . YES
+``nxtk_setsize()`` . YES
+``nxtk_raise()`` . YES
+``nxtk_lower()`` . YES
+``nxtk_modal()`` . NO
+``nxtk_setvisibility()`` Exercized using Twm4Nx YES, informally
+``nxtk_ishidden()`` Exercized using Twm4Nx YES, informally
+``nxtk_fillwindow()`` . YES
+``nxtk_getwindow()`` . NO
+``nxtk_filltrapwindow()`` . NO
+``nxtk_drawlinewindow()`` . YES
+``nxtk_drawcirclewindow()`` . YES
+``nxtk_fillcirclewindow()`` . YES
+``nxtk_movewindow()`` . NO
+``nxtk_bitmapwindow()`` . YES
+``nxtk_opentoolbar()`` . YES
+``nxtk_closetoolbar()`` . YES
+``nxtk_filltoolbar()`` . YES
+``nxtk_gettoolbar()`` . NO
+``nxtk_filltraptoolbar()`` . NO
+``nxtk_drawlinetoolbar()`` . NO
+``nxtk_drawcircletoolbar()`` . NO
+``nxtk_fillcircletoolbar()`` . NO
+``nxtk_movetoolbar()`` . NO
+``nxtk_bitmaptoolbar()`` . NO
+============================ ========================= ========
+
+NXFONTS API Test Coverage
+-------------------------
+
+======================== ============================= ========
+Function Special Setup/Notes Verified
+======================== ============================= ========
+``nxf_getfonthandle()`` . YES
+``nxf_getfontset()`` . YES
+``nxf_getbitmap()`` . YES
+``nxf_convert_2bpp()`` . NO
+``nxf_convert_4bpp()`` . NO
+``nxf_convert_8bpp()`` Use defconfig when building. YES
+``nxf_convert_16bpp()`` . YES
+``nxf_convert_24bpp()`` . NO
+``nxf_convert_32bpp()`` . YES
+======================== ============================= ========
+
diff --git a/content/docs/latest/_sources/components/nxgraphics/index.rst.txt b/content/docs/latest/_sources/components/nxgraphics/index.rst.txt
new file mode 100644
index 0000000..1c49a93
--- /dev/null
+++ b/content/docs/latest/_sources/components/nxgraphics/index.rst.txt
@@ -0,0 +1,174 @@
+=====================
+NX Graphics Subsystem
+=====================
+
+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.
+
+.. figure:: NuttXScreenShot.jpg
+ :align: center
+
+ **Figure 1**. This screnshot shows the final frame for the NuttX example
+ at ``apps/examples/nx`` running on the simulated, Linux x86 platform with
+ simulated framebuffer output to an X window. This picture shows to framed window
+ 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.
+
+Objectives
+==========
+
+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:
+
+- **Virtual Vertical Graphics Space**. Windows that reside in a
+ virtual, *vertical* space so that it makes sense to talk about one
+ window being on top of another and obscuring the window below it.
+- **Client/Server Model**. A standard client server/model was adopted.
+ NX may be considered a server and other logic that presents the
+ windows are NX clients.
+- **Multi-User Support**. NX includes *front-end* 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.
+- **Minimal Graphics Toolset**. The actual implementation of the
+ graphics operations is performed by common, *back-end* logic. This
+ back-end supports only a primitive set of graphic and rendering
+ operations.
+- **Device Interface**. NX supports any graphics device either of two
+ device interfaces:
+
+ - Any device with random access video memory using the NuttX
+ framebuffer driver interface (see ``include/nuttx/video/fb.h``).
+ - Any LCD-like device than can accept raster line *runs* through a
+ parallel or serial interface (see ``include/nuttx/lcd/lcd.h``). By
+ default, NX is configured to use the frame buffer driver unless
+ ``CONFIG_NX_LCDDRIVER`` is defined =y in your NuttX configuration
+ file.
+
+- **Transparent to NX Client**. 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 *redraw*
+ requests from NX when needed).
+- **Framed Windows and Toolbars**. 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
+ `screenshot <#screenshot>`__ above. These framed windows sub-divide
+ one one window into three relatively independent subwindows: A frame,
+ the contained window and an (optional) toolbar window.
+- **Mouse Support**. 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.
+- **Keyboard input**. 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 *focus*) via a callback function.
+
+Organization
+============
+
+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 `Appendix
+B <#grapicsdirs>`__ of this document. The logic modules are discussed in
+the following sub-paragraphs.
+
+.. figure:: NXOrganization.gif
+ :align: center
+
+NX Graphics Library (``NXGL``)
+------------------------------
+
+NXGLIB is a standalone library that contains low-level graphics
+utilities and direct framebuffer or LCD rendering logic. NX is built on
+top NXGLIB.
+
+NX (``NXSU`` and ``NXMU``)
+--------------------------
+
+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.
+
+:sup:`1`\ 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.
+
+**NXNULL?** At one time, I also envisioned a *NULL* 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.
+
+However, the same end result can be obtained by using the
+```nx_requestbkgd()`` <#nxrequestbkgd>`__ 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.
+
+NX Tool Kit (``NXTK``)
+----------------------
+
+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.
+
+NX Fonts Support (``NXFONTS``)
+------------------------------
+
+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.
+
+NX Widgets (``NxWidgets``)
+--------------------------
+
+`NxWidgets <NxWidgets.html>`__ is a higher level, C++, object-oriented
+library for object-oriented access to graphical "widgets." NxWidgets is
+provided as a separate library in the ``apps/`` 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.
+
+Terminal Driver (``NxTerm``)
+----------------------------
+
+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 ``stdout``
+and ``stderr`` and, hence, can provide the output side of NuttX console.
+).
+
+NX Header Files
+===============
+
+``include/nuttx/nx/nxglib.h``
+ Describes the NXGLIB C interfaces
+``include/nuttx/nx/nx.h``
+ Describes the NX C interfaces
+``include/nutt/nxtk.h``
+ Describe the NXTOOLKIT C interfaces
+``include/nutt/nxfont.h``
+ Describe sthe NXFONT C interfaces
+
+.. toctree::
+ :Caption: User APIs
+
+ nxgl.rst
+ nx.rst
+ nxtk.rst
+ nxfonts.rst
+ nxcursor.rst
+ sample.rst
+ appendix.rst
+
diff --git a/content/docs/latest/_sources/components/nxgraphics/nx.rst.txt b/content/docs/latest/_sources/components/nxgraphics/nx.rst.txt
new file mode 100644
index 0000000..49f33c7
--- /dev/null
+++ b/content/docs/latest/_sources/components/nxgraphics/nx.rst.txt
@@ -0,0 +1,740 @@
+==
+NX
+==
+
+Pre-Processor Definitions
+=========================
+
+The default server message queue name used by the :c:macro:`nx_run` macro:
+
+.. code-block:: c
+
+ #define NX_DEFAULT_SERVER_MQNAME "/dev/nxs"
+
+Mouse button bits:
+
+.. code-block:: c
+
+ #define NX_MOUSE_NOBUTTONS 0x00
+ #define NX_MOUSE_LEFTBUTTON 0x01
+ #define NX_MOUSE_CENTERBUTTON 0x02
+ #define NX_MOUSE_RIGHTBUTTON 0x04
+
+NX Types
+========
+
+The interface to the NX server is managed using a opaque handle:
+
+.. c:type:: FAR void *NXHANDLE
+
+The interface to a specific window is managed using an opaque handle:
+
+.. c:type:: FAR void *NXWINDOW
+
+These define callbacks that must be provided to :c:func:`nx_openwindow`.
+These callbacks will be invoked as part of the processing performed by
+:c:func:`nx_eventhandler`.
+
+.. c:struct:: nx_callback_s
+
+ .. code-block:: c
+
+ 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
+ };
+
+Starting the NX Server
+======================
+
+The *NX Server* 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:
+
+#. The NX server may be started in your board startup logic by simply
+ calling the function ``nxmu_start()``. The board startup logic
+ usually resides the the ``boards/arch/chip/board/src`` directory. The
+ board startup logic can run automatically during the early system if
+ ``CONFIG_BOARD_LATE_INITIALIZE`` is defined in the configuration. Or,
+ the board startup logic can execute under control of the application
+ by calling the ``boardctl(BOARDIOC_INIT, arg)`` OS interface.
+
+ The board initialization logic will run in either case and the simple
+ call to ``nxmu_start()`` will start the NX server.
+
+#. The NX server may also be started later by the application via the
+ ``boardctl(BOARDIOC_NX_START, arg)``
+
+.. c:function:: int nxmu_start(int display, int plane);
+
+ Provides a wrapper function to
+ simplify and standardize the starting of the NX server.
+
+ :param display: The display number to be served by this new NXMU instance.
+ :param plane: The plane number to use to get information about the display geometry and color format.
+
+ :return: Zero (``OK``) is returned on success. This indicates
+ that the NX server has been successfully started, is running, and
+ waiting to accept connections from NX clients.
+ A negated ``errno`` value is returned on failure. The ``errno`` value
+ indicates the nature of the failure.
+
+.. c:function:: void boardctl(...)
+
+ Generic NuttX interface that among
+ many of it functions, may also be used to start the NX server.
+
+ 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
+ ``ioctl()`` calls. This, however, may not be practical in many cases and
+ will lead to "correct" but awkward implementations.
+
+ ``boardctl()`` 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.
+
+ When called with the ``cmd`` of ``BOARDIOC_NX_START``, then the
+ ``boardctl()`` will call ``nxmu_start`` indirectly on behalf of the
+ application. In this case the ``arg`` parameter is ignored.
+
+ :param cmd: Identifies the board command to be executed
+ :param arg: The argument that accompanies the command. The nature of the argument
+ is determined by the specific command.
+
+ :return: On success zero (``OKERROR``) is returned on failure
+ with the ``errno`` variable set to indicate the nature of the failure.
+
+NX Server Callbacks
+===================
+
+.. c:function:: void redraw(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect, bool more, FAR void *arg);
+
+ NX requests that the client re-draw the portion of the
+ window within with rectangle.
+
+ :param hwnd:
+ The handle created by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd`
+ :param rect:
+ The rectangle that needs to be re-drawn (in window relative
+ coordinates)
+ :param more:
+ true: More re-draw requests will follow
+ :param arg:
+ User provided argument (see :c:func:`nx_openwindow`)
+
+.. c:function:: 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);
+
+ The size or position of the window has changed (or the
+ window was just created with zero size.
+
+ :param hwnd:
+ The handle created by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd`
+ :param size:
+ The size of the window
+ :param pos:
+ The position of the upper left hand corner of the window on the
+ overall display
+ :param bounds:
+ The bounding rectangle that the describes the entire display
+ :param arg:
+ User provided argument (see :c:func:`nx_openwindow`)
+
+.. c:function:: void mousein(NXWINDOW hwnd, FAR const struct nxgl_point_s *pos, \
+ uint8_t buttons, FAR void *arg);
+
+ New mouse data is available for the window
+
+ :param hwnd:
+ The handle created by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd`
+ :param pos:
+ The (x,y) position of the mouse
+ :param buttons:
+ See ``NX_MOUSE_*`` definitions
+ :param arg:
+ User provided argument (see :c:func:`nx_openwindow`)
+
+.. c:var:: void (*kbdin)(NXWINDOW hwnd, uint8_t nch, FAR const uint8_t *ch, FAR void *arg);
+
+ New keyboard/keypad data is available for the window.
+
+ :param hwnd:
+ The handle created by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd`
+ :param nch:
+ The number of characters that are available in ch[]
+ :param ch:
+ The array of characters
+ :param arg:
+ User provided argument (see :c:func:`nx_openwindow`)
+
+.. c:var:: void (*event)(NXWINDOW hwnd, enum nx_event_e event, FAR void *arg1, FAR void *arg2);
+
+ This callback is used to communicate server events to the window listener.
+
+ - ``NXEVENT_BLOCKED``: Window messages are blocked.
+ This callback is the response from :c:func:`nx_block`,
+ :c:func:`nxtk_block`. Those blocking interfaces are used
+ to assure that no further messages are directed to the window.
+ Receipt of the blocked callback signifies that (1) there are no
+ further pending callbacks and (2) that the window is now *defunct*
+ 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.
+ - ``NXEVENT_SYNCHED``: Synchronization handshake
+ This completes the handshake started by
+ :c:func:`nx_synch`, or :c:func:`nxtk_synch`.
+ Those interfaces send a synchronization messages to the NX server
+ 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.
+
+ :param hwnd:
+ TWindow handle of window receiving the event
+ :param event:
+ The server event
+ :param arg1:
+ User provided argument (see :c:func:`nx_openwindow`,
+ :c:func:`nx_requestbkgd`, or :c:func:`nxtk_opentoolbar`)
+ :param arg2:
+ TUser provided argument (see :c:func:`nx_block`, :c:func:`nxtk_block`,
+ :c:func:`nx_synch`, or :c:func:`nxtk_synch`)
+
+.. c:macro:: nx_run(fb)
+
+ .. code-block:: c
+
+ #define nx_run(fb) nx_runinstance(NX_DEFAULT_SERVER_MQNAME, dev)
+
+.. c:function:: int nx_runinstance(FAR const char *mqname, FAR struct fb_vtable_s *fb)
+
+ This is the server entry point. It does not return; the
+ calling thread is dedicated to supporting NX server.
+
+ NOTE that multiple instances of the NX server may run at the same time,
+ with different callback and message queue names. ``nx_run()`` is simply
+ a macro that can be used when only one server instance is required. In
+ that case, a default server name is used.
+
+ :param mqname: The name for the server incoming message queue
+ :param dev: Framebuffer or LCD driver "object" to be used
+
+ :return: This function usually does not return. If it does
+ return, it will return ``ERROR`` and ``errno`` will be set
+ appropriately.
+
+.. c:macro:: nx_connect(cb)
+
+ .. code-block:: c
+
+ #define nx_connect(cb) nx_connectinstance(NX_DEFAULT_SERVER_MQNAME)
+
+.. c:function:: NXHANDLE nx_connectinstance(FAR const char *svrmqname);
+
+ Open a connection from a client to the NX server. One
+ one client connection is normally needed per thread as each connection
+ can host multiple windows.
+
+ NOTES:
+
+ - This function returns before the connection is fully instantiated. it
+ is necessary to wait for the connection event before using the
+ returned handle.
+ - Multiple instances of the NX server may run at the same time, each
+ with different message queue names.
+ - ``nx_connect()`` is simply a macro that can be used when only one
+ server instance is required. In that case, a default server name is
+ used.
+
+ :param svrmqname: The name for the server incoming message queue
+
+ :return: Success: A non-NULL handle used with subsequent NX accesses
+ Failure: NULL is returned and errno is set appropriately.
+
+.. c:function:: void nx_disconnect(NXHANDLE handle)
+
+ Disconnect a client from the NX server and/or free
+ resources reserved by :c:func:`nx_connect`/c:func:`nx_connectinstance`.
+
+ :param handle: The handle returned by :c:func:`nx_connectinstance`.
+
+.. c:function:: int nx_eventhandler(NXHANDLE handle);
+
+ The client code must call this function periodically to
+ process incoming messages from the server. If ``CONFIG_NX_BLOCKING`` is
+ defined, then this function not return until a server message is
+ received.
+
+ When ``CONFIG_NX_BLOCKING`` 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.
+ ```nx_eventnotify()`` <#nxeventnotify>`__ may be called to get a signal
+ event whenever a new incoming server event is available.
+
+ :param handle: The handle returned by ```nx_connect()`` <#nxconnectinstance>`__.
+
+ :return:
+ - ``OK``: No errors occurred. If ``CONFIG_NX_BLOCKING`` is defined,
+ then one or more server messages were processed.
+ - ``ERROR``: An error occurred and ``errno`` has been set
+ appropriately. Of particular interest, it will return
+ ``errno == EHOSTDOWN`` when the server is disconnected. After that
+ event, the handle can no longer be used.
+
+.. c:function:: int nx_eventnotify(NXHANDLE handle, int signo);
+
+ Rather than calling :c:func:`nx_eventhandler` periodically, the client may
+ register to receive a signal when a server event is available. The
+ client can then call :c:func:nx_eventhandler` only
+ when incoming events are available.
+
+ The underlying implementation used ``mq_notifiy()`` and, as a result,
+ the client must observe the rules for using ``mq_notifiy()``:
+
+ - Only one event is signalled. Upon receipt of the signal, if the
+ client wishes further notifications, it must call
+ ``nx_eventnotify()`` again.
+ - The signal will only be issued when the message queue transitions
+ from empty to not empty.
+
+ :param handle: The handle returned by ```nx_connect()`` <#nxconnectinstance>`__.
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nx_block(NXWINDOW hwnd, FAR void *arg);
+
+ 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.
+
+ The ``event`` callback with the ``NXEVENT_BLOCKED`` event is the
+ response from ``nx_block()``. This blocking interface is used to assure
+ that no further messages are are directed to the window. Receipt of the
+ ``NXEVENT_BLOCKED`` event signifies that (1) there are no further
+ pending callbacks and (2) that the window is now *defunct* and will
+ receive no further callbacks.
+
+ 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.
+
+ :param wnd: The window to be blocked
+ :param arg: An argument that will accompany the block messages (This is ``arg2`` in
+ the event callback).
+
+ :return: OK on success; ERROR on failure with errno set
+ appropriately.
+
+.. c:function:: int nx_synch(NXWINDOW hwnd, FAR void *arg);
+
+ 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.
+
+ 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 = 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 --
+ }
+ }
+
+ 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).
+
+ :return: OK on success; ERROR on failure with errno set
+ appropriately
+
+.. c:function:: NXWINDOW nx_openwindow(NXHANDLE handle, uint8_t flags, \
+ FAR const struct nx_callback_s *cb, \
+ FAR void *arg);
+
+ Create a new window.
+
+ :param handle: The handle returned by ```nx_connect()`` <#nxconnectinstance>`__.
+ :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()``.
+
+ :param cb: Callbacks used to process window events
+ :param arg: User provided value that will be returned with NX callbacks.
+
+ :return: Success: A non-NULL handle used with subsequent NX accesses
+ Failure: NULL is returned and errno is set appropriately.
+
+.. c:function:: int nx_closewindow(NXWINDOW hwnd)
+
+ Destroy a window created by :c:func:`nx_openwindow` window.
+
+ :param hwnd: The handle returned by ```nx_openwindow()`` <#nxopenwindow>`__ that
+ identifies the window to be destroyed. This handle must not have been
+ one returned by ```nx_requestbkgd()`` <#nxrequestbkgd>`__.
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nx_requestbkgd(NXHANDLE handle, \
+ FAR const struct nx_callback_s *cb, \
+ FAR void *arg);
+
+ 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:
+
+ - If you want to implement a windowless solution. The single screen can
+ be used to create a truly simple graphic environment.
+ - 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.
+
+ This API only requests the handle of the background window. That handle
+ will be returned asynchronously in a subsequent position and redraw
+ callbacks.
+
+ Cautions:
+
+ - The following should never be called using the background window.
+ They are guaranteed to cause severe crashes: :c:func:`nx_setposition`,
+ :c:func:`nx_setsize`, :c:func:`nx_raise`, or :c:func:`nx_lower`,
+ :c:func:`nx_modal`, :c:func:`nx_setvisibility`.
+ - Neither :c:func:`nx_requestbkgd` nor :c:func:`nx_releasebkgd`
+ should be called more than once. Multiple instances of the
+ background window are not supported.
+
+ :param handle: The handle returned by ```nx_connect()`` <#nxconnectinstance>`__.
+ :param cb: Callbacks to use for processing background window events
+ :param arg: User provided argument (see ```nx_openwindow()`` <#nxopenwindow>`__)
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nx_releasebkgd(NXWINDOW hwnd)
+
+ Release the background window previously acquired using
+ :c:func:`nx_requestbkgd` and return control of the background to NX.
+
+ :param handle: The handle returned indirectly by :c:func:`nx_requestbkgd`.
+ This handle must not have been one created by :c:func:`nx_openwindow`.
+
+ :return: ``OK`` on success; ``ERROR`` on failure with ``errno`` set appropriately
+
+.. c:function:: int nx_getposition(NXWINDOW hwnd)
+
+ Request the position and size information for the
+ selected window. The values will be return asynchronously through the
+ client callback function pointer.
+
+ :param hwnd: The handle returned by :c:func:`nx_openwindow` or
+ :c:func:`nx_requestbkgd`.
+
+ :return: ``OK`` on success; ``ERROR`` on failure with ``errno`` set appropriately
+
+.. c:function:: int nx_setposition(NXWINDOW hwnd, FAR struct nxgl_point_s *pos)
+
+ Set the position and size for the selected window.
+
+ :param hwnd: The handle returned by :c:func:`nx_openwindow`. This
+ handle must not have been created by :c:func:`nx_requestbkgd`.
+ :param pos: The new position of the window
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nx_setsize(NXWINDOW hwnd, FAR struct nxgl_size_s *size)
+
+ Set the size of the selected window.
+
+ :param hwnd: The handle returned by :c:func:`nx_openwindow`. This
+ handle must not have been created by :c:func:`nx_requestbkgd`.
+ :param size: The new size of the window (in pixels).
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nx_raise(NXWINDOW hwnd)
+
+ 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`.
+
+ :return: ``OK`` on success; ``ERROR`` on failure with ``errno`` set appropriately
+
+.. c:function:: int nx_lower(NXWINDOW hwnd);
+
+ Lower the specified window to the bottom 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`.
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nx_modal(NXWINDOW hwnd, bool modal)
+
+ May be used to either (1) raise a window to the top of
+ the display and select modal behavior, or (2) disable modal behavior.
+
+ :param hwnd: The handle returned by :c:func:`nx_openwindow`. This
+ handle must not have been created by :c:func:`nx_requestbkgd`.
+ :param modal: True: enter modal state; False: leave modal state
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nx_setvisibility(NXWINDOW hwnd, bool hide);
+
+ 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.
+
+ :param hwnd: The handle returned by :c:func:`nx_openwindow`. This
+ handle must not have been created by :c:func:`nx_requestbkgd`.
+ :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 nx_ishidden(NXWINDOW hwnd);
+
+ 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 :c:func:`nx_setvisibily`
+ before that new setting is reported by :c:func:`nx_ishidden`. ``nx_synch()``
+ may be used if temporal synchronization is required.
+
+ :param hwnd: The handle returned by :c:func:`nx_openwindow` that
+ identifies the window to be queried.
+
+ :return: *True*: the window is hidden, *false*: the window is
+ visible
+
+.. c:function:: int nx_fill(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect, \
+ nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
+
+ Fill the specified rectangle in the window with the
+ specified color.
+
+ :param hwnd: The handle returned by ```nx_openwindow()`` <#nxopenwindow>`__ or
+ ```nx_requestbkgd()`` <#nxrequestbkgd>`__
+ :param rect: The location 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 nx_getrectangle(NXWINDOW hwnd, 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 hwnd: The handle returned by :c:func:`nx_openwindow` or
+ :c:func:`nx_requestbkgd`
+ :param rect: The location to be copied
+ :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 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]);
+
+ Fill the specified trapezoidal region in the window
+ with the specified color.
+
+ :param hwnd: The handle returned by :c:func:`nx_openwindow` or
+ :c:func:`nx_requestbkgd`
+ :param clip: Clipping rectangle relative to window (may be null)
+ :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 nx_drawline(NXWINDOW hwnd, 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 :c:func:`nxgl_splitline`
+ to break the line into trapezoids and then calls :c:func:`nx_filltrapezoid`
+ to render the line.
+
+ :param hwnd: The handle returned by :c:func:`nx_openwindow` or
+ :c:func:`nx_requestbkgd`
+ :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::
+
+ /* 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 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]);
+
+ Draw a circular outline using the specified line
+ thickness and color.
+
+ :param hwnd: The handle returned by :c:func:`nx_openwindow` or
+ :c:func:`nx_requestbkgd`
+ :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 nx_fillcircle(NXWINDOW hwnd, 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 hwnd: The handle returned by :c:func:`nx_openwindow` or
+ :c:func:`nx_requestbkgd`
+ :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 nx_setbgcolor(NXHANDLE handle, \
+ nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
+
+Set the color of the background.
+
+:param handle: The handle created by :c:func:`nx_openwindow` or
+ :c:func:`nx_requestbkgd`
+:param color: The color to use in the background
+
+:return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nx_move(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect, \
+ FAR const struct nxgl_point_s *offset);
+
+Move a rectangular region within the window.
+
+:param hwnd: The handle returned by :c:func:`nx_openwindow` or
+ :c:func:`nx_requestbkgd` that specifies the window within which the move is to be done
+:param rect: Describes the (source) rectangular region to move
+:param offset: The offset to move the region
+
+:return: ``OK`` on success; ``ERROR`` on failure with ``errno`` set appropriately
+
+.. c:function:: 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);
+
+ Copy a rectangular region of a larger image into the
+ rectangle in the specified window.
+
+ :param hwnd: The handle returned by :c:func:`nx_openwindow` or
+ :c:func:`nx_requestbkgd` that specifies the window that will receive the bitmap image.
+ :param dest: Describes the rectangular on the display that will receive the bit map.
+ :param src: The start of the source image. 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 window coordinates, however, the origin may
+ lie outside of the display.
+ :param stride: The width of the full source image in bytes.
+
+ :return: ``OK`` on success; ``ERROR`` on failure with ``errno`` set appropriately
+
+.. c:function:: int nx_kbdchin(NXHANDLE handle, uint8_t ch);
+.. c:function:: int nx_kbdin(NXHANDLE handle, uint8_t nch, FAR const uint8_t *ch);
+
+ 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.
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nx_mousein(NXHANDLE handle, nxgl_coord_t x, nxgl_coord_t y, uint8_t buttons)
+
+ 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.
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. _nx-tool-kit-nxtk-1:
+
+
diff --git a/content/docs/latest/_sources/components/nxgraphics/nxcursor.rst.txt b/content/docs/latest/_sources/components/nxgraphics/nxcursor.rst.txt
new file mode 100644
index 0000000..77205ab
--- /dev/null
+++ b/content/docs/latest/_sources/components/nxgraphics/nxcursor.rst.txt
@@ -0,0 +1,50 @@
+================================
+NX Cursor Support (``NXCURSOR``)
+================================
+
+.. c:function:: int nxcursor_enable(NXHANDLE hnd, bool enable)
+
+ Enable/disable presentation of the cursor. The disabled
+ cursor still exits and still may be controlled, but is not visible on
+ the display.
+
+ :param hnd:
+ The server handle returned by :c:func:`nx_connect`.
+ :param enable: The new cursor position
+
+ :return: OK on success; ERROR on failure with errno set appropriately.
+
+.. c:function:: int nxcursor_setimage(NXHANDLE hnd, FAR const struct nx_cursorimage_s *image)
+
+ Set the cursor image.
+
+ The image is provided a a 2-bits-per-pixel image. The two bit incoding
+ is as following:
+
+ - 00: The transparent background.
+ - 01: Color1: The main color of the cursor.
+ - 10: Color2: The color of any border.
+ - 11: Color3: A blend color for better imaging (fake anti-aliasing).
+
+ **NOTE:** The NX logic will reference the user image buffer repeatedly.
+ That image buffer must persist for as long as the NX server connection
+ persists.
+
+ :param hnd: The server handle returned by :c:func:`nx_connect`
+ :param image:
+ An instance of ``struct struct nx_cursorimage_s`` that describes the
+ cursor image. See ``<nuttx/nx/nxcursor.h>`` for the full description
+ of this structure.
+
+ :return: OK on success; ERROR on failure with errno set appropriately.
+
+.. c:function:: int nxcursor_setposition(NXHANDLE hnd, FAR const struct nxgl_point_s *pos)
+
+ Move the cursor to the specified position.
+
+ :param hnd: The server handle returned by :c:func:`nx_connect`
+ :param pos: The new cursor position
+
+ :return: OK on success; ERROR on failure with errno set appropriately.
+
+
diff --git a/content/docs/latest/_sources/components/nxgraphics/nxfonts.rst.txt b/content/docs/latest/_sources/components/nxgraphics/nxfonts.rst.txt
new file mode 100644
index 0000000..98da7d3
--- /dev/null
+++ b/content/docs/latest/_sources/components/nxgraphics/nxfonts.rst.txt
@@ -0,0 +1,127 @@
+==============================
+NX Fonts Support (``NXFONTS``)
+==============================
+
+NXFONTS types
+=============
+
+.. c:struct:: nx_fontmetric_s
+
+ This structures provides the metrics for one glyph:
+
+ .. code-block:: c
+
+ 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;
+ };
+
+.. c:struct:: nx_fontbitmap_s
+
+ This structure binds the glyph metrics to the glyph bitmap:
+
+ .. code-block:: c
+
+ struct nx_fontbitmap_s
+ {
+ struct nx_fontmetric_s metric; /* Character metrics */
+ FAR const uint8_t *bitmap; /* Pointer to the character bitmap */
+ };
+
+
+.. c:struct:: nx_fontset_s
+
+ This structure describes one contiguous grouping of glyphs that can be
+ described by an array starting with encoding ``first`` and extending
+ through (``first`` + ``nchars`` - 1).
+
+ .. code-block:: c
+
+ 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;
+ };
+
+.. c:struct:: nx_font_s
+
+ This structure describes the overall fontset.
+
+ .. code-block:: c
+
+ 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 */
+ };
+
+.. c:function:: NXHANDLE nxf_getfonthandle(enum nx_fontid_e fontid);
+
+ Given a numeric font ID, return a handle that may be
+ subsequently be used to access the font data sets.
+
+ :param fontid: Identifies the font set to use
+
+ :return: A handle that may be subsequently be used to access the font data sets.
+
+.. c:function:: FAR const struct nx_font_s *nxf_getfontset(NXHANDLE handle);
+
+ Return information about the current font set.
+
+ :param handle: A font handle previously returned by :c:func:`nxf_getfonthandle`.
+ :return: An instance of ``struct nx_font_s`` describing the font set.
+
+.. c:function:: FAR const struct nx_fontbitmap_s *nxf_getbitmap(NXHANDLE handle, uint16_t ch)
+
+ Return font bitmap information for the selected
+ character encoding.
+
+ :param ch: The char code for the requested bitmap.
+ :param handle: A font handle previously returned by :c:func:`nxf_getfonthandle`.
+ :return: An instance of :c:struct:`nx_fontbitmap_s` describing the glyph.
+
+.. c:function:: 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);
+
+.. c:function:: int nxf_convert_4bpp(FAR uint8_t *dest, uint16_t height, \
+ uint16_t width, uint16_t stride, \
+ FAR const struct nx_fontbitmap_s *bm, \
+ nxgl_mxpixel_t color);
+.. c:function:: 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);
+.. c:function:: 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);
+.. c:function:: 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);
+.. c:function:: 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);
+
+ Convert the 1BPP font to a new pixel depth.
+
+ :param dest: The destination buffer provided by the caller.
+ :param height: The max height of the returned char in rows.
+ :param width: The max width of the returned char in pixels.
+ :param stride: The width of the destination buffer in bytes.
+ :param bm: Describes the character glyph to convert
+ :param color: The color to use for '1' bits in the font bitmap (0 bits are transparent).
+
+ :return: ``OK`` on success; ``ERROR`` on failure with ``errno`` set appropriately.
+
diff --git a/content/docs/latest/_sources/components/nxgraphics/nxgl.rst.txt b/content/docs/latest/_sources/components/nxgraphics/nxgl.rst.txt
new file mode 100644
index 0000000..45d89cd
--- /dev/null
+++ b/content/docs/latest/_sources/components/nxgraphics/nxgl.rst.txt
@@ -0,0 +1,259 @@
+.. _nx-graphics-library-nxgl-1:
+
+==============================
+NX Graphics Library (``NXGL``)
+==============================
+
+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 ``include/nuttx/nx/nxglib.h``
+for the full set of APIs; those APIs might be of interest if you are
+rendering directly into framebuffer or LCD memory.
+
+NXGL Types
+----------
+
+.. c:type:: nxgl_mxpixel_t
+
+ Holds one device pixel. NXGLIB will select the
+ smallest size for the ``nxgl_mxpixel_t`` that just contains the pixel:
+ ``byte`` if 16, 24, and 32 resolution support is disabled, ``uint16_t``
+ if 24, and 32 resolution support is disabled, or ``uint32_t``.
+
+.. c:type:: nxgl_coord_t
+
+ A given coordinate is limited to the screen height an
+ width. If either of those values exceed 32,767 pixels, then the
+ following will have to need to change:
+
+.. c:struct:: nxgl_point_s
+
+ Describes a point on the display:
+
+ .. code-block:: c
+
+ struct nxgl_point_s
+ {
+ nxgl_coord_t x; /* X position, range: 0 to screen width - 1 */
+ nxgl_coord_t y; /* Y position, range: 0 to screen height - 1 */
+ };
+
+.. c:struct:: nxgl_size_s
+
+ Describes the size of a rectangular region.
+
+ .. code-block:: c
+
+ struct nxgl_size_s
+ {
+ nxgl_coord_t w; /* Width in pixels */
+ nxgl_coord_t h; /* Height in rows */
+ };
+
+.. c:struct:: nxgl_rect_s
+
+ Describes a positioned rectangle on the display.
+
+ .. code-block:: c
+
+ struct nxgl_rect_s
+ {
+ struct nxgl_point_s pt1; /* Upper, left-hand corner */
+ struct nxgl_point_s pt2; /* Lower, right-hand corner */
+ };
+
+.. c:struct:: nxgl_run_s
+
+ 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.
+
+ .. code-block:: c
+
+ struct nxgl_run_s
+ {
+ b16_t x1; /* Left X position, range: 0 to x2 */
+ b16_t x2; /* Right X position, range: x1 to screen width - 1 */
+ nxgl_coord_t y; /* Top Y position, range: 0 to screen height - 1 */
+ };
+
+.. c:struct:: nxgl_trapezoid_s
+
+ Describes a horizontal trapezoid on the
+ display in terms the run at the top of the trapezoid and the run at the
+ bottom.
+
+ .. code-block:: c
+
+ struct nxgl_trapezoid_s
+ {
+ struct nxgl_run_s top; /* Top run */
+ struct nxgl_run_s bot; /* bottom run */
+ };
+
+.. c:function:: void nxgl_rgb2yuv(uint8_t r, uint8_t g, uint8_t b, uint8_t *y, uint8_t *u, uint8_t *v)
+
+ Convert 8-bit RGB triplet to 8-bit YUV triplet.
+
+.. c:function:: void nxgl_yuv2rgb(uint8_t y, uint8_t u, uint8_t v, uint8_t *r, uint8_t *g, uint8_t *b);
+
+ Convert 8-bit YUV triplet to 8-bit RGB triplet.
+
+.. c:function:: void nxgl_rectcopy(FAR struct nxgl_rect_s *dest, FAR const struct nxgl_rect_s *src)
+
+ This is essentially ``memcpy()``\ for rectangles. We
+ don't do structure assignments because some compilers are not good at
+ that.
+
+.. c:function:: void nxgl_rectoffset(FAR struct nxgl_rect_s *dest, \
+ FAR const struct nxgl_rect_s *src, \
+ nxgl_coord_t dx, nxgl_coord_t dy);
+
+ Offset the rectangle position by the specified dx, dy
+ values.
+
+.. c:function:: void nxgl_vectoradd(FAR struct nxgl_point_s *dest, \
+ FAR const struct nxgl_point_s *v1, \
+ FAR const struct nxgl_point_s *v2);
+
+
+ Add two 2x1 vectors and save the result to a third.
+
+.. c:function:: void nxgl_vectsubtract(FAR struct nxgl_point_s *dest, \
+ FAR const struct nxgl_point_s *v1, \
+ FAR const struct nxgl_point_s *v2);
+
+ Add subtract vector ``v2`` from vector ``v1`` and
+ return the result in vector dest.
+
+.. c:function:: void nxgl_rectintersect(FAR struct nxgl_rect_s *dest, \
+ FAR const struct nxgl_rect_s *src1, \
+ FAR const struct nxgl_rect_s *src2);
+
+ Return the rectangle representing the intersection of
+ the two rectangles.
+
+.. c:function:: void nxgl_rectunion(FAR struct nxgl_rect_s *dest, \
+ FAR const struct nxgl_rect_s *src1, \
+ FAR const struct nxgl_rect_s *src2);
+
+ Given two rectangles, ``src1`` and ``src2``, return the
+ larger rectangle that contains both, ``dest``.
+
+.. c:function:: void nxgl_nonintersecting(FAR struct nxgl_rect_s result[4], \
+ FAR const struct nxgl_rect_s *rect1, \
+ FAR const struct nxgl_rect_s *rect2);
+
+ Return the regions of rectangle ``rect1`` that do not
+ intersect with ``rect2``. This will four rectangles, some of which may
+ be degenerate (and can be picked off with :c:func:`nxgl_nullrect`).
+
+.. c:function:: bool nxgl_rectoverlap(FAR struct nxgl_rect_s *rect1, \
+ FAR struct nxgl_rect_s *rect2);
+
+ Return true if the two rectangles overlap.
+
+.. c:function:: bool nxgl_rectinside(FAR const struct nxgl_rect_s *rect, \
+ FAR const struct nxgl_point_s *pt);
+
+ Return true if the point ``pt`` lies within ``rect``.
+
+.. c:function:: void nxgl_rectsize(FAR struct nxgl_size_s *size, \
+ FAR const struct nxgl_rect_s *rect);
+
+ Return the size of the specified rectangle.
+
+.. c:function:: bool nxgl_nullrect(FAR const struct nxgl_rect_s *rect);
+
+ Return true if the area of the retangle is <= 0.
+
+.. c:function:: void nxgl_runoffset(FAR struct nxgl_run_s *dest, \
+ FAR const struct nxgl_run_s *src, \
+ nxgl_coord_t dx, nxgl_coord_t dy);
+
+ Offset the run position by the specified ``dx``, ``dy``
+ values.
+
+.. c:function:: void nxgl_runcopy(FAR struct nxgl_run_s *dest, \
+ FAR const struct nxgl_run_s *src);
+
+ This is essentially ``memcpy()``\ for runs. We don't do
+ structure assignments because some compilers are not good at that.
+
+.. c:function:: void nxgl_trapoffset(FAR struct nxgl_trapezoid_s *dest, \
+ FAR const struct nxgl_trapezoid_s *src, \
+ nxgl_coord_t dx, nxgl_coord_t dy);
+
+ Offset the trapezoid position by the specified ``dx``,
+ ``dy`` values.
+
+.. c:function:: void nxgl_trapcopy(FAR struct nxgl_trapezoid_s *dest, \
+ FAR const struct nxgl_trapezoid_s *src);
+
+ This is essentially ``memcpy()``\ for trapezoids. We
+ don't do structure assignments because some compilers are not good at
+ that.
+
+.. c:function:: void nxgl_colorcopy(nxgl_mxpixel_t dest[CONFIG_NX_NPLANES], \
+ const nxgl_mxpixel_t src[CONFIG_NX_NPLANES]);
+
+ This is essentially ``memcpy()``\ for colors. This does
+ very little for us other than hide all of the conditional compilation
+ for planar colors in one place.
+
+.. c:function:: 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);
+
+ 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:
+
+ #. If ``y1 == y2`` then the line is horizontal and is better represented
+ as a rectangle.
+ #. If ``x1 == x2`` then the line is vertical and also better represented
+ as a rectangle.
+ #. 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).
+ #. 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.
+
+ :param vector: A pointer to the vector described the line to be drawn.
+ :param traps: A pointer to a array of trapezoids (size 3).
+ :param rect: A pointer to a rectangle.
+
+ :return:
+ - 0: Line successfully broken up into three trapezoids. Values in traps[0], traps[1], and traps[2] are valid.
+ - 1: Line successfully represented by one trapezoid. Value in traps[1] is valid.
+ - 2: Line successfully represented by one rectangle. Value in rect is valid
+ - <0: On errors, a negated errno value is returned.
+
+.. c:function:: void nxgl_circlepts(FAR const struct nxgl_point_s *center, nxgl_coord_t radius, \
+ FAR struct nxgl_point_s *circle);
+
+ 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 :c:func:`nx_drawcircle` or related APIs to draw a
+ circle outline.
+
+ :param center: A pointer to the point that is the center of the circle.
+ :param radius: The radius of the circle in pixels.
+ :param circle: A pointer the first entry in an array of 16 points where the circle points will be returned.
+
+.. c:function:: void nxgl_circletraps(FAR const struct nxgl_point_s *center, nxgl_coord_t radius, \
+ FAR struct nxgl_trapezoid_s *circle);
+
+
+ Given a description of a a circle, return 8 trapezoids
+ that can be used to fill the circle by
+ :c:func:`nx_fillcircle` and other interfaces.
+
+ :param center: A pointer to the point that is the center of the circle.
+ :param radius: The radius of the circle in pixels.
+ :param circle: A pointer the first entry in an array of 8 trapezoids where the
+ circle description will be returned.
+
diff --git a/content/docs/latest/_sources/components/nxgraphics/nxtk.rst.txt b/content/docs/latest/_sources/components/nxgraphics/nxtk.rst.txt
new file mode 100644
index 0000000..52a80cc
--- /dev/null
+++ b/content/docs/latest/_sources/components/nxgraphics/nxtk.rst.txt
@@ -0,0 +1,653 @@
+======================
+NX Tool Kit (``NXTK``)
+======================
+
+NXTK implements where the *framed window*. NX framed windows consist of
+three components within one NX window:
+
+ #. The window *border*,
+ #. The main *client window* area, and
+ #. A *toolbar* area
+
+Each sub-window represents a region within one window. `Figure
+1 <#screenshot>`__ shows some simple NX framed windows. NXTK allows
+these sub-windows to be managed more-or-less independently:
+
+ - 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
+ :c:func:`nxtk_openwindow`; Separate toolbar
+ sub-window callbacks are reigistered when the toolbar is added using
+ :c:func:`nxtk_opentoolbar`. (NOTES: (1) only the
+ client sub-window receives keyboard input and, (2) border callbacks
+ are not currently accessible by the user).
+ - 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.
+
+.. c:type:: FAR void *NXTKWINDOW
+
+ This is the handle that can be used to access the window data region.
+
+.. c:function:: int nxtk_block(NXWINDOW hwnd, FAR void *arg)
+
+ 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.
+
+ The ``event`` callback with the ``NXEVENT_BLOCKED`` event is the
+ response from ``nxtk_block()``. This blocking interface is used to
+ assure that no further messages are are directed to the window. Receipt
+ of the ``NXEVENT_BLOCKED`` event signifies that (1) there are no further
+ pending callbacks and (2) that the window is now *defunct* and will
+ receive no further callbacks.
+
+ 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.
+
+ :param wnd: The window to be blocked
+ :param arg: An argument that will accompany the block messages (This is ``arg2`` in
+ the event callback).
+
+ :return: OK on success; ERROR on failure with errno set
+ appropriately.
+
+.. c:function:: int nxtk_synch(NXWINDOW hwnd, FAR void *arg);
+
+ 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.
+
+ 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).
+
+ :return: OK on success; ERROR on failure with errno set
+ appropriately
+
+.. c:function:: NXTKWINDOW nxtk_openwindow(NXHANDLE handle, uint8_t flags, \
+ FAR const struct nx_callback_s *cb, \
+ FAR void *arg);
+
+ Create a new, framed window.
+
+ :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 ``nxtk_setvisibility()``.
+
+ :param cb:
+ Callbacks used to process window events
+ :param arg:
+ User provided argument (see ```nx_openwindow()`` <#nxopenwindow>`__)
+
+ :return: Success: A non-NULL handle used with subsequent NXTK window accesses
+ Failure: NULL is returned and errno is set appropriately.
+
+.. c:function:: int nxtk_closewindow(NXTKWINDOW hfwnd);
+
+ Close the window opened by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
+
+ :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_getposition(NXTKWINDOW hfwnd);
+
+ 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.
+
+ :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_setposition(NXTKWINDOW hfwnd, FAR struct nxgl_point_s *pos);
+
+ 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.
+
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
+ :param pos:
+ The new position of the client sub-window
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nxtk_setsize(NXTKWINDOW hfwnd, FAR struct nxgl_size_s *size);
+
+ 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.
+
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
+ :param size:
+ The new size of the client sub-window.
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nxtk_raise(NXTKWINDOW hfwnd);
+
+ Bring the window containing the specified client
+ sub-window to the top of the display.
+
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__ specifying the window to
+ be raised.
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nxtk_lower(NXTKWINDOW hfwnd);
+
+ Lower the window containing the specified client
+ sub-window to the bottom of the display.
+
+ :param hfwnd:
+ A handle previously returned by
+ ```nxtk_openwindow()`` <#nxtkopenwindow>`__ specifying the window to
+ be lowered.
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nxtk_modal(NXWINDOW hwnd, bool modal);
+
+ May be used to either (1) raise a window to the top of
+ the display and select modal behavior, or (2) disable modal behavior.
+
+ :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
+
+ :return: ``OK`` on success; ``ERROR`` on failure with
+ ``errno`` set appropriately
+
+.. c:function:: int nxtk_setvisibility(NXWINDOW hwnd, bool hide);
+
+ 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.
+
+ :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:
+
+
diff --git a/content/docs/latest/_sources/components/nxgraphics/sample.rst.txt b/content/docs/latest/_sources/components/nxgraphics/sample.rst.txt
new file mode 100644
index 0000000..7de9601
--- /dev/null
+++ b/content/docs/latest/_sources/components/nxgraphics/sample.rst.txt
@@ -0,0 +1,30 @@
+===========
+Sample Code
+===========
+
+``apps/examples/nx*``. 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.
+
+- ``apps/examples/nx``. 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.
+- ``apps/examples/nxhello``. This is intended to be simplest NX test:
+ It simply displays the words "Hello, World!" centered on the display.
+- ``apps/examples/nxtext``. 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.
+
+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.
+
+**Building** ``apps/examples/nx``. Testing was performed using the
+Linux/Cygwin-based NuttX simulator. Instructions are provided for
+building that simulation are provided in `Appendix C <#testcoverage>`__
+of this document.
+
+
diff --git a/content/docs/latest/_sources/components/nxwidgets.rst.txt b/content/docs/latest/_sources/components/nxwidgets.rst.txt
new file mode 100644
index 0000000..01cba46
--- /dev/null
+++ b/content/docs/latest/_sources/components/nxwidgets.rst.txt
@@ -0,0 +1,59 @@
+=========
+NxWidgets
+=========
+
+In order to better support NuttX based platforms, a special graphical
+userinterface has been created called NXWidgets. NXWidgets is written in
+C++ and integrates seamlessly with the NuttX `NX graphics
+subsystem <NXGraphicsSubsystem.html>`__ in order to provide graphic
+objects, or "widgets," in the NX Graphics Subsystem
+
+Some of the features of NXWidgets include:
+
+- **Conservative C++**. NXWidgets is written entirely in C++ but using
+ only selected "embedded friendly" C++ constructs that are fully
+ supported under NuttX. No additional C++ support libraries are
+ required.
+- **NX Integration**. NXWidgets integrate seamlessly with the `NX
+ graphics subsystem <NXGraphicsSubsystem.html>`__. Think of the X
+ server under Linux … the NX graphics system is like a tiny X server
+ that provides windowing under NuttX. By adding NXWidgets, you can
+ support graphics objects like buttons and text boxes in the NX
+ windows and toolbars.
+- **Small Footprint**. NXWidgets is tailored for use MCUs in embedded
+ applications. It is ideally suited for mid- and upper-range of most
+ MCU families. A complete NXWidgets is possible in as little as 40K of
+ FLASH and maybe 4K of SRAM.
+- **Output Devices**. NXWidgets will work on the high-end frame buffer
+ devices as well as on LCDs connected via serial or parallel ports to
+ a small MCU.
+- **Input Devices**. NXWidgets will accept position and selection
+ inputs from a mouse or a touchscreen. It will also support character
+ input from a keyboard such as a USB keyboard. NXWidgets supports on
+ very special widget called CKeypad that will provide keyboard input
+ via an on-screen keypad that can be operated via mouse or touchscreen
+ inputs.
+- **Many Graphic Objects**. Some of the graphic objects supported by
+ NXWidgets include labels, buttons, text boxes, button arrays, check
+ boxes, cycle buttons, images, sliders, scrollable list boxes,
+ progress bars, and more.
+- **DOxygen Documentation** DOxygen documentation is available.
+
+Note: Many of the fundamental classed in NxWidgets derive from the
+Antony Dzeryn's "Woopsi" project: http://woopsi.org/ which also has a
+BSD style license. See the COPYING file for details.
+
+NXWidgets DOxygen Documentation
+===============================
+
+Release notes, DOxygen documentation, as well as downloads for the
+latest NxWidgets releases are available online:
+
+**NxWidgets-1.19**:
+`Documentation <http://nuttx.org/nxwidgets_v1_19/html/index.html>`__,
+`Release
+notes <http://sourceforge.net/projects/nuttx/files/NxWidgets/NxWidgets-1.19/>`__,
+and
+`Downloads <http://sourceforge.net/projects/nuttx/files/NxWidgets/NxWidgets-1.19/>`__
+
+Thanks go to Jose Pablo Carballo for contributing this!
diff --git a/content/docs/latest/_sources/components/paging.rst.txt b/content/docs/latest/_sources/components/paging.rst.txt
new file mode 100644
index 0000000..92d9c60
--- /dev/null
+++ b/content/docs/latest/_sources/components/paging.rst.txt
@@ -0,0 +1,423 @@
+================
+On-Demand Paging
+================
+
+Introduction
+============
+
+Overview
+--------
+
+This document summarizes the design of NuttX on-demand paging. This
+feature permits embedded MCUs with some limited RAM space to execute
+large programs from some non-random access media.
+
+What kind of platforms can support NuttX on-demang paging?
+
+ #. The MCU should have some large, probably low-cost non-volatile
+ storage such as serial FLASH or an SD card. This storage probably
+ does not support non-random access (otherwise, why not just execute
+ the program directly on the storage media). SD and serial FLASH are
+ inexpensive and do not require very many pins and SPI support is
+ prevalent in just about all MCUs. This large serial FLASH would
+ contain a big program. Perhaps a program of several megabytes in
+ size.
+ #. The MCU must have a (relatively) small block of fast SRAM from which
+ it can execute code. A size of, say 256K (or 192K as in the NXP
+ LPC3131) would be sufficient for many applications.
+ #. The MCU has an MMU (again like the NXP LPC3131).
+
+If the platform meets these requirement, then NuttX can provide
+on-demand paging: It can copy .text from the large program in
+non-volatile media into RAM as needed to execute a huge program from the
+small RAM.
+
+Terminology
+-----------
+
+ ``g_waitingforfill``:
+ An OS list that is used to hold the TCBs of tasks that are waiting
+ for a page fill.
+ ``g_pftcb``:
+ A variable that holds a reference to the TCB of the thread that is
+ currently be re-filled.
+ ``g_pgworker``:
+ The *process* ID of the thread that will perform the page fills.
+ ``pg_callback()``:
+ The callback function that is invoked from a driver when the fill is
+ complete.
+ ``pg_miss()``:
+ The function that is called from architecture-specific code to handle
+ a page fault.
+ ``TCB``:
+ Task Control Block
+
+NuttX Common Logic Design Description
+=====================================
+
+Initialization
+--------------
+
+The following declarations will be added.
+
+- ``g_waitingforfill``. A doubly linked list that will be used to
+ implement a prioritized list of the TCBs of tasks that are waiting
+ for a page fill.
+- ``g_pgworker``. The *process* ID of the thread that will perform
+ the page fills
+
+During OS initialization in ``sched/init/nx_start.c``, the following
+steps will be performed:
+
+- The ``g_waitingforfill`` queue will be initialized.
+- The special, page fill worker thread, will be started. The ``pid`` of
+ the page will worker thread will be saved in ``g_pgworker``. Note
+ that we need a special worker thread to perform fills; we cannot use
+ the "generic" worker thread facility because we cannot be assured
+ that all actions called by that worker thread will always be resident
+ in memory.
+
+Declarations for ``g_waitingforfill``, ``g_pgworker``, and other
+internal, private definitions will be provided in
+``sched/paging/paging.h``. All public definitions that should be used by
+the architecture-specific code will be available in
+``include/nuttx/page.h``. Most architecture-specific functions are
+declared in ``include/nuttx/arch.h``, but for the case of this paging
+logic, those architecture specific functions are instead declared in
+``include/nuttx/page.h``.
+
+Page Faults
+-----------
+
+**Page fault exception handling**. Page fault handling is performed by
+the function ``pg_miss()``. This function is called from
+architecture-specific memory segmentation fault handling logic. This
+function will perform the following operations:
+
+#. **Sanity checking**. This function will ASSERT if the currently
+ executing task is the page fill worker thread. The page fill worker
+ thread is how the page fault is resolved and all logic associated
+ with the page fill worker must be "`locked <#MemoryOrg>`__" and
+ always present in memory.
+#. **Block the currently executing task**. This function will call
+ ``up_block_task()`` to block the task at the head of the ready-to-run
+ list. This should cause an interrupt level context switch to the next
+ highest priority task. The blocked task will be marked with state
+ ``TSTATE_WAIT_PAGEFILL`` and will be retained in the
+ ``g_waitingforfill`` prioritized task list.
+#. **Boost the page fill worker thread priority**. Check the priority of
+ the task at the head of the ``g_waitingforfill`` list. If the
+ priority of that task is higher than the current priority of the page
+ fill worker thread, then boost the priority of the page fill worker
+ thread to that priority. Thus, the page fill worker thread will
+ always run at the priority of the highest priority task that is
+ waiting for a fill.
+#. **Signal the page fill worker thread**. Is there a page already being
+ filled? If not then signal the page fill worker thread to start
+ working on the queued page fill requests.
+
+When signaled from ``pg_miss()``, the page fill worker thread will be
+awakenend and will initiate the fill operation.
+
+**Input Parameters.** None -- The head of the ready-to-run list is
+assumed to be that task that caused the exception. The current task
+context should already be saved in the TCB of that task. No additional
+inputs are required.
+
+**Assumptions**.
+
+- It is assumed that this function is called from the level of an
+ exception handler and that all interrupts are disabled.
+- The ``pg_miss()`` must be "`locked <#MemoryOrg>`__" in memory.
+ Calling ``pg_miss()`` cannot cause a nested page fault.
+- It is assumed that currently executing task (the one at the head of
+ the ready-to-run list) is the one that cause the fault. This will
+ always be true unless the page fault occurred in an interrupt
+ handler. Interrupt handling logic must always be available and
+ "`locked <#MemoryOrg>`__" into memory so that page faults never come
+ from interrupt handling.
+- The architecture-specific page fault exception handling has already
+ verified that the exception did not occur from interrupt/exception
+ handling logic.
+- As mentioned above, the task causing the page fault must not be the
+ page fill worker thread because that is the only way to complete the
+ page fill.
+
+Fill Initiation
+---------------
+
+The page fill worker thread will be awakened on one of three conditions:
+
+- When signaled by ``pg_miss()``, the page fill worker thread will be
+ awakenend (see above),
+- From ``pg_callback()`` after completing last fill (when
+ ``CONFIG_PAGING_BLOCKINGFILL`` is defined... see below), or
+- A configurable timeout expires with no activity. This timeout can be
+ used to detect failure conditions such things as fills that never
+ complete.
+
+The page fill worker thread will maintain a static variable called
+``struct tcb_s *g_pftcb``. If no fill is in progress, ``g_pftcb`` will
+be NULL. Otherwise, it will point to the TCB of the task which is
+receiving the fill that is in progress.
+
+When awakened from ``pg_miss()``, no fill will be in progress and
+``g_pftcb`` will be NULL. In this case, the page fill worker thread will
+call ``pg_startfill()``. That function will perform the following
+operations:
+
+- Call the architecture-specific function ``up_checkmapping()`` to see
+ if the page fill still needs to be performed. In certain conditions,
+ the page fault may occur on several threads and be queued multiple
+ times. In this corner case, the blocked task will simply be restarted
+ (see the logic below for the case of normal completion of the fill
+ operation).
+- Call ``up_allocpage(tcb, &vpage)``. This architecture-specific
+ function will set aside page in memory and map to virtual address
+ (vpage). If all available pages are in-use (the typical case), this
+ function will select a page in-use, un-map it, and make it available.
+- Call the architecture-specific function ``up_fillpage()``. Two
+ versions of the up_fillpage function are supported -- a blocking and
+ a non-blocking version based upon the configuration setting
+ ``CONFIG_PAGING_BLOCKINGFILL``.
+
+ - If ``CONFIG_PAGING_BLOCKINGFILL`` is defined, then up_fillpage is
+ blocking call. In this case, ``up_fillpage()`` will accept only
+ (1) a reference to the TCB that requires the fill.
+ Architecture-specific context information within the TCB will be
+ sufficient to perform the fill. And (2) the (virtual) address of
+ the allocated page to be filled. The resulting status of the fill
+ will be provided by return value from ``up_fillpage()``.
+ - If ``CONFIG_PAGING_BLOCKINGFILL`` is defined, then up_fillpage is
+ non-blocking call. In this case ``up_fillpage()`` will accept an
+ additional argument: The page fill worker thread will provide a
+ callback function, ``pg_callback``. This function is non-blocking,
+ it will start an asynchronous page fill. After calling the
+ non-blocking ``up_fillpage()``, the page fill worker thread will
+ wait to be signaled for the next event -- the fill completion
+ event. The callback function will be called when the page fill is
+ finished (or an error occurs). The resulting status of the fill
+ will be providing as an argument to the callback functions. This
+ callback will probably occur from interrupt level.
+
+In any case, while the fill is in progress, other tasks may execute. If
+another page fault occurs during this time, the faulting task will be
+blocked, its TCB will be added (in priority order) to
+``g_waitingforfill``, and the priority of the page worker task may be
+boosted. But no action will be taken until the current page fill
+completes. NOTE: The IDLE task must also be fully
+`locked <#MemoryOrg>`__ in memory. The IDLE task cannot be blocked. It
+the case where all tasks are blocked waiting for a page fill, the IDLE
+task must still be available to run.
+
+The architecture-specific functions, ``up_checkmapping()``,
+``up_allocpage(tcb, &vpage)`` and ``up_fillpage(page, pg_callback)``
+will be prototyped in ``include/nuttx/arch.h``
+
+Fill Complete
+-------------
+
+For the blocking ``up_fillpage()``, the result of the fill will be
+returned directly from the call to ``up_fillpage``.
+
+For the non-blocking ``up_fillpage()``, the architecture-specific driver
+call the ``pg_callback()`` that was provided to ``up_fillpage()`` when
+the fill completes. In this case, the ``pg_callback()`` will probably be
+called from driver interrupt-level logic. The driver will provide the
+result of the fill as an argument to the callback function. NOTE:
+``pg_callback()`` must also be `locked <#MemoryOrg>`__ in memory.
+
+In this non-blocking case, the callback ``pg_callback()`` will perform
+the following operations when it is notified that the fill has
+completed:
+
+- Verify that ``g_pftcb`` is non-NULL.
+- Find the higher priority between the task waiting for the fill to
+ complete in ``g_pftcb`` and the task waiting at the head of the
+ ``g_waitingforfill`` list. That will be the priority of he highest
+ priority task waiting for a fill.
+- If this higher priority is higher than current page fill worker
+ thread, then boost worker thread's priority to that level. Thus, the
+ page fill worker thread will always run at the priority of the
+ highest priority task that is waiting for a fill.
+- Save the result of the fill operation.
+- Signal the page fill worker thread.
+
+Task Resumption
+---------------
+
+For the non-blocking ``up_fillpage()``, the page fill worker thread will
+detect that the page fill is complete when it is awakened with
+``g_pftcb`` non-NULL and fill completion status from ``pg_callback``. In
+the non-blocking case, the page fill worker thread will know that the
+page fill is complete when ``up_fillpage()`` returns.
+
+In this either, the page fill worker thread will:
+
+- Verify consistency of state information and ``g_pftcb``.
+- Verify that the page fill completed successfully, and if so,
+- Call ``up_unblocktask(g_pftcb)`` to make the task that just received
+ the fill ready-to-run.
+- Check if the ``g_waitingforfill`` list is empty. If not:
+
+ - Remove the highest priority task waiting for a page fill from
+ ``g_waitingforfill``,
+ - Save the task's TCB in ``g_pftcb``,
+ - If the priority of the thread in ``g_pftcb``, is higher in
+ priority than the default priority of the page fill worker thread,
+ then set the priority of the page fill worker thread to that
+ priority.
+ - Call ``pg_startfill()`` which will start the next fill (as
+ described above).
+
+- Otherwise,
+
+ - Set ``g_pftcb`` to NULL.
+ - Restore the default priority of the page fill worker thread.
+ - Wait for the next fill related event (a new page fault).
+
+Architecture-Specific Support Requirements
+==========================================
+
+Memory Organization
+-------------------
+
+**Memory Regions**. Chip specific logic will map the virtual and
+physical address spaces into three general regions:
+
+#. A .text region containing "`locked-in-memory <#MemoryOrg>`__" code
+ that is always available and will never cause a page fault. This
+ locked memory is loaded at boot time and remains resident for all
+ time. This memory regions must include:
+
+ - All logic for all interrupt paths. All interrupt logic must be
+ locked in memory because the design present here will not support
+ page faults from interrupt handlers. This includes the page fault
+ handling logic and ```pg_miss()`` <#PageFaults>`__ that is called
+ from the page fault handler. It also includes the
+ ```pg_callback()`` <#FillComplete>`__ function that wakes up the
+ page fill worker thread and whatever architecture-specific logic
+ that calls ``pg_callback()``.
+ - All logic for the IDLE thread. The IDLE thread must always be
+ ready to run and cannot be blocked for any reason.
+ - All of the page fill worker thread must be locked in memory. This
+ thread must execute in order to unblock any thread waiting for a
+ fill. It this thread were to block, there would be no way to
+ complete the fills!
+
+#. A .text region containing pages that can be assigned allocated,
+ mapped to various virtual addresses, and filled from some mass
+ storage medium.
+#. And a fixed RAM space for .bss, .text, and .heap.
+
+This memory organization is illustrated in the following table. Notice
+that:
+
+- There is a one-to-one relationship between pages in the virtual
+ address space and between pages of .text in the non-volatile mass
+ storage device.
+- There are, however, far fewer physical pages available than virtual
+ pages. Only a subset of physical pages will be mapped to virtual
+ pages at any given time. This mapping will be performed on-demand as
+ needed for program execution.
+
+============================= ============================ ====================
+SRAM Virtual Address Space Non-Volatile Storage
+============================= ============================ ====================
+. DATA .
+. Virtual Page *n* (*n* > *m*) Stored Page *n*
+. Virtual Page *n-1* Stored Page *n-1*
+DATA ... ...
+Physical Page *m* (*m* < *n*) ... ...
+Physical Page *m-1* ... ...
+... ... ...
+Physical Page *1* Virtual Page *1* Stored Page *1*
+Locked Memory Locked Memory Memory Resident
+============================= ============================ ====================
+
+**Example**. As an example, suppose that the size of the SRAM is 192K
+(as in the NXP LPC3131). And suppose further that:
+
+- The size of the locked, memory resident .text area is 32K, and
+- The size of the DATA area is 64K.
+- The size of one, managed page is 1K.
+- The size of the whole .text image on the non-volatile, mass storage
+ device is 1024K.
+
+Then, the size of the locked, memory resident code is 32K (*m*\ =32
+pages). The size of the physical page region is 96K (96 pages), and the
+size of the data region is 64 pages. And the size of the virtual paged
+region must then be greater than or equal to (1024-32) or 992 pages
+(*n*).
+
+**Building the Locked, In-Memory Image**. One way to accomplish this
+would be a two phase link:
+
+- In the first phase, create a partially linked objected containing all
+ interrupt/exception handling logic, the page fill worker thread plus
+ all parts of the IDLE thread (which must always be available for
+ execution).
+- All of the ``.text`` and ``.rodata`` sections of this partial link
+ should be collected into a single section.
+- The second link would link the partially linked object along with the
+ remaining object to produce the final binary. The linker script
+ should position the "special" section so that it lies in a reserved,
+ "non-swappable" region.
+
+Architecture-Specific Functions
+-------------------------------
+
+Most standard, architecture-specific functions are declared in
+``include/nuttx/arch.h``. However, for the case of this paging logic,
+the architecture specific functions are declared in
+``include/nuttx/page.h``. Standard, architecture-specific functions that
+should already be provided in the architecture port. The following are
+used by the common paging logic:
+
+.. c:function:: void up_block_task(FAR struct tcb_s *tcb, tstate_t task_state)
+
+ The currently executing task at the head of the ready to run list
+ must be stopped. Save its context and move it to the inactive list
+ specified by task_state. This function is called by the on-demand
+ paging logic in order to block the task that requires the page fill,
+ and to
+
+.. c:function:: void up_unblock_task(FAR struct tcb_s *tcb)
+
+ A task is currently in an inactive task list but has been prepped to
+ execute. Move the TCB to the ready-to-run list, restore its context,
+ and start execution. This function will be called
+
+New, additional functions that must be implemented just for on-demand
+paging support:
+
+.. c:function:: int up_checkmapping(FAR struct tcb_s *tcb)
+
+ The function ``up_checkmapping()`` returns an indication if the page
+ fill still needs to performed or not. In certain conditions, the page
+ fault may occur on several threads and be queued multiple times. This
+ function will prevent the same page from be filled multiple times.
+
+.. c:function:: int up_allocpage(FAR struct tcb_s *tcb, FAR void *vpage)
+
+ This architecture-specific function will set aside page in memory and
+ map to its correct virtual address. Architecture-specific context
+ information saved within the TCB will provide the function with the
+ information needed to identify the virtual miss address. This function
+ will return the allocated physical page address in ``vpage``. The size
+ of the underlying physical page is determined by the configuration
+ setting ``CONFIG_PAGING_PAGESIZE``. NOTE: This function must *always*
+ return a page allocation. If all available pages are in-use (the typical
+ case), then this function will select a page in-use, un-map it, and make
+ it available.
+
+.. c:function:: int up_fillpage(FAR struct tcb_s *tcb, FAR const void *vpage, void (*pg_callback)(FAR struct tcb_s *tcb, int result))
+
+ The actual filling of the page with data from the non-volatile, must be
+ performed by a separate call to the architecture-specific function,
+ ``up_fillpage()``. This will start asynchronous page fill. The common
+ paging logic will provide a callback function, ``pg_callback``, that
+ will be called when the page fill is finished (or an error occurs). This
+ callback is assumed to occur from an interrupt level when the device
+ driver completes the fill operation.
+
diff --git a/content/docs/latest/_sources/components/power.rst.txt b/content/docs/latest/_sources/components/power.rst.txt
new file mode 100644
index 0000000..3a41deb
--- /dev/null
+++ b/content/docs/latest/_sources/components/power.rst.txt
@@ -0,0 +1,241 @@
+================
+Power Management
+================
+
+NuttX supports a simple power management (PM) sub-system which:
+
+ - Monitors activity from drivers (and from other parts of the
+ system), and
+
+ - Provides hooks to place drivers (and the whole system) into
+ reduce power modes of operation.
+
+|figure|
+
+The PM sub-system integrates the MCU idle loop with a collection
+of device drivers to support:
+
+ - Reports of relevant driver or other system activity.
+
+ - Registration and callback mechanism to interface with
+ individual device drivers.
+
+ - IDLE time polling of overall driver activity.
+
+ - Coordinated, global, system-wide transitions to lower power
+ usage states.
+
+**Low Power Consumption States**. Various "sleep" and low power
+consumption states have various names and are sometimes used in
+conflicting ways. In the NuttX PM logic, we will use the following
+terminology:
+
+ ``NORMAL``
+ The normal, full power operating mode.
+ ``IDLE``
+ This is still basically normal operational mode, the system is,
+ however, ``IDLE`` and some simple simple steps to reduce power
+ consumption provided that they do not interfere with normal
+ Operation. Simply dimming the a backlight might be an example
+ some that that would be done when the system is idle.
+ ``STANDBY``
+ Standby is a lower power consumption mode that may involve more
+ extensive power management steps such has disabling clocking or
+ setting the processor into reduced power consumption modes. In
+ this state, the system should still be able to resume normal
+ activity almost immediately.
+ ``SLEEP``
+ The lowest power consumption mode. The most drastic power
+ reduction measures possible should be taken in this state. It
+ may require some time to get back to normal operation from
+ ``SLEEP`` (some MCUs may even require going through reset).
+
+.. c:enum:: pm_state_e
+
+ These various states are represented with type :c:enum:`pm_state_e`
+ in ``include/nuttx/power/pm.h``.
+
+**Power Management Domains**. Each PM interfaces includes a
+integer *domain* number. By default, only a single power domain is
+supported (``CONFIG_PM_NDOMAINS=1``). But that is configurable;
+any number of PM domains can be supported. Multiple PM domains
+might be useful, for example, if you would want to control power
+states associated with a network separately from power states
+associated with a user interface.
+
+Interfaces
+==========
+
+All PM interfaces are declared in the file ``include/nuttx/power/pm.h``.
+
+.. c:function:: void pm_initialize(void)
+
+ Called by MCU-specific one-time logic
+ at power-on-reset in order to initialize the power management
+ capabilities. This function must be called *very* early in the
+ initialization sequence *before* any other device drivers are
+ initialized (since they may attempt to register with the power
+ management subsystem).
+
+.. c:function:: int pm_register(FAR struct pm_callback_s *callbacks)
+
+ Called by a device driver in
+ order to register to receive power management event callbacks.
+ Refer to the :ref:`components/power:Callbacks` section for more
+ details.
+
+ :param callbacks:
+ An instance of :c:struct:`pm_callback_s`
+ providing the driver callback functions.
+
+ :return:
+ Zero (``OK``) on success; otherwise a negated
+ ``errno`` value is returned.
+
+.. c:function:: int pm_unregister(FAR struct pm_callback_s *callbacks)
+
+ Called by a device driver in
+ order to unregister previously registered power management event
+ callbacks. Refer to the :ref:`components/power:Callbacks` section for
+ more details.
+
+ **Input Parameters:**
+
+ :param callbacks:
+ An instance of :c:struct:`pm_callback_s`
+ providing the driver callback functions.
+
+ :return:
+ Zero (``OK``) on success; otherwise a negated
+ ``errno`` value is returned.
+
+.. c:function:: void pm_activity(int domain, int priority)
+
+ Called by a device driver to
+ indicate that it is performing meaningful activities (non-idle).
+ This increment an activity count and/or will restart a idle timer
+ and prevent entering reduced power states.
+
+ :param domain: Identifies the domain of the new PM activity
+ :param priority:
+ Activity priority, range 0-9. Larger values correspond to
+ higher priorities. Higher priority activity can prevent the
+ system from entering reduced power states for a longer period
+ of time. As an example, a button press might be higher priority
+ activity because it means that the user is actively interacting
+ with the device.
+
+ **Assumptions:** This function may be called from an interrupt
+ handler (this is the ONLY PM function that may be called from an
+ interrupt handler!).
+
+.. c:function:: enum pm_state_e pm_checkstate(int domain)
+
+ Called from the MCU-specific
+ IDLE loop to monitor the power management conditions. This
+ function returns the "recommended" power management state based on
+ the PM configuration and activity reported in the last sampling
+ periods. The power management state is not automatically changed,
+ however. The IDLE loop must call :c:func:`pm_changestate` in order to
+ make the state change.
+
+ These two steps are separated because the platform-specific IDLE
+ loop may have additional situational information that is not
+ available to the PM sub-system. For example, the IDLE loop may
+ know that the battery charge level is very low and may force lower
+ power states even if there is activity.
+
+ NOTE: That these two steps are separated in time and, hence, the
+ IDLE loop could be suspended for a long period of time between
+ calling :c:func:`pm_checkstate` and :c:func:`pm_changestate`. The IDLE
+ loop may need to make these calls atomic by either disabling
+ interrupts until the state change is completed.
+
+ :param domain: Identifies the PM domain to check
+ :return: The recommended power management state.
+
+.. c:function:: int pm_changestate(int domain, enum pm_state_e newstate)
+
+ This function is used by platform-specific power
+ management logic. It will announce the power management power
+ management state change to all drivers that have registered for
+ power management event callbacks.
+
+ :param domain: Identifies the domain of the new PM state
+ :param newstate: Identifies the new PM state
+
+ :return:
+ 0 (``OK``) means that the callback function
+ for all registered drivers returned ``OK`` (meaning that they
+ accept the state change). Non-zero means that one of the drivers
+ refused the state change. In this case, the system will revert to
+ the preceding state.
+
+ **Assumptions:** It is assumed that interrupts are disabled when
+ this function is called. This function is probably called from the
+ IDLE loop... the lowest priority task in the system. Changing
+ driver power management states may result in renewed system
+ activity and, as a result, can suspend the IDLE thread before it
+ completes the entire state change unless interrupts are disabled
+ throughout the state change.
+
+Callbacks
+=========
+
+
+.. c:struct:: pm_callback_s
+
+ This struct includes the pointers to the driver
+ callback functions. This structure is defined
+ ``include/nuttx/power/pm.h``. These callback functions can be used
+ to provide power management information to the driver.
+
+.. c:var:: int (*prepare)(FAR struct pm_callback_s *cb, int domain, enum pm_state_e pmstate)
+
+ Request the driver to prepare for a new power
+ state. This is a warning that the system is about to enter into a
+ new power state. The driver should begin whatever operations that
+ may be required to enter power state. The driver may abort the
+ state change mode by returning a non-zero value from the callback
+ function.
+
+ :param cb:
+ Returned to the driver. The driver version of the callback
+ structure may include additional, driver-specific state data at
+ the end of the structure.
+ :param domain:
+ Identifies the activity domain of the state change
+ :param pmstate:
+ Identifies the new PM state
+
+ :return:
+ Zero (``OK``) means the event was successfully
+ processed and that the driver is prepared for the PM state change.
+ Non-zero means that the driver is not prepared to perform the
+ tasks needed achieve this power setting and will cause the state
+ change to be aborted. NOTE: The ``prepare()`` method will also be
+ called when reverting from lower back to higher power consumption
+ modes (say because another driver refused a lower power state
+ change). Drivers are not permitted to return non-zero values when
+ reverting back to higher power consumption modes!
+
+.. c:var:: void (*notify)(FAR struct pm_callback_s *cb, int domain, enum pm_state_e pmstate)
+
+ Notify the driver of new power state. This
+ callback is called after all drivers have had the opportunity to
+ prepare for the new power state.
+
+ :param cb:
+ Returned to the driver. The driver version of the callback
+ structure may include additional, driver-specific state data at
+ the end of the structure.
+ :param domain:
+ Identifies the activity domain of the state change
+ :param pmstate:
+ Identifies the new PM state
+
+ The driver already agreed to transition
+ to the low power consumption state when when it returned ``OK`` to
+ the :c:var:`prepare` call.
+
+.. |figure| image:: pm.png
diff --git a/content/docs/latest/_sources/components/socketcan.rst.txt b/content/docs/latest/_sources/components/socketcan.rst.txt
new file mode 100644
index 0000000..9c3b71b
--- /dev/null
+++ b/content/docs/latest/_sources/components/socketcan.rst.txt
@@ -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
+
diff --git a/content/docs/latest/_sources/components/syslog.rst.txt b/content/docs/latest/_sources/components/syslog.rst.txt
new file mode 100644
index 0000000..58b1467
--- /dev/null
+++ b/content/docs/latest/_sources/components/syslog.rst.txt
@@ -0,0 +1,511 @@
+======
+SYSLOG
+======
+
+
+SYSLOG Interfaces
+=================
+
+Standard SYSLOG Interfaces
+--------------------------
+
+The NuttX SYSLOG is an architecture for getting debug and status
+information from the system. The syslogging interfaces are defined
+in the header file ``include/syslog.h``. The primary interface to
+SYSLOG sub-system is the function ``syslog()`` and, to a lesser
+extent, its companion ``vsyslog()``:
+
+.. c::function:: int syslog(int priority, FAR const IPTR char *format, ...);
+
+ Generates a log message. The
+ priority argument is formed by ORing the facility and the level
+ values (see ``include/syslog.h``). The remaining arguments are a
+ format, as in ``printf()`` and any arguments to the format.
+
+ The NuttX implementation does not support any special formatting
+ characters beyond those supported by ``printf()``.
+
+.. c::function:: void vsyslog(int priority, FAR const IPTR char *src, va_list ap);
+
+ Performs the same task as :c:func:`syslog`
+ with the difference that it takes a set of arguments which have
+ been obtained using the ``stdarg`` variable argument list macros.
+
+.. c::function:: int setlogmask(int mask);
+
+ The additional setlogmask() interface can use use to filter SYSLOG output.
+ This function sets the logmask and returns the previous mask.
+ If the mask argument is zero, the current logmask is not modified.
+
+ The SYSLOG priorities are: ``LOG_EMERG``, ``LOG_ALERT``, ``LOG_CRIT``,
+ ``LOG_ERR``, ``LOG_WARNING``, ``LOG_NOTICE``, ``LOG_INFO``, and ``LOG_DEBUG``.
+ The bit corresponding to a priority ``p`` is ``LOG_MASK(p)``; ``LOG_UPTO(p)``
+ provides the mask of all priorities in the above list up to and including ``p``.
+
+ Per *OpenGroup.org* "If the ``maskpri`` argument is 0,
+ the current log mask is not modified." In this implementation,
+ the value zero is permitted in order to disable all SYSLOG levels.
+
+ .. note::
+ REVISIT: Per POSIX the SYSLOG mask should be a per-process value but
+ in NuttX, the scope of the mask is dependent on the nature of the build:
+
+ - *Flat Build*: There is one, global SYSLOG mask that controls
+ all output.
+
+ - *Protected Build*: There are two SYSLOG masks. One within the
+ kernel that controls only kernel output. And one in user-space
+ that controls only user SYSLOG output.
+
+ - *Kernel Build*: The kernel build is compliant with the POSIX
+ requirement: There will be one mask for for each user process,
+ controlling the SYSLOG output only form that process. There
+ will be a separate mask accessible only in the kernel code to
+ control kernel SYSLOG output.
+
+The above are all standard interfaces as defined at
+`OpenGroup.org <http://pubs.opengroup.org/onlinepubs/009695399/functions/closelog.html>`__.
+Those interfaces are available for use by application software.
+The remaining interfaces discussed in this section are non-standard, OS-internal interfaces.
+
+Debug Interfaces
+----------------
+
+In NuttX, syslog output is really synonymous to debug output and,
+therefore, the debugging interface macros defined in the header
+file ``include/debug.h`` are also syslogging interfaces. Those
+macros are simply wrappers around ``syslog()``. The debugging
+interfaces differ from the syslog interfaces in that:
+
+ - They do not take a priority parameter; the priority is inherent
+ in the debug macro name.
+
+ - They decorate the output stream with information such as the
+ file name
+
+ - They can each be disabled via configuration options.
+
+Each debug macro has a base name that represents the priority and
+a prefix that represents the sub-system. Each macro is
+individually initialized by both priority and sub-system. For
+example, ``uerr()`` is the macro used for error level messages
+from the USB subsystem and is enabled with
+``CONFIG_DEBUG_USB_ERROR``.
+
+The base debug macro names, their priority, and configuration
+variable are summarized below:
+
+- ``info()``. The ``info()`` macro is the lowest priority
+ (``LOG_INFO``) and is intended to provide general information
+ about the flow of program execution so that you can get an
+ overview of the behavior of the program. ``info()`` is often
+ very chatty and voluminous and usually more information than
+ you may want to see. The ``info()`` macro is controlled via
+ CONFIG_DEBUG_subsystem_INFO
+
+- ``warn()``. The ``warn()`` macro has medium priority
+ (``LOG_WARN``) and is controlled by
+ ``CONFIG_DEBUG_subsystem_WARN``. The ``warn()`` is intended to
+ note exceptional or unexpected conditions that might be
+ potential errors or, perhaps, minor errors that easily
+ recovered.
+
+- ``err()``. This is a high priority debug macro (``LOG_ERROR``)
+ and controlled by ``CONFIG_DEBUG_subsystem_ERROR``. The
+ ``err()`` is reserved to indicate important error conditions.
+
+- ``alert()``. The highest priority debug macro (``LOG_EMERG``)
+ and is controlled by ``CONFIG_DEBUG_ALERT``. The ``alert()``
+ macro is reserved for use solely by assertion and crash
+ handling logic. It also differs from the other macros in that
+ it cannot be enabled or disabled per subsystem.
+
+SYSLOG Channels
+===============
+
+SYSLOG Channel Interfaces
+-------------------------
+
+In the NuttX SYSLOG implementation, the underlying device logic
+the supports the SYSLOG output is referred to as a SYSLOG
+*channel*. Each SYSLOG channel is represented by an interface
+defined in ``include/nuttx/syslog/syslog.h``:
+
+.. code-block:: c
+
+ /* This structure provides the interface to a SYSLOG device */
+
+ typedef CODE int (*syslog_putc_t)(int ch);
+ typedef CODE int (*syslog_flush_t)(void);
+
+ struct syslog_channel_s
+ {
+ /* I/O redirection methods */
+
+ syslog_putc_t sc_putc; /* Normal buffered output */
+ syslog_putc_t sc_force; /* Low-level output for interrupt handlers */
+ syslog_flush_t sc_flush; /* Flush buffered output (on crash) */
+
+ /* Implementation specific logic may follow */
+ };
+
+The channel interface is instantiated by calling
+:c:func:`syslog_channel()`.
+
+.. c:function:: int syslog_channel(FAR const struct syslog_channel_s *channel);
+
+ Configure the SYSLOG function to use the provided
+ channel to generate SYSLOG output.
+
+ ``syslog_channel()`` is a non-standard, internal OS interface and
+ is not available to applications. It may be called numerous times
+ as necessary to change channel interfaces. By default, all system
+ log output goes to console (``/dev/console``).
+
+ :param channel: Describes the interface to the channel to be used.
+
+ :return:
+ Zero (OK)is returned on success. A negated errno value is
+ returned on any failure.
+
+SYSLOG Channel Initialization
+-----------------------------
+
+The initial, default SYSLOG channel is established with statically
+initialized global variables so that some level of SYSLOG output
+may be available immediately upon reset. This initialized data is
+in the file ``drivers/syslog/syslog_channel.c``. The initial
+SYSLOG capability is determined by the selected SYSLOG channel:
+
+- *In-Memory Buffer (RAMLOG)*. Full SYSLOG capability as
+ available at reset.
+
+- *Serial Console*. If the serial implementation provides the
+ low-level character output function ``up_putc()``, then that
+ low level serial output is available as soon as the serial
+ device has been configured.
+
+- For all other SYSLOG channels, all SYSLOG output goes to the
+ bit- bucket until the SYSLOG channel device has been
+ initialized.
+
+The syslog channel device is initialized when the bring-up logic
+calls :c:func:`syslog_initialize()`.
+
+.. c:function:: int syslog_initialize(void)
+
+ .. code-block:: c
+
+ #include <nuttx/syslog/syslog.h>
+ #ifndef CONFIG_ARCH_SYSLOG
+ int syslog_initialize(void);
+ #else
+ # define syslog_initialize()
+ #endif
+
+ One power up, the SYSLOG facility is non-existent
+ or limited to very low-level output. This function is called later
+ in the initialization sequence after full driver support has been
+ initialized. It installs the configured SYSLOG drivers and enables
+ full SYSLOG capability.
+
+ This function performs these basic operations:
+
+ - Initialize the SYSLOG device
+
+ - Call :c:func:`syslog_channel` to begin using that device.
+
+ - If ``CONFIG_ARCH_SYSLOG`` is selected, then the
+ architecture-specific logic will provide its own SYSLOG device
+ initialize which must include as a minimum a call to
+ :c:func:`syslog_channel` to use the device.
+
+ :return:
+ Zero (``OK``) is returned on success; a
+ negated ``errno`` value is returned on any failure.
+
+Different types of SYSLOG devices have different OS initialization
+requirements. Some are available immediately at reset, some are
+available after some basic OS initialization, and some only after
+OS is fully initialized.
+
+There are other types of SYSLOG channel devices that may require
+even further initialization. For example, the file SYSLOG channel
+(described below) cannot be initialized until the necessary file
+systems have been mounted.
+
+Interrupt Level SYSLOG Output
+-----------------------------
+
+As a general statement, SYSLOG output only supports *normal*
+output from NuttX tasks. However, for debugging purposes, it is
+also useful to get SYSLOG output from interrupt level logic. In an
+embedded system, that is often where the most critical operations
+are performed.
+
+There are three conditions under which SYSLOG output generated
+from interrupt level processing can a included the SYSLOG output
+stream:
+
+ #. **Low-Level Serial Output**. If you are using a SYSLOG console
+ channel (``CONFIG_SYSLOG_CONSOLE``) and if the underlying
+ architecture supports the low-level ``up_putc()``
+ interface(\ ``CONFIG_ARCH_LOWPUTC``), then the SYSLOG logic
+ will direct the output to ``up_putc()`` which is capable of
+ generating the serial output within the context of an interrupt
+ handler.
+
+ There are a few issues in doing this however:
+
+ - ``up_putc()`` is able to generate debug output in any
+ context because it disables serial interrupts and polls the
+ hardware directly. These polls may take many milliseconds
+ and during that time, all interrupts are disable within the
+ interrupt handler. This, of course, interferes with the
+ real-time behavior of the RTOS.
+
+ - The output generated by ``up_putc()`` is immediate and in
+ real-time. The normal SYSLOG output, on the other hand, is
+ buffered in the serial driver and may be delayed with
+ respect to the immediate output by many lines. Therefore,
+ the interrupt level SYSLOG output provided through
+ ``up_putc()`` is grossly out of synchronization with other
+ debug output
+
+ #. **In-Memory Buffering**. If the RAMLOG SYSLOG channel is
+ supported, then all SYSLOG output is buffered in memory.
+ Interrupt level SYSLOG output is no different than normal
+ SYSLOG output in this case.
+
+ #. **Serialization Buffer**. A final option is the use of an
+ *interrupt buffer* to buffer the interrupt level SYSLOG output.
+ In this case:
+
+ - SYSLOG output generated from interrupt level process in not
+ sent to the SYSLOG channel immediately. Rather, it is
+ buffered in the interrupt serialization buffer.
+
+ - Later, when the next normal syslog output is generated, it
+ will first empty the content of the interrupt buffer to the
+ SYSLOG device in the proper context. It will then be
+ followed by the normal syslog output. In this case, the
+ interrupt level SYSLOG output will interrupt the normal
+ output stream and the interrupt level SYSLOG output will be
+ inserted into the correct position in the SYSLOG output when
+ the next normal SYSLOG output is generated.
+
+The SYSLOG interrupt buffer is enabled with
+``CONFIG_SYSLOG_INTBUFFER``. When the interrupt buffer is
+enabled, you must also provide the size of the interrupt buffer
+with ``CONFIG_SYSLOG_INTBUFSIZE``.
+
+SYSLOG Channel Options
+======================
+
+SYSLOG Console Device
+---------------------
+
+The typical SYSLOG device is the system console. If you are using
+a serial console, for example, then the SYSLOG output will appear
+on that serial port.
+
+This SYSLOG channel is automatically selected by
+``syslog_initialize()`` in the LATE initialization phase based on
+configuration options. The configuration options that affect this
+channel selection include:
+
+ - ``CONFIG_DEV_CONSOLE``. This setting indicates that the system
+ supports a console device, i.e., that the character device
+ ``/dev/console`` exists.
+
+ - ``CONFIG_SERIAL_CONSOLE``. This configuration option is
+ automatically selected when a UART or USART is configured as
+ the system console. There is no user selection.
+
+ - ``CONFIG_SYSLOG_CONSOLE``. This configuration option is
+ manually selected from the SYSLOG menu. This is the option that
+ actually enables the SYSLOG console device. It depends on
+ ``CONFIG_DEV_CONSOLE``.
+
+ - ``CONFIG_ARCH_LOWPUTC``. This is an indication from the
+ architecture configuration that the platform supports the
+ ``up_putc()`` interface. ``up_putc()`` is a very low level UART
+ interface that can even be used from interrupt handling.
+
+Interrupt level SYSLOG output will be lost unless: (1) the
+interrupt buffer is enabled to support serialization, or (2) a
+serial console is used and ``up_putc()`` is supported.
+
+.. note::
+ The console channel uses the fixed character device at
+ ``/dev/console``. The console channel is not synonymous with
+ ``stdout`` (or file descriptor 1). ``stdout`` is the current
+ output from a task when, say, ``printf()`` if used. Initially,
+ ``stdout`` does, indeed, use the ``/dev/console`` device. However,
+ ``stdout`` may subsequently be redirected to some other device or
+ file. This is always the case, for example, when a transient
+ device is used for a console -- such as a USB console or a Telnet
+ console. The SYSLOG channel is not redirected as ``stdout`` is;
+ the SYSLOG channel will stayed fixed (unless it is explicitly
+ changed via ``syslog_channel()``).
+
+References: ``drivers/syslog/syslog_consolechannel.c`` and
+``drivers/syslog/syslog_device.c``
+
+SYSLOG Character Device
+-----------------------
+
+The system console device, ``/dev/console``, is a character driver
+with some special properties. However, any character driver may be
+used as the SYSLOG output channel. For example, suppose you have a
+serial console on ``/dev/ttyS0`` and you want SYSLOG output on
+``/dev/ttyS1``. Or suppose you support only a Telnet console but
+want to capture debug output ``/dev/ttyS0``.
+
+This SYSLOG device channel is selected with ``CONFIG_SYSLOG_CHAR``
+and has no other dependencies. Differences from the SYSLOG console
+channel include:
+
+ - ``CONFIG_SYSLOG_DEVPATH``. This configuration option string
+ must be set provide the full path to the character device to be
+ used.
+
+ - The forced SYSLOG output always goes to the bit-bucket. This
+ means that interrupt level SYSLOG output will be lost unless
+ the interrupt buffer is enabled to support serialization.
+
+ - ``CONFIG_SYSLOG_CHAR_CRLF``. If ``CONFIG_SYSLOG_CHAR_CRLF`` is
+ selected, then linefeeds in the SYSLOG output will be expanded
+ to Carriage Return plus Linefeed. Since the character device is
+ not a console device, the addition of carriage returns to line
+ feeds would not be performed otherwise. You would probably want
+ this expansion if you use a serial terminal program with the
+ character device output.
+
+References: ``drivers/syslog/syslog_devchannel.c`` and
+``drivers/syslog/syslog_device.c``
+
+SYSLOG File Device
+------------------
+
+Files can also be used as the sink for SYSLOG output. There is,
+however, a very fundamental difference in using a file as opposed
+the system console, a RAM buffer, or character device: You must
+first mount the file system that supports the SYSLOG file. That
+difference means that the file SYSLOG channel cannot be supported
+during the boot-up phase but can be instantiated later when board
+level logic configures the application environment, including
+mounting of the file systems.
+
+The interface ``syslog_file_channel()`` is used to configure the
+SYSLOG file channel:
+
+.. c:function:: int syslog_file_channel(FAR const char *devpath);
+
+ Configure to use a file in a mounted file system
+ at ``devpath`` as the SYSLOG channel.
+
+ This tiny function is simply a wrapper around
+ ``syslog_dev_initialize()`` and ``syslog_channel()``. It calls
+ ``syslog_dev_initialize()`` to configure the character file at
+ ``devpath`` then calls ``syslog_channel()`` to use that device as
+ the SYSLOG output channel.
+
+ File SYSLOG channels differ from other SYSLOG channels in that
+ they cannot be established until after fully booting and mounting
+ the target file system. This function would need to be called from
+ board-specific bring-up logic AFTER mounting the file system
+ containing ``devpath``.
+
+ SYSLOG data generated prior to calling ``syslog_file_channel()``
+ will, of course, not be included in the file.
+
+ NOTE interrupt level SYSLOG output will be lost in this case
+ unless the interrupt buffer is used.
+
+ :param devpath:
+ The full path to the file to be used for SYSLOG
+ output. This may be an existing file or not. If the file
+ exists, ``syslog_file_channel()`` will append new SYSLOG data
+ to the end of the file. If it does not, then
+ ``syslog_file_channel()`` will create the file.
+
+ :return:
+ Zero (``OK``) is returned on success; a
+ negated ``errno`` value is returned on any failure.
+
+ References: ``drivers/syslog/syslog_filechannel.c``,
+ ``drivers/syslog/syslog_device.c``, and
+ ``include/nuttx/syslog/syslog.h``.
+
+SYSLOG RAMLOG Device
+--------------------
+
+The RAMLOG is a standalone feature that can be used to buffer any
+character data in memory. There are, however, special
+configurations that can be used to configure the RAMLOG as a
+SYSLOG channel. The RAMLOG functionality is described in a more
+general way in the following paragraphs.
+
+RAM Logging Device
+==================
+
+The RAM logging driver is a driver that was intended to support
+debugging output (SYSLOG) when the normal serial output is not
+available. For example, if you are using a Telnet or USB serial
+console, the debug output will get lost -- or worse. For example,
+what if you want to debug the network over Telnet?
+The RAM logging driver can also accept debug output data from
+interrupt handler with no special serialization buffering. As an
+added benefit, the RAM logging driver is much less invasive. Since
+no actual I/O is performed with the debug output is generated, the
+RAM logger tends to be much faster and will interfere much less
+when used with time critical drivers.
+
+The RAM logging driver is similar to a pipe in that it saves the
+debugging output in a circular buffer in RAM. It differs from a
+pipe in numerous details as needed to support logging.
+
+This driver is built when ``CONFIG_RAMLOG`` is defined in the
+Nuttx configuration.
+
+``dmesg`` command
+-----------------
+
+When the RAMLOG (with SYSLOG) is enabled, a new NuttShell (NSH)
+command will appear: ``dmesg``. The ``dmesg`` command will dump
+the contents of the circular buffer to the console (and also clear
+the circular buffer).
+
+RAMLOG Configuration options
+----------------------------
+
+- ``CONFIG_RAMLOG``: Enables the RAM logging feature
+
+- ``CONFIG_RAMLOG_SYSLOG``: Use the RAM logging device for the
+ SYSLOG interface. If this feature is enabled, then all debug
+ output will be re-directed to the circular buffer in RAM. This
+ RAM log can be viewed from NSH using the ``dmesg`` command.
+ NOTE: Unlike the limited, generic character driver SYSLOG
+ device, the RAMLOG *can* be used to capture debug output from
+ interrupt level handlers.
+
+- ``CONFIG_RAMLOG_NPOLLWAITERS``: The number of threads than can
+ be waiting for this driver on ``poll()``. Default: 4
+
+- ``CONFIG_RAMLOG_BUFSIZE``: The size of the circular buffer to
+ use. Default: 1024 bytes.
+
+Other miscellaneous settings
+
+- ``CONFIG_RAMLOG_CRLF``: Pre-pend a carriage return before every
+ linefeed that goes into the RAM log.
+
+- ``CONFIG_RAMLOG_NONBLOCKING``: Reading from the RAMLOG will
+ never block if the RAMLOG is empty. If the RAMLOG is empty,
+ then zero is returned (usually interpreted as end-of-file). If
+ you do not define this, the NSH ``dmesg`` command will lock up
+ when called! So you probably do want this!
+
+- ``CONFIG_RAMLOG_NPOLLWAITERS``: The maximum number of threads
+ that may be waiting on the poll method.
diff --git a/content/docs/latest/_sources/contributing/coding_style.rst.txt b/content/docs/latest/_sources/contributing/coding_style.rst.txt
new file mode 100644
index 0000000..5f0aeda
--- /dev/null
+++ b/content/docs/latest/_sources/contributing/coding_style.rst.txt
@@ -0,0 +1,2656 @@
+=================
+C Coding Standard
+=================
+
+NuttX follows a specific coding style which needs to be followed at all times
+a contribution to be accepted. Please read this document before working on
+new code so that you can follow the style from the start. To check your code
+for conformance to the coding style, you should use the `nxstyle <#nxstyle>`_
+tool included under ``tools/`` in the main NuttX repository.
+
+*******************
+General Conventions
+*******************
+
+File Organization
+=================
+
+**File Extensions** Use the ``.h`` extension for C header files
+and ``.c`` for C source files.
+
+**File header**. Every C, C++, make file, or script begins with a file header.
+That file header is enclosed with a *block comment* (see below). Within the
+block comment, the following must appear:
+
+ - The relative path to the file from the top-level directory.
+ - An optional, one-line description of the file contents.
+ - A blank line
+ - A copyright notice indented two additional spaces
+ - A line identifying the author and contact information with the
+ same indentation as the copyright notice.
+ - A blank line
+ - NuttX standard Apache 2.0 licensing information as provided in
+ the `appendix <#appndxa>`__.
+
+**Sample File Headers**. Sample file headers are provided in an
+`Appendix <#appndxa>`__ 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 ``COPYING`` file to indicate any variations from
+Apache 2.0 licensing.
+
+**Grouping**. 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 *block comment* identifying the grouping.
+
+**Block Comments**. Each grouping in the file is separated with a
+*block comment*. The block comment consists of:
+
+- A line that consists of the opening C comment (``/*``) followed
+ by a series of asterisks extending to the length of the line
+ (usually to column 78).
+- The name of the grouping, starting at column 4. An asterisk
+ preceives the name of the grouping in column 1.
+- A line that consists of the closing C comment (``*/``) at the
+ end of the line (usually column 78) preceded by a series of
+ asterisks extending to column 1.
+
+**Examples of Block Comments**. See `Appendix A <#appndxa>`__ for
+examples of block comments.
+
+**Order of Groupings**. The following groupings should appear in
+all C source files in the following order:
+
+ #. Included Files
+ #. Pre-processor Definitions
+ #. Private Types (definitions)
+ #. Private Function Prototypes (declarations)
+ #. Private Data (definitions)
+ #. Public Data (definitions)
+ #. Private Functions (definitions)
+ #. Public Functions (definitions)
+
+The following groupings should appear in all C header files in the
+following order:
+
+ #. Included Files
+ #. Pre-processor Definitions
+ #. Public Types (definitions)
+ #. Public Data (declarations)
+ #. Inline Functions (definitions)
+ #. Public Function Prototypes (declarations)
+
+**Large vs. Small Files**. 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!
+
+**Header File Idempotence**. 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.
+
+- 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::
+
+ #ifndef __INCLUDE_NUTTX_ARCH_H
+ #define __INCLUDE_NUTTX_ARCH_H
+
+ 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.
+
+- Then conditional compilation is closed at the fine line of the
+ header file with::
+
+ #endif /* __INCLUDE_NUTTX_ARCH_H */
+
+**Forming Guard Names**. 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
+``__`` and ``_`` replaces each character that would otherwise be
+invalid in a macro name. So, for example, ``__INCLUDE_NUTTX_ARCH_H``
+corresponds to the header file ``include/nuttx/arch.h``
+
+**Deoxygen Information**. NuttX does not use Deoxygen for
+documentation and no file should contain Doxygen tags or Doxygen
+style comments.
+
+**Sample File Formats**. C source and header file templates are
+provided in an `Appendix <#appndxa>`__ to this document.
+
+Lines
+=====
+
+**Line Endings**. Files should be formatted with the newline
+character (``\n``) as the line ending (Unix-style line endings)
+and specifically *not* the carriage return, newline sequence
+(``\r\n``) 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 (``\n``). This avoids the
+*"No newline at end of file"* warning generated by certain tools.
+
+**Line Width**. 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.
+
+**Line Wrapping**.
+
+.. error:: This is incorrect
+
+ .. code-block:: c
+
+ 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);
+
+.. hint:: This is correct
+
+ .. code-block:: c
+
+ 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 =
... 90308 lines suppressed ...