This is an automated email from the ASF dual-hosted git repository. acassis pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit cffc74c6647ec48a19729097e39a64258478bc4d Author: raiden00pl <raide...@railab.me> AuthorDate: Tue Oct 24 12:23:16 2023 +0200 Documentaion: migrate system/readme --- Documentation/applications/system/cdcacm/index.rst | 38 +++ .../applications/system/cfgdata/index.rst | 22 ++ .../applications/system/composite/index.rst | 71 ++++++ .../applications/system/flash_eraseall/index.rst | 14 ++ Documentation/applications/system/index.rst | 18 +- Documentation/applications/system/libuv/index.rst | 19 ++ Documentation/applications/system/nsh/index.rst | 44 ++++ Documentation/applications/system/nxdiag/index.rst | 8 +- .../applications/system/nxplayer/index.rst | 16 ++ Documentation/applications/system/psmq/index.rst | 53 ++++ Documentation/applications/system/spi/index.rst | 247 ++++++++++++++++++ .../applications/system/termcurses/index.rst | 54 ++++ Documentation/applications/system/trace/index.rst | 5 + Documentation/applications/system/usbmsc/index.rst | 83 +++++++ Documentation/applications/system/ymodem/index.rst | 61 +++++ Documentation/applications/system/zmodem/index.rst | 276 +++++++++++++++++++++ 16 files changed, 1009 insertions(+), 20 deletions(-) diff --git a/Documentation/applications/system/cdcacm/index.rst b/Documentation/applications/system/cdcacm/index.rst new file mode 100644 index 0000000000..5eb5af9ecb --- /dev/null +++ b/Documentation/applications/system/cdcacm/index.rst @@ -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. diff --git a/Documentation/applications/system/cfgdata/index.rst b/Documentation/applications/system/cfgdata/index.rst new file mode 100644 index 0000000000..87e94ee7a6 --- /dev/null +++ b/Documentation/applications/system/cfgdata/index.rst @@ -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 diff --git a/Documentation/applications/system/composite/index.rst b/Documentation/applications/system/composite/index.rst new file mode 100644 index 0000000000..473abeb60e --- /dev/null +++ b/Documentation/applications/system/composite/index.rst @@ -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. diff --git a/Documentation/applications/system/flash_eraseall/index.rst b/Documentation/applications/system/flash_eraseall/index.rst new file mode 100644 index 0000000000..68e3829dd7 --- /dev/null +++ b/Documentation/applications/system/flash_eraseall/index.rst @@ -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 diff --git a/Documentation/applications/system/index.rst b/Documentation/applications/system/index.rst index 859b3d8a6b..942369a5d3 100644 --- a/Documentation/applications/system/index.rst +++ b/Documentation/applications/system/index.rst @@ -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 diff --git a/Documentation/applications/system/libuv/index.rst b/Documentation/applications/system/libuv/index.rst new file mode 100644 index 0000000000..7a94fd4bad --- /dev/null +++ b/Documentation/applications/system/libuv/index.rst @@ -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`` diff --git a/Documentation/applications/system/nsh/index.rst b/Documentation/applications/system/nsh/index.rst new file mode 100644 index 0000000000..763851eb69 --- /dev/null +++ b/Documentation/applications/system/nsh/index.rst @@ -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`` diff --git a/Documentation/applications/system/nxdiag/index.rst b/Documentation/applications/system/nxdiag/index.rst index 0129392c47..11f685f705 100644 --- a/Documentation/applications/system/nxdiag/index.rst +++ b/Documentation/applications/system/nxdiag/index.rst @@ -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>`). diff --git a/Documentation/applications/system/nxplayer/index.rst b/Documentation/applications/system/nxplayer/index.rst new file mode 100644 index 0000000000..150480ceab --- /dev/null +++ b/Documentation/applications/system/nxplayer/index.rst @@ -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 diff --git a/Documentation/applications/system/psmq/index.rst b/Documentation/applications/system/psmq/index.rst new file mode 100644 index 0000000000..2983613475 --- /dev/null +++ b/Documentation/applications/system/psmq/index.rst @@ -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. diff --git a/Documentation/applications/system/spi/index.rst b/Documentation/applications/system/spi/index.rst new file mode 100644 index 0000000000..9c1ae3ed86 --- /dev/null +++ b/Documentation/applications/system/spi/index.rst @@ -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``. diff --git a/Documentation/applications/system/termcurses/index.rst b/Documentation/applications/system/termcurses/index.rst new file mode 100644 index 0000000000..9032fe82c2 --- /dev/null +++ b/Documentation/applications/system/termcurses/index.rst @@ -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 diff --git a/Documentation/applications/system/trace/index.rst b/Documentation/applications/system/trace/index.rst new file mode 100644 index 0000000000..ea595d327b --- /dev/null +++ b/Documentation/applications/system/trace/index.rst @@ -0,0 +1,5 @@ +======================= +``trace`` Trace command +======================= + +See https://nuttx.apache.org/docs/latest/guides/tasktraceuser.html diff --git a/Documentation/applications/system/usbmsc/index.rst b/Documentation/applications/system/usbmsc/index.rst new file mode 100644 index 0000000000..57da5b3035 --- /dev/null +++ b/Documentation/applications/system/usbmsc/index.rst @@ -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``). diff --git a/Documentation/applications/system/ymodem/index.rst b/Documentation/applications/system/ymodem/index.rst new file mode 100644 index 0000000000..e5e86a0249 --- /dev/null +++ b/Documentation/applications/system/ymodem/index.rst @@ -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. diff --git a/Documentation/applications/system/zmodem/index.rst b/Documentation/applications/system/zmodem/index.rst new file mode 100644 index 0000000000..53c1d3e62b --- /dev/null +++ b/Documentation/applications/system/zmodem/index.rst @@ -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.