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

Documentaion: migrate system/readme

Browse Source
This commit is contained in:
raiden00pl 2023-10-24 12:23:16 +02:00 committed by Alan Carvalho de Assis
parent a9a1d719da
commit cffc74c664
16 changed files with 1009 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
Documentation/applications/system/cdcacm/index.rst Normal file
View File

@ -0,0 +1,38 @@
======================================
``cdcacm`` USB CDC/ACM Device Commands
======================================
This very simple add-on allows the USB CDC/ACM serial device can be dynamically
connected and disconnected from a host. This add-on can only be used as an NSH
built-in command. If built-in, then two new NSH commands will be supported:
1. ``sercon`` – Connect the CDC/ACM serial device
2. ``serdis`` – Disconnect the CDC/ACM serial device
Configuration prerequisites (not complete):
- ``CONFIG_USBDEV=y`` – USB device support must be enabled
- ``CONFIG_CDCACM=y`` – The CDC/ACM driver must be built
Configuration options specific to this add-on:
- ``CONFIG_SYSTEM_CDCACM_DEVMINOR`` – The minor number of the CDC/ACM device,
i.e., the ``x`` in ``/dev/ttyACMx``.
If ``CONFIG_USBDEV_TRACE`` is enabled (or ``CONFIG_DEBUG_FEATURES`` and
``CONFIG_DEBUG_USB``, or ``CONFIG_USBDEV_TRACE``), then the add-on code will also
initialize the USB trace output. The amount of trace output can be controlled
using:
- ``CONFIG_SYSTEM_CDCACM_TRACEINIT`` – Show initialization events.
- ``CONFIG_SYSTEM_CDCACM_TRACECLASS`` – Show class driver events.
- ``CONFIG_SYSTEM_CDCACM_TRACETRANSFERS`` – Show data transfer events.
- ``CONFIG_SYSTEM_CDCACM_TRACECONTROLLER`` – Show controller events.
- ``CONFIG_SYSTEM_CDCACM_TRACEINTERRUPTS`` – Show interrupt-related events.
**Note**: This add-on is only enables or disable USB CDC/ACM via the NSH
``sercon`` and ``serdis`` command. It will enable and disable tracing per the
settings before enabling and after disabling the CDC/ACM device. It will not,
however, monitor buffered trace data in the interim. If ``CONFIG_USBDEV_TRACE`` is
defined (and the debug options are not), other application logic will need to
monitor the buffered trace data.

22
Documentation/applications/system/cfgdata/index.rst Normal file
View File

@ -0,0 +1,22 @@
===========================
``cfgdata`` Cfgdata Command
===========================
This application provides a command line interface for managing platform
specific configdata within the ``/dev/config`` device.
Usage::
config <cmd> [arguments]
Where ``<cmd>`` is one of:
- ``all`` – show all config entries
- ``print`` – display a specific config entry
- ``set`` – set or change a config entry
- ``unset`` – delete a config entry
Author: Ken Pettit
Date: 18 December 2018

71
Documentation/applications/system/composite/index.rst Normal file
View File

@ -0,0 +1,71 @@
===========================================
``composite`` USB Composite Device Commands
===========================================
This logic adds a NSH command to control a USB composite device. The only
supported devices in the composite are CDC/ACM serial and a USB mass storage
device. Which devices are enclosed in a composite device is configured with an
array of configuration-structs, handed over to the function
``composite_initialize()``.
Required overall configuration:
Enable the USB Support of your Hardware / Processor e.g. ``SAMV7_USBDEVHS=y``
- ``CONFIG_USBDEV=y`` – USB device support.
- ``CONFIG_USBDEV_COMPOSITE=y`` – USB composite device support.
- ``CONFIG_COMPOSITE_IAD=y`` – Interface associate descriptor needed.
- ``CONFIG_CDCACM=y`` – USB CDC/ACM serial device support.
- ``CONFIG_CDCACM_COMPOSITE=y`` – USB CDC/ACM serial composite device support.
The interface-, string-descriptor- and endpoint-numbers are configured via the
configuration-structs as noted above. The CDC/ACM serial device needs three
endpoints; one interrupt-driven and two bulk endpoints.
- ``CONFIG_USBMSC=y`` – USB mass storage device support.
- ``CONFIG_USBMSC_COMPOSITE=y`` – USB mass storage composite device support.
Like the configuration for the CDC/ACM, the descriptor- and endpoint-numbers are
configured via the configuration struct.
Depending on the configuration struct you need to configure different vendor-
and product-IDs. Each ``VID``/``PID`` is unique to a device and thus to a dedicated
configuration.
Linux tries to detect the device types and installs default drivers if the
``VID``/``PID`` pair is unknown.
Windows insists on a known and installed configuration. With an Atmel hardware
and Atmel-Studio or the Atmel-USB-drivers installed, you can test your
configuration with Atmel Example Vendor- and Product-IDs.
If you have a USBMSC and a CDC/ACM configured in your combo, then you can try to
use
- ``VID = 0x03EB`` (ATMEL)
- ``PID = 0x2424`` (ASF Example with MSC and CDC)
If for example you try to test a configuration with up to seven CDCs, then
- ``VID = 0x03EB`` (ATMEL)
- ``PID = 0x2426`` (ASF Example with up to seven CDCs)
This add-on can be built as two NSH "built-in" commands:
- ``CONFIG_NSH_BUILTIN_APPS`` – if this option is selected: ``conn`` will connect
the USB composite device; ``disconn`` will disconnect the USB composite device.
Configuration options unique to this add-on:
- ``CONFIG_SYSTEM_COMPOSITE_DEBUGMM`` – Enables some debug tests to check for
memory usage and memory leaks.
If ``CONFIG_USBDEV_TRACE`` is enabled (or ``CONFIG_DEBUG_FEATURES`` and
``CONFIG_DEBUG_USB``), then the add-on code will also manage the USB trace output.
The amount of trace output can be controlled using:
- ``CONFIG_SYSTEM_COMPOSITE_TRACEINIT`` – Show initialization events.
- ``CONFIG_SYSTEM_COMPOSITE_TRACECLASS`` – Show class driver events.
- ``CONFIG_SYSTEM_COMPOSITE_TRACETRANSFERS`` – Show data transfer events.
- ``CONFIG_SYSTEM_COMPOSITE_TRACECONTROLLER`` – Show controller events.
- ``CONFIG_SYSTEM_COMPOSITE_TRACEINTERRUPTS`` – Show interrupt-related events.

14
Documentation/applications/system/flash_eraseall/index.rst Normal file
View File

@ -0,0 +1,14 @@
==========================================
``flash_eraseall`` FLASH Erase-all Command
==========================================
This application erases the FLASH of an MTD flash block. It is simply a wrapper
that calls the NuttX ``flash_eraseall`` interface.
Usage::
flash_eraseall <flash_block_device>
Author: Ken Pettit
Date: 5 May 2013

18
Documentation/applications/system/index.rst
View File

@ -7,16 +7,12 @@ System Libraries and NSH Add-Ons
:maxdepth: 3
:titlesonly:
nxdiag/index.rst
i2c/index.rst
*/index*
- adb - ADB daemon application
- argtable3 - ARGTABLE3 library
- cachespeed - CACHE Speed Test
- cdcacm - USB CDC/ACM Device Commands
- cfgdata - Cfgdata Command
- cle - EMACS-like Command Line Editor
- composite - USB Composite Device Commands
- coredump - Coredump tool capture system status
- critmon - Critcal Section Monitor
- cu - CU minimal serial terminal
@ -26,7 +22,6 @@ System Libraries and NSH Add-Ons
- dumpstack - dumpstack tool for show the task backtrace
- fastboot - fastbootd
- fdt - fdt utility tools
- flash_eraseall - FLASH Erase-all Command
- gcov - gcov tool
- gdbstub - GDBSTUB
- hexed - Hex editor
@ -34,7 +29,6 @@ System Libraries and NSH Add-Ons
- hostname - 'hostname' command
- input - input tool
- iptables - 'iptables' command
- libuv - libuv asynchronous I/O Library
- lm75 - LM75 Temperature
- lzf - LZF compression tool
- mdio - PHY MDIO tool
@ -43,19 +37,16 @@ System Libraries and NSH Add-Ons
- ntpc - NTP Daemon Commands
- nxcamera - NxCamera video test application
- nxlooper - NxLooper audio test application
- nxplayer - NxPlayer Media Player
- nxrecorder - NxRecorder pcm raw data Recorder
- ping - ICMP 'ping' command
- ping6 - ICMPv6 'ping6' command
- popen - popen()/pclose() Functions
- psmq - psmq
- ptpd - PTP daemon commands
- ramspeed - RAM Speed Test
- ramtest - RAM Test
- readline - readline() Support
- sched_note - Scheduler monitor
- setlogmask - 'setlogmask' command
- spi - SPI tool
- stackmonitor - Stack Monitor
- system - System Command
- taskset - Taskset Command
@ -63,14 +54,9 @@ System Libraries and NSH Add-Ons
- tee - Tee Command
- telnet - Telnet chat daemon
- telnetd - Telnet daemon application
- termcurses - Terminal Curses control support
- trace - Trace command
- ubloxmodem - u-blox modem configuration tool
- uniqueid - 'uniqueid' command
- uorb - uorb(micro object request broker)
- usbmsc - USB Mass Storage Device Commands
- vi - VI Work-Alike Text Editor
- ymodem - YMODEM
- ofloader - Open flash loader
- zlib - zlib data compression library
- zmodem - Zmodem Commands

19
Documentation/applications/system/libuv/index.rst Normal file
View File

@ -0,0 +1,19 @@
========================================
``libuv`` libuv asynchronous I/O Library
========================================
Most features of libuv are supported by current port, except SIGPROF relative function (loop_configure).
Nearly full libuv's test suite avaliable on NuttX, but some known case can't run on sim:
* ``loop_update_time``
* ``idle_starvation``
* ``signal_multiple_loops``
* ``signal_pending_on_close``
* ``metrics_idle_time``
* ``metrics_idle_time_thread``
* ``metrics_idle_time_zero``
And some will cause crash by some reason:
* ``fs_poll_ref``

44
Documentation/applications/system/nsh/index.rst Normal file
View File

@ -0,0 +1,44 @@
===============================
``nsh`` NuttShell (NSH) example
===============================
Basic Configuration
-------------------
This directory provides an example of how to configure and use the NuttShell
(NSH) application. NSH is a simple shell application. NSH is described in its
own README located at ``apps/nshlib/README.md``. This function is enabled with::
CONFIG_SYSTEM_NSH=y
Applications using this example will need to provide an ``defconfig`` file in the
configuration directory with instruction to build the NSH library like::
CONFIG_NSH_LIBRARY=y
Other Configuration Requirements
--------------------------------
**Note**: If the NSH serial console is used, then following is also required to
build the ``readline()`` library::
CONFIG_SYSTEM_READLINE=y
And if networking is included::
CONFIG_NETUTILS_NETLIB=y
CONFIG_NETUTILS_DHCPC=y
CONFIG_NETDB_DNSCLIENT=y
CONFIG_NETUTILS_TFTPC=y
CONFIG_NETUTILS_WEBCLIENT=y
If the Telnet console is enabled, then the defconfig file should also include::
CONFIG_NETUTILS_TELNETD=y
Also if the Telnet console is enabled, make sure that you have the following set
in the NuttX configuration file or else the performance will be very bad
(because there will be only one character per TCP transfer):
- ``CONFIG_STDIO_BUFFER_SIZE`` - Some value ``>= 64``
- ``CONFIG_STDIO_LINEBUFFER=y``

8
Documentation/applications/system/nxdiag/index.rst
View File

@ -1,6 +1,6 @@
==============================
NuttX Diagnostic Tool (Nxdiag)
==============================
================================
``nxdiag`` NuttX Diagnostic Tool
================================
The NuttX Diagnostic Tool (Nxdiag) is a command line tool that can be used to gather information about the NuttX and host systems.
It also can be used to run a tests to verify that the vendor's tools are properly installed and configured.
@ -15,7 +15,7 @@ script, check the command line options and code comments of ``host_sysinfo.py``.
recommended as it provides more accurate information about the host system.
Usage
=====
-----
This page shows ``nxdiag`` options. Note that some options are only available if the
respective configuration options are enabled (see :ref:`cmdtable <nxdiagcmddependencies>`).

16
Documentation/applications/system/nxplayer/index.rst Normal file
View File

@ -0,0 +1,16 @@
==================================
``nxplayer`` NxPlayer Media Player
==================================
This application implements a command-line media player which uses the NuttX
Audio system to play files (``mp3``, ``wav``, etc.) from the file system.
Usage::
nxplayer
The application presents an command line for specifying player commands, such as
``play filename``, ``pause``, ``volume 50%``, etc.
Author: Ken Pettit
Date: 11 Sept 2013

53
Documentation/applications/system/psmq/index.rst Normal file
View File

@ -0,0 +1,53 @@
========================================
``psmq`` Publish Subscribe Message Queue
========================================
``psmq`` is publish subscribe message queue. It's a set of programs and libraries
to implement publish/subscribe way of inter-process communication on top of
POSIX message queue.
Manuals, source code and more info at: https://psmq.bofc.pl
Little demo using ``psmqd`` broker, ``psmq_pub`` and ``psmq_sub``:
Start broker and make it log to file::
nsh> psmqd -b/brok -p/sd/psmqd/psmqd.log &
Start subscribe thread that will read all messages send on ``/can/*`` and
``/adc/*`` topic, and dump all readings to file::
nsh> psmq_sub -n/sub -b/brok -t/can/* -t/adc/* -o/sd/psmq-sub/can.log &
n/connected to broker /brok
n/subscribed to: /can/*
n/subscribed to: /adc/*
n/start receiving data
n/reply timeout set 100
Publish some messages::
nsh> psmq_pub -b/brok -t/can/engine/rpm -m50
nsh> psmq_pub -b/brok -t/adc/volt -m30
nsh> psmq_pub -b/brok -t/can/room/10/temp -m23
nsh> psmq_pub -b/brok -t/pwm/fan1/speed -m300
Check out subscribe thread logs::
nsh> cat /sd/psmq-sub/can.log
[2021-05-23 17:53:59] p:0 l: 3 /can/engine/rpm 50
[2021-05-23 17:53:59] p:0 l: 3 /adc/volt 30
[2021-05-23 17:53:59] p:0 l: 3 /can/room/10/temp 23
As you can see ``/pwm/fan1/speed`` hasn't been received by subscribe thread,
since we didn't subscribe to it.
Content:
- ``psmqd`` – broker, relays messages between clients.
- ``psmq_sub`` – listens to specified topics, can be used as logger for
communication (optional).
- ``psmq_pub`` – publishes messages directly from shell. Can send binary data, but
requires pipes, so on nuttx it can only send ASCII.
- ``libpsmq`` – library used to communicate with the broker and send/receive
messages.

247
Documentation/applications/system/spi/index.rst Normal file
View File

@ -0,0 +1,247 @@
================
``spi`` SPI Tool
================
The I2C tool provides a way to debug SPI related problems. This README file will
provide usage information for the SPI tools.
Contents
--------
- System Requirements
* SPI Driver
* Configuration Options
- Help
- Common Line Form
- Common Command Options
* "Sticky" Options
* Environment variables
* Common Option Summary
- Command summary
* ``bus``
* ``dev``
* ``get``
* ``set``
* ``verf``
- I2C Build Configuration
* NuttX Configuration Requirements
* I2C Tool Configuration Options
System Requirements
-------------------
The SPI tool is designed to be implemented as a NuttShell (NSH) add-on. Read the
``apps/nshlib/README.md`` file for information about add-ons.
Configuration Options
~~~~~~~~~~~~~~~~~~~~~
- ``CONFIG_NSH_BUILTIN_APPS`` – Build the tools as an NSH built-in command.
- ``CONFIG_SPITOOL_MINBUS`` – Smallest bus index supported by the hardware
(default ``0``).
- ``CONFIG_SPITOOL_MAXBUS`` – Largest bus index supported by the hardware
(default ``3``).
- ``CONFIG_SPITOOL_DEFFREQ`` – Default frequency (default: ``40000000``).
- ``CONFIG_SPITOOL_DEFMODE`` – Default mode, where::
0 = CPOL=0, CPHA=0
1 = CPOL=0, CPHA=1
2 = CPOL=1, CPHA=0
3 = CPOL=1, CPHA=1
- ``CONFIG_SPITOOL_DEFWIDTH`` – Default bit width (default ``8``).
- ``CONFIG_SPITOOL_DEFWORDS`` – Default number of words to exchange (default ``1``).
Help
----
The SPI tools supports some help output. That help output can be view by
entering either::
nsh> spi help
or::
nsh> spi ?
Here is an example of the help output. I shows the general form of the command
line, the various SPI commands supported with their unique command line options,
and a more detailed summary of the command SPI command options::
nsh> Usage: spi <cmd> [arguments]
Where <cmd> is one of:
Show help : ?
List buses : bus
SPI Exchange : exch [OPTIONS] [<hex senddata>]
Show help : help
Where common _sticky_ OPTIONS include:
[-b bus] is the SPI bus number (decimal). Default: 0 Current: 2
[-f freq] SPI frequency. Default: 4000000 Current: 4000000
[-m mode] Mode for transfer. Default: 0 Current: 0
[-u udelay] Delay after transfer in uS. Default: 0 Current: 0
[-w width] Width of bus. Default: 8 Current: 8
[-x count] Words to exchange. Default: 1 Current: 4
**Notes**:
- An environment variable like $PATH may be used for any argument.
- Arguments are _sticky_. For example, once the SPI address is specified, that
address will be re-used until it is changed.
**Warning**:
- The SPI commands may have bad side effects on your SPI devices. Use only at
your own risk.
Command Line Form
-----------------
The SPI is started from NSH by invoking the ``spi`` command from the NSH command
line. The general form of the ``spi`` command is::
spi <cmd> [arguments]
Where ``<cmd>`` is a "sub-command" and identifies one SPI operation supported by
the tool. ``[arguments]`` represents the list of arguments needed to perform the
SPI operation. Those arguments vary from command to command as described below.
However, there is also a core set of common ``OPTIONS`` supported by all commands.
So perhaps a better representation of the general SPI command would be::
i2c <cmd> [OPTIONS] [arguments]
Where ``[OPTIONS]`` represents the common options and and arguments represent the
operation-specific arguments.
Common Command Options
-----------------------
"Sticky" Options
~~~~~~~~~~~~~~~~
In order to interact with SPI devices, there are a number of SPI parameters that
must be set correctly. One way to do this would be to provide to set the value
of each separate command for each SPI parameter. The SPI tool takes a different
approach, instead: The SPI configuration can be specified as a (potentially
long) sequence of command line arguments.
These arguments, however, are _sticky_. They are sticky in the sense that once
you set the SPI parameter, that value will remain until it is reset with a new
value (or until you reset the board).
Environment Variables
~~~~~~~~~~~~~~~~~~~~~
**Note** also that if environment variables are not disabled (by
``CONFIG_DISABLE_ENVIRON=y``), then these options may also be environment
variables. Environment variables must be preceded with the special character
``$``. For example, ``PWD`` is the variable that holds the current working directory
and so ``$PWD`` could be used as a command line argument. The use of environment
variables on the I2C tools command is really only useful if you wish to write
NSH scripts to execute a longer, more complex series of SPI commands.
Common Option Summary
~~~~~~~~~~~~~~~~~~~~~
- ``[-b bus]`` is the SPI bus number (decimal). Default: ``0``
Which SPI bus to commiuncate on. The bus must have been initialised as a
character device in the config in the form ``/dev/spiX`` (e.g. ``/dev/spi2``).
The valid range of bus numbers is controlled by the configuration settings
``CONFIG_SPITOOL_MINBUS`` and ``CONFIG_SPITOOL_MAXBUS``.
The bus numbers are small, decimal numbers.
- ``[-m mode]`` SPI Mode for transfer.
Which of the available SPI modes is to be used. Options are::
0 = CPOL=0, CPHA=0
1 = CPOL=0, CPHA=1
2 = CPOL=1, CPHA=0
3 = CPOL=1, CPHA=1
- ``[-u udelay]`` Delay after transfer in uS. Default: ``0``
Any extra delay to be provided after the transfer. Not normally needed from
the command line.
- ``[-x count]`` Words to exchange Default: ``1``
The number of words to be transited over the bus. For sanitys sake this is
limited to a relatively small number (``40`` by default). Any data on the
command line is sent first, padded by ``0xFF``'s while any remaining data are
received.
- ``[-w width]`` is the data width (varies according to target). Default: ``8``
Various SPI devices support different data widths. This option is untested.
- ``[-f freq]`` I2C frequency. Default: ``4000000`` Current: ``4000000``
The ``[-f freq]`` sets the frequency of the SPI device. The default is very
conservative.
Command Summary
---------------
List buses: ``bus [OPTIONS]``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command will simply list all of the configured SPI buses and indicate which
are supported by the driver and which are not::
BUS EXISTS?
Bus 1: YES
Bus 2: NO
The valid range of bus numbers is controlled by the configuration settings
``CONFIG_SPITOOL_MINBUS`` and ``CONFIG_SPITOOL_MAXBUS``.
Exchange data: ``exch [OPTIONS] <Optional TX Data>``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command triggers an SPI transfer, returning the data back from the far end.
As an example (with MOSI looped back to MISO)::
nsh> spi exch -b 2 -x 4 aabbccdd
Received: AA BB CC DD
Note that the ``TX Data`` are always specified in hex, and are always two digits
each, case insensitive.
I2C Build Configuration
-----------------------
NuttX Configuration Requirements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The SPI tools requires the following in your NuttX configuration:
1. Application configuration.
Using ``make menuconfig``, select the SPI tool. The following definition should
appear in your ``.config`` file::
CONFIG_SYSTEM_SPI=y
2. Device-specific SPI driver support must be enabled::
CONFIG_SPI_DRIVER=y
The SPI tool will then use the SPI character driver to access the SPI bus.
These devices will reside at ``/dev/spiN`` where ``N`` is the I2C bus number.
**Note**: The SPI driver ``ioctl`` interface is defined in
``include/nuttx/spi/spi.h``.

54
Documentation/applications/system/termcurses/index.rst Normal file
View File

@ -0,0 +1,54 @@
==============================================
``termcurses`` Terminal Curses control support
==============================================
Terminal emulation library for NuttX
The Termcurses library provides terminal emulation support for performing common
screen actions such as cursor movement, foreground / background color control
and keyboard escape sequence mapping. The initial release supports only ``vt100``
/ ``ansi`` terminal types, but the library architecture has an extensible
interface to allow support for additional emulation types if needed.
The library can be used standalone or in conjunction with the
``apps/graphics/pdcurses`` libraries. The pdcurses libraries have been updated
with a _termcurses_ config option which fully integrates the termcurses library
automatically.
Usage
-----
To use the termcurses library, the routines must be initialized by calling the
``termcurses_initterm()`` function. This routine accepts a terminal type string
identifying the type of terminal emulation support requested. If a ``NULL``
pointer is passed, then the routine will check for a ``TERM`` environment variable
and set the terminal type based on that string. If the emulation type still
cannot be determined, the routine will default to ``vt100`` emulation type.
Upon successful initialization, the ``termcurses_initterm()`` function will
allocate an new terminal context which must be passed with all future termcurses
library functions. When this context is no longer needed, the
``termcurses_deinitterm()`` routine should be called for proper freeing and
terminal teardown.
Use with ``telnetd``
--------------------
When using termcurses with the telnet daemon, the telnet config option
``CONFIG_TELNET_SUPPORT_NAWS`` should be enabled. This option adds code to the
telnet library for terminal size negotiation. Without this option, the telnet
routines have no concept of the terminal size, and therefore the termcurses
routines must default to ``80x24`` screen mode.
Use with ``pdcurses``
---------------------
When using the pdcurses termcurses support (i.e you have enabled both the
``CONFIG_PDCURSES`` and ``CONFIG_TERMCURSES`` options),, the pdcurses input device
should be selected to be ``TERMINPUT`` (i.e. set ``CONFIG_PDCURSES_TERMINPUT=y``).
This causes the pdcurses keyboard input logic to use ``termcurses_getkeycode()``
routine for curses input.
Author: Ken Pettit
Date: 2018-2019

5
Documentation/applications/system/trace/index.rst Normal file
View File

@ -0,0 +1,5 @@
=======================
``trace`` Trace command
=======================
See https://nuttx.apache.org/docs/latest/guides/tasktraceuser.html

83
Documentation/applications/system/usbmsc/index.rst Normal file
View File

@ -0,0 +1,83 @@
===========================================
``usbmsc`` USB Mass Storage Device Commands
===========================================
This add-on registers a block device driver, then exports the block the device
using the USB storage class driver. In order to use this add-on, your
board-specific logic must provide the function::
void board_usbmsc_initialize(void);
This function will be called by the ``system/usbmsc`` indirectly via the ``boardctl``
``BOARDIOC_USBDEV_CONTROL`` command in order to do the actual registration of the
block device drivers. For examples of the implementation of
``board_usbmsc_initialize()`` see
``boards/arm/lpc214x/mcu123-lpc214x/src/up_usbmsc.c`` or
``boards/arm/stm32/stm3210e-eval/src/usbmsc.c``.
Configuration options:
- ``CONFIG_NSH_BUILTIN_APPS`` – This add-on can be built as two NSH "built-in"
commands if this option is selected: ``msconn`` will connect the USB mass
storage device; ``msdis`` will disconnect the USB storage device.
- ``CONFIG_BOARDCTL`` – Enables the ``boardctl()`` interfaces.
- ``CONFIG_BOARDCTL_USBDEVCTRL`` – Enables the ``BOARDIOC_USBDEV_CONTROL``
``boardctl()`` command.
- ``CONFIG_SYSTEM_USBMSC_NLUNS`` – Defines the number of logical units (LUNs)
exported by the USB storage driver. Each LUN corresponds to one exported block
driver (or partition of a block driver). May be ``1``, ``2``, or ``3``. Default is
``1``.
- ``CONFIG_SYSTEM_USBMSC_DEVMINOR1`` – The minor device number of the block driver
for the first LUN. For example, ``N`` in ``/dev/mmcsdN``. Used for registering the
block driver. Default is zero.
- ``CONFIG_SYSTEM_USBMSC_DEVPATH1`` – The full path to the registered block
driver. Default is ``/dev/mmcsd0``
- ``CONFIG_SYSTEM_USBMSC_DEVMINOR2`` and ``CONFIG_SYSTEM_USBMSC_DEVPATH2``
Similar parameters that would have to be provided if
``CONFIG_SYSTEM_USBMSC_NLUNS`` is ``2`` or ``3``. No defaults.
- ``CONFIG_SYSTEM_USBMSC_DEVMINOR3`` and ``CONFIG_SYSTEM_USBMSC_DEVPATH3``
Similar parameters that would have to be provided if
``CONFIG_SYSTEM_USBMSC_NLUNS`` is ``3``. No defaults.
- ``CONFIG_SYSTEM_USBMSC_DEBUGMM`` – Enables some debug tests to check for memory
usage and memory leaks.
If ``CONFIG_USBDEV_TRACE`` is enabled (or ``CONFIG_DEBUG_FEATURES`` and
``CONFIG_DEBUG_USB``), then the code will also manage the USB trace output. The
amount of trace output can be controlled using:
- ``CONFIG_SYSTEM_USBMSC_TRACEINIT`` – Show initialization events.
- ``CONFIG_SYSTEM_USBMSC_TRACECLASS`` – Show class driver events.
- ``CONFIG_SYSTEM_USBMSC_TRACETRANSFERS`` – Show data transfer events.
- ``CONFIG_SYSTEM_USBMSC_TRACECONTROLLER`` – Show controller events.
- ``CONFIG_SYSTEM_USBMSC_TRACEINTERRUPTS`` – Show interrupt-related events.
Error results are always shown in the trace output
**Note 1**: When built as an NSH add-on command (``CONFIG_NSH_BUILTIN_APPS=y``),
Caution should be used to assure that the SD drive (or other storage device) is
not in use when the USB storage device is configured. Specifically, the SD
driver should be unmounted like::
nsh> mount -t vfat /dev/mmcsd0 /mnt/sdcard # Card is mounted in NSH
...
nsh> umount /mnd/sdcard # Unmount before connecting USB!!!
nsh> msconn # Connect the USB storage device
...
nsh> msdis # Disconnect USB storate device
nsh> mount -t vfat /dev/mmcsd0 /mnt/sdcard # Restore the mount
Failure to do this could result in corruption of the SD card format.
**Note 2**: This add-on used internal USB device driver interfaces. As such, it
relies on internal OS interfaces that are not normally available to a user-space
program. As a result, this add-on cannot be used if a NuttX is built as a
protected, supervisor kernel (``CONFIG_BUILD_PROTECTED`` or
``CONFIG_BUILD_KERNEL``).

61
Documentation/applications/system/ymodem/index.rst Normal file
View File

@ -0,0 +1,61 @@
=================
``ymodem`` YMODEM
=================
This is `ymodem protocal <http://pauillac.inria.fr/~doligez/zmodem/ymodem.txt>`_.
According to it, the sb rb application is realized, which is used to send files and receive files respectively
Usage
-----
Common Usage
~~~~~~~~~~~~
In the ubuntu system, lszrz needs to be installed, can use ``sudo apt install lszrz``.
Use minicom to communicate with the board.
Advanced Usage
~~~~~~~~~~~~~~
In order to achieve a faster transmission speed,
I added a specific HEADER ``STC`` to the YMODEM protocol to represent the custom length.
Using the ``sb`` and ``rb`` commands on the board, you can use the ``-k`` option to set the length
of the custom packet, and the unit is KB. Therefore, you need to use ``sbrb.py`` for file transfer,
and you need ``sbrb.py`` -k to set the same length as the board. According to my test,
when using -k 32, it can reach 93% of the baud rate,
and is fully compatible with the original ymodem protocol.
First, you need to add a soft link to sbrb.py, for example ``sudo ln -s /home/<name>/.../<nuttxwork>/apps/system/ymodem/sbrb.py /usr/bin``
and then sbrb.py can be configured into minicom.``<Ctrl + a> z o`` then chose ``File transfer protocols`` and
crate two option cmd is 'sbrb.py -k 32'. like this
=========== ============= ==== === ======= ======= =====
Name Program Name U/D FullScr IO-Red. Multi
=========== ============= ==== === ======= ======= =====
ymodem-k sbrb.py -k 32 Y U N Y Y
ymodem-k sbrb.py -k 32 N D N Y Y
=========== ============= ==== === ======= ======= =====
usb ``sb -k 32`` or ``rb -k 32`` for file transfer on board.
Sendfile to pc
--------------
use sb command like this ``nsh> sb /tmp/test.c ...``, this command support send multiple files together
then use ``<Ctrl + a> , r`` chose ``ymodem`` to receive board file.
Sendfile to board
-----------------
use rb cmd like this ``nsh> rb``, this command support receive multiple files together
then use ``<Ctrl + a> , s`` chose ``ymodem``, then chose what file need to send.
help
~~~~
can use ``sb -h`` or ``rb -h`` get help.
Debug
-----
Because the serial port is used for communication, the log is printed to the debug file
you can use ``CONFIG_SYSTEM_YMODEM_DEBUGFILE_PATH`` set debug file path.

276
Documentation/applications/system/zmodem/index.rst Normal file
View File

@ -0,0 +1,276 @@
==========================
``zmodem`` Zmodem Commands
==========================
Contents
--------
- Buffering Notes
* Hardware Flow Control
* RX Buffer Size
* Buffer Recommendations
- Using NuttX ZModem with a Linux Host
* Sending Files from the Target to the Linux Host PC
* Receiving Files on the Target from the Linux Host PC
- Building the ZModem Tools to Run Under Linux
- Status
Buffering Notes
---------------
Hardware Flow Control
~~~~~~~~~~~~~~~~~~~~~
Hardware flow control must be enabled in serial drivers in order to prevent data
overrun. However, in the most NuttX serial drivers, hardware flow control only
protects the hardware RX FIFO: Data will not be lost in the hardware FIFO but
can still be lost when it is taken from the FIFO. We can still overflow the
serial driver's RX buffer even with hardware flow control enabled! That is
probably a bug. But the workaround solution that I have used is to use lower
data rates and a large serial driver RX buffer.
Those measures should be unnecessary if buffering and hardware flow control are
set up and working correctly.
Software Flow Control
~~~~~~~~~~~~~~~~~~~~~
The ZModem protocol has ``XON/XOFF`` flow control built into it. The protocol
permits ``XON`` or ``XOFF`` characters placed at certain parts of messages. If
software flow control is enabled on the receiving end it will consume the ``XON`` s
and ``XOFF`` s. Otherwise they will be ignored in the data by the ZModem logic.
NuttX, however, does not implement ``XON/XOFF`` flow control so these do nothing.
On NuttX you will have to use hardware flow control in most cases.
The ``XON`` / ``XOFF`` controls built into ZModem could be used if you enabled
software flow control in the host. But that would only work in one direction: If
would prevent the host from overrunning the the target Rx buffering. So you
should be able to do host-to-target software flow control. But there would still
be no target-to-host flow control. That might not be an issue because the host
is usually so much faster than that target.
RX Buffer Size
~~~~~~~~~~~~~~
The ZModem protocol supports a message that informs the file sender of the
maximum size of data that you can buffer (``ZRINIT``). However, my experience is
that the Linux sz ignores this setting and always sends file data at the maximum
size (``1024``) no matter what size of buffer you report. That is unfortunate
because that, combined with the possibilities of data overrun mean that you must
use quite large buffering for ZModem file receipt to be reliable (none of these
issues effect sending of files).
Buffer Recommendations
~~~~~~~~~~~~~~~~~~~~~~
Based on the limitations of NuttX hardware flow control and of the Linux sz
behavior, I have been testing with the following configuration (assuming ``UART1``
is the ZModem device):
1) This setting determines that maximum size of a data packet frame::
CONFIG_SYSTEM_ZMODEM_PKTBUFSIZE=1024
2) Input Buffering. If the input buffering is set to a full frame, then data
overflow is less likely::
CONFIG_UART1_RXBUFSIZE=1024
3) With a larger driver input buffer, the ZModem receive I/O buffer can be
smaller::
CONFIG_SYSTEM_ZMODEM_RCVBUFSIZE=256
4) Output buffering. Overrun cannot occur on output (on the NuttX side) so there
is no need to be so careful::
CONFIG_SYSTEM_ZMODEM_SNDBUFSIZE=512
CONFIG_UART1_TXBUFSIZE=256
Using NuttX ZModem with a Linux Host
------------------------------------
Sending Files from the Target to the Linux Host PC
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The NuttX ZModem commands have been verified against the rzsz programs running
on a Linux PC. To send a file to the PC, first make sure that the serial port is
configured to work with the board (Assuming you are using 9600 baud for the data
transfers - high rates may result in data overruns)::
$ sudo stty -F /dev/ttyS0 9600 # Select 9600 BAUD
$ sudo stty -F /dev/ttyS0 crtscts # Enables CTS/RTS handshaking *
$ sudo stty -F /dev/ttyS0 raw # Puts the TTY in raw mode
$ sudo stty -F /dev/ttyS0 # Show the TTY configuration
Only if hardware flow control is enabled.
Start ``rz`` on the Linux host (using ``/dev/ttyS0`` as an example)::
$ sudo rz < /dev/ttyS0 > /dev/ttyS0
You can add the ``rz -v`` option multiple times, each increases the level of debug
output. If you want to capture the Linux ``rz`` output, then re-direct ``stderr`` to
a log file by adding ``2>rz.log`` to the end of the ``rz`` command.
**Note**: The NuttX ZModem does sends ``rz\n`` when it starts in compliance with
the ZModem specification. On Linux this, however, seems to start some other,
incompatible version of ``rz``. You need to start ``rz`` manually to make sure that
the correct version is selected. You can tell when this evil ``rz``/``sz`` has
inserted itself because you will see the ``^`` (``0x5e``) character replacing the
standard ZModem ``ZDLE`` character (``0x19``) in the binary data stream.
If you don't have the ``rz`` command on your Linux box, the package to install
``rzsz`` (or possibly ``lrzsz``).
Then on the target (using ``/dev/ttyS1`` as an example)::
nsh> sz -d /dev/ttyS1 <filename>
Where filename is the full path to the file to send (i.e., it begins with the
``/`` character). ``/dev/ttyS1`` or whatever device you select **must** support
Hardware flow control in order to throttle therates of data transfer to fit
within the allocated buffers.
Receiving Files on the Target from the Linux Host PC
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Note**: There are issues with using the Linux ``sz`` command with the NuttX ``rz``
command. See _Status_ below. It is recommended that you use the NuttX ``sz``
command on Linux as described in the next paragraph.
To send a file to the target, first make sure that the serial port on the host
is configured to work with the board (Assuming that you are using ``9600`` baud
for the data transfers - high rates may result in data overruns)::
$ sudo stty -F /dev/ttyS0 9600 # Select 9600 (or other) BAUD
$ sudo stty -F /dev/ttyS0 crtscts # Enables CTS/RTS handshaking *
$ sudo stty -F /dev/ttyS0 raw # Puts the TTY in raw mode
$ sudo stty -F /dev/ttyS0 # Show the TTY configuration
Only is hardware flow control is enabled.
Start ``rz`` on the on the target. Here, in this example, we are using
``/dev/ttyS1`` to perform the transfer::
nsh> rz -d /dev/ttyS1
``/dev/ttyS1`` or whatever device you select **must** support Hardware flow
control in order to throttle therates of data transfer to fit within the
allocated buffers.
Then use the ``sz`` command on Linux to send the file to the target::
$ sudo sz <filename> [-l nnnn] [-w nnnn] </dev/ttyS0 >/dev/ttyS0
Where ``<filename>`` is the file that you want to send. If ``-l nnnn`` and ``-w nnnn``
is not specified, then there will likely be packet buffer overflow errors.
``nnnn`` should be set to a value less than or equal to
``CONFIG_SYSTEM_ZMODEM_PKTBUFSIZE``.
The resulting file will be found where you have configured the ZModem
**sandbox** via ``CONFIG_SYSTEM_ZMODEM_MOUNTPOINT``.
You can add the ``sz -v`` option multiple times, each increases the level of debug
output. If you want to capture the Linux ``sz`` output, then re-direct ``stderr`` to
a log file by adding ``2>sz.log`` to the end of the ``sz`` command.
If you don't have the sz command on your Linux box, the package to install
``rzsz`` (or possibly ``lrzsz``).
Building the ZModem Tools to Run Under Linux
--------------------------------------------
Build support has been added so that the NuttX ZModem implementation can be
executed on a Linux host PC. This can be done by
- Change to the ``apps/systems/zmodem`` directory
- Make using the special makefile, ``Makefile.host``
**Notes**:
1. ``TOPDIR`` and ``APPDIR`` must be defined on the make command line: ``TOPDIR`` is
the full path to the ``nuttx/`` directory; ``APPDIR`` is the full path to the
``apps/`` directory. For example, if you installed nuttx at
``/home/me/projects/nuttx`` and apps at ``/home/me/projects/apps``, then the
correct make command line would be::
make -f Makefile.host TOPDIR=/home/me/projects/nuttx APPDIR=/home/me/projects/apps
2. Add ``CONFIG_DEBUG_FEATURES=1`` to the make command line to enable debug output
3. Make sure to clean old target ``.o`` files before making new host ``.o`` files.
This build is has been verified as of ``2013-7-16`` using Linux to transfer files
with an Olimex LPC1766STK board. It works great and seems to solve all of the
problems found with the Linux ``sz``/``rz`` implementation.
Status
------
- ``2013-7-15``: Testing against the Linux ``rz``/``sz`` commands.
I have tested with the ``boards/arm/lpc17xx_40xx/olimex-lpc1766stk``
configuration. I have been able to send large and small files with the target
``sz`` command. I have been able to receive small files, but there are problems
receiving large files using the Linux ``sz`` command: The Linux ``sz`` does not
obey the buffering limits and continues to send data while ``rz`` is writing the
previously received data to the file and the serial driver's RX buffer is
overrun by a few bytes while the write is in progress. As a result, when it
reads the next buffer of data, a few bytes may be missing. The symptom of this
missing data is a CRC check failure.
Either (1) we need a more courteous host application, or (2) we need to
greatly improve the target side buffering capability!
My thought now is to implement the NuttX ``sz`` and ``rz`` commands as PC side
applications as well. Matching both sides and obeying the handshaking will
solve the issues. Another option might be to fix the serial driver hardware
flow control somehow.
- ``2013-7-16``. More Testing against the Linux ``rz``/``sz`` commands.
I have verified that with debug off and at lower serial BAUD (``2400``), the
transfers of large files succeed without errors. I do not consider this a
_solution_ to the problem. I also found that the LPC17xx hardware flow control
caused strange hangs; ZModem works better with hardware flow control disabled
on the LPC17xx.
At this lower BAUD, RX buffer sizes could probably be reduced; Or perhaps the
BAUD could be increased. My thought, however, is that tuning in such an
unhealthy situation is not the approach: The best thing to do would be to use
the matching NuttX sz on the Linux host side.
- ``2013-7-16``. More Testing against the NuttX ``rz``/``sz`` on Both Ends.
The NuttX ``sz``/``rz`` commands have been modified so that they can be built and
executed under Linux. In this case, there are no transfer problems at all in
either direction and with large or small files. This configuration could
probably run at much higher serial speeds and with much smaller buffers
(although that has not been verified as of this writing).
- ``2018-5-27``
Updates to checksum calculations. Verified correct operation with hardware
flow control using the ``olimex-stm32-p407/zmodem`` configuration. Only the
host-to-target transfer was verified.
This was using the Linux ``sz`` utility. There appears to still be a problem
using the NuttX ``sz`` utility running on Linux.
- ``2018-5-27``
Verified correct operation with hardware flow control using the
``olimex-stm32-p407/zmodem`` configuration with target-to-host transfers was
verified. Again, there are issues remaining if I tried the NuttX ``rz`` utility
running on Linux.
- ``2018-6-26``
With ``-w nnnn`` option, the host-to-target transfer can work reliably without
hardware flow control.