diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml index 0801cce6f1..a6e1b4af2f 100644 --- a/.github/workflows/doc.yml +++ b/.github/workflows/doc.yml @@ -16,7 +16,7 @@ on: push: jobs: - docs: + build-html: runs-on: ubuntu-latest steps: - uses: actions/checkout@v1 @@ -28,6 +28,7 @@ jobs: cd Documentation/ pip3 install pipenv pipenv lock -r > requirements.txt + - uses: ammaraskar/sphinx-problem-matcher@master - uses: ammaraskar/sphinx-action@master with: docs-folder: "Documentation/" @@ -35,3 +36,17 @@ jobs: with: name: sphinx-docs path: Documentation/_build/html/ + linkcheck: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - uses: actions/setup-python@v2 + with: + python-version: '3.8' + - uses: ammaraskar/sphinx-problem-matcher@master + - name: Run linkcheck + run: | + cd Documentation/ + pip3 install pipenv + pipenv install + pipenv run make linkcheck diff --git a/Documentation/applications/nsh/commands.rst b/Documentation/applications/nsh/commands.rst index 39d642a92c..3524128a52 100644 --- a/Documentation/applications/nsh/commands.rst +++ b/Documentation/applications/nsh/commands.rst @@ -1,9 +1,11 @@ -******** +======== Commands -******** +======== + +.. _cmdtest: Evaluate Expression (test) --------------------------- +************************** **Command Syntax:** @@ -38,8 +40,10 @@ the conditional command following the ``if`` in the numeric-binary = integer -eq integer | integer -ge integer | integer -gt integer | integer -le integer | integer -lt integer | integer -ne integer +.. _cmdaddroute: + Add a Routing Table Entry (addroute) ------------------------------------- +************************************ **Command Syntax:** @@ -71,6 +75,8 @@ which is equivalent to The second form of the addroute command can be used to set the default gateway. +.. _cmdarp: + Access the ARP table (arp) ************************** @@ -102,6 +108,8 @@ Access the ARP table (arp) nsh> arp -a 10.0.0.1 nsh: arp: no such ARP entry: 10.0.0.1 +.. _cmdbase64dec: + Base64 Decode (base64dec) ************************* @@ -111,6 +119,8 @@ Base64 Decode (base64dec) **Synopsis**. *To be provided.* +.. _cmdbase64enc: + Base64 Encode (base64enc) ************************* @@ -120,6 +130,8 @@ Base64 Encode (base64enc) **Synopsis**. *To be provided.* +.. _cmdbasename: + Extract Base File/Directory Name (basename) ******************************************* @@ -131,6 +143,8 @@ Extract Base File/Directory Name (basename) removing the preceding path segments and (optionally) removing any trailing ````. +.. _cmdbreak: + Terminate a Loop (break) ************************ @@ -139,13 +153,15 @@ Terminate a Loop (break) break **Synopsis**. The ``break`` command is only meaningful within the -body of the a `while <#looping>`__ or `until <#looping>`__ loop, +body of the a ``while`` or ``until`` 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. +.. _cmdcat: + Concatenate Files (cat) *********************** @@ -157,6 +173,8 @@ Concatenate Files (cat) files at ```` to the console (or to another file if the output is redirected). +.. _cmdcd: + Change Current Working Directory (cd) ************************************* @@ -180,6 +198,8 @@ Also sets the previous working directory environment variable ``cd ..`` sets the current working directory to the parent directory. ================== ===================================== +.. _cmdcmp: + Compare Files (cmp) ******************* @@ -191,6 +211,8 @@ Compare Files (cmp) with the contents of the file at ````. Returns an indication only if the files differ. +.. _cmdcp: + Copy Files (cp) *************** @@ -202,6 +224,8 @@ Copy Files (cp) ```` to the location in the file system indicated by ````. +.. _cmddate: + Show or set the date and time (date) ************************************ @@ -216,6 +240,8 @@ date/time: ``MMM DD HH:MM:SS YYYY``. For example, 24-hour time is used. +.. _cmddd: + Copy and Convert Files (dd) *************************** @@ -257,6 +283,8 @@ bucket:: brw-rw-rw- 0 ram0 nsh> dd if=/dev/ram0 of=/dev/null +.. _cmddelroute: + Delete a Routing Table Entry (delroute) *************************************** @@ -279,6 +307,8 @@ which is equivalent to:: nsh> delroute 11.0.0.0/24 +.. _cmddf: + Show Volume Status (df) *********************** @@ -304,6 +334,8 @@ configuration, then the ``df`` will also support an option ``-h`` which may be used to show the volume information in *human readable* format. +.. _cmddirname: + Extract Path to a File/Directory (dirname) ****************************************** @@ -314,6 +346,8 @@ Extract Path to a File/Directory (dirname) **Synopsis**. Extract the path string leading up to the full ```` by removing the final directory or file name. +.. _cmddmesg: + Dump Buffered SYSLOG Output (dmesg) *********************************** @@ -330,6 +364,8 @@ 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. +.. _cmdecho: + Echo Strings and Variables (echo) ********************************* @@ -343,6 +379,8 @@ output is re-directed). The ``-n`` option suppresses the trailing newline character. +.. _cmdenv: + Show Environment Variables (env) ******************************** @@ -370,6 +408,8 @@ environment. Example:: .. note::NSH local variables are *not* shown by the ``env`` command. +.. _cmdexec: + Execute User Code (exec) ************************ @@ -381,6 +421,8 @@ Execute User Code (exec) NSH will pause until the execution unless the user logic is executed in background via ``exec &``. +.. _cmdexit: + Exit NSH (exit) *************** @@ -393,6 +435,8 @@ 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. +.. _cmdexport: + Set an Environment Variable (export) ************************************ @@ -438,6 +482,8 @@ examples: The ``export`` command is not supported by NSH unless both ``CONFIG_NSH_VARS=y`` and ``CONFIG_DISABLE_ENVIRON``\ is not set. +.. _cmdfree: + Show Memory Manager Status (free) ********************************* @@ -462,6 +508,8 @@ 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. ======= ====================================== +.. _cmdget: + Get File Via TFTP (get) *********************** @@ -480,6 +528,8 @@ whose IP address is identified by ````. ``-b`` Selects binary ("octet") transfer mode =================== ============================================ +.. _cmdhelp: + Show Usage Command Usage (help) ******************************* @@ -497,6 +547,8 @@ console. ```` Show full command usage only for this command. ========= ==================== +.. _cmdhexdump: + Hexadecimal Dump of File or Device (hexdump) ******************************************** @@ -516,6 +568,8 @@ The ``skip`` and ``count`` options are only available if ``CONFIG_NSH_CMDOPT_HEXDUMP`` is defined in the NuttX configuration. +.. _cmdifconfig: + Manage Network Configuration (ifconfig) *************************************** @@ -556,6 +610,8 @@ supported: nsh> mount -t procfs /proc +.. _cmdifdown: + Take a network down (ifdown) **************************** @@ -570,6 +626,8 @@ Take a network down (ifdown) ifdown eth0 +.. _cmdifup: + Bring a network up (ifup) ************************* @@ -584,6 +642,8 @@ Bring a network up (ifup) ifup eth0 +.. _cmdinsmod: + Install an OS module (insmod) ***************************** @@ -620,6 +680,7 @@ module . NAME INIT UNINIT ARG TEXT SIZE DATA SIZE mydriver 20404659 20404625 0 20404580 552 204047a8 0 +.. _cmdirqinfo: Show Interrupt Status (irqinfo) ******************************* @@ -639,6 +700,8 @@ attached interrupts. 15 0000800d 00000000 817 100.000 30 00000fd5 20000018 20 2.490 +.. _cmdkill: + Send a signal to a task (kill) ****************************** @@ -681,6 +744,8 @@ Send a signal to a task (kill) and to strand resource since there is insufficient clean-up in certain build configurations. +.. _cmdlosetup: + Setup/teardown the Loop Device (losetup) **************************************** @@ -724,6 +789,8 @@ on the loop-mounted file:: **Synopsis**. Teardown the setup for the loop device at . +.. _cmdln: + Link to a File or Directory (ln) ******************************** @@ -735,14 +802,16 @@ Link to a File or Directory (ln) at for the existing file or directory, . This implementation is simplified for use with NuttX in these ways: - - Links may be created only within the NuttX top-level, `pseudo - file system `__. No + - Links may be created only within the NuttX top-level, + :ref:`pseudo file system ` 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. +.. _cmdls: + List Directory Contents (ls) **************************** @@ -762,6 +831,8 @@ no other file system object. ``-l`` Show size and mode information along with the filenames in the listing. ====== ================================ +.. _cmdlsmod: + Show information about installed OS modules (lsmod) *************************************************** @@ -793,6 +864,8 @@ modules. This information includes: NAME INIT UNINIT ARG TEXT SIZE DATA SIZE mydriver 20404659 20404625 0 20404580 552 204047a8 0 +.. _cmdmd5: + Calculate MD5 (md5) ******************* @@ -802,6 +875,8 @@ Calculate MD5 (md5) **Synopsis**. *To be provided.* +.. _cmdmx: + Access Memory (mb, mh, and mw) ****************************** @@ -839,6 +914,8 @@ accesses (mh), or 32-bit access (mw). In each case, 14 = 0x0c1e nsh> +.. _cmdps: + Show Current Tasks and Threads (ps) *********************************** @@ -863,6 +940,8 @@ have been mounted with a command like:: nsh> mount -t procfs /proc +.. _cmdmkdir: + Create a Directory (mkdir) ************************** @@ -875,10 +954,10 @@ of ```` 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 `__ +:ref:`pseudo file system ` 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 +:ref:`mount ` command; it cannot be used to create directories in the *pseudo* file system. **Example**:: @@ -890,6 +969,8 @@ directories in the *pseudo* file system. drw-rw-rw- 0 TMP/ nsh> +.. _cmdmkfatfs: + Create a FAT File System (mkfatfs) ********************************** @@ -914,11 +995,12 @@ 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()`` `__ NuttX API. This block device must -reside in the NuttX `pseudo file -system `__ and must have -been created by some call to ``register_blockdriver()`` (see -``include/nuttx/fs/fs.h``). +``mkfatfs()`` NuttX API. This block device must +reside in the NuttX :ref:`pseudo file system ` +and must have been created by some call to ``register_blockdriver()`` +(see ``include/nuttx/fs/fs.h``). + +.. _cmdmkfifo: Create a FIFO (mkfifo) ********************** @@ -933,7 +1015,7 @@ be needed to complete the ````. 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()`` `__ NuttX API. +```mkfifo()`` NuttX API. **Example**:: @@ -952,6 +1034,8 @@ driver. NSH provides this command to access the brw-rw-rw- 0 ram0 nsh> +.. _cmdmkrd: + Create a RAMDISK (mkrd) *********************** @@ -995,6 +1079,8 @@ Once the ramdisk has been created, it may be formatted using the /tmp: nsh> +.. _cmdmount: + Mount a File System (mount) *************************** @@ -1017,24 +1103,23 @@ way association, binding: ````. As of this writing, ``vfat`` is the only supported value for ```` #. **Block Device.** The ```` argument is the full - or relative path to a block driver inode in the `pseudo file - system `__. By + or relative path to a block driver inode in the + :ref:`pseudo file system `. By convention, this is a name under the ``/dev`` sub-directory. This ```` must have been previously formatted with the same file system type as specified by ```` #. **Mount Point.** The mount point, ````, is the - location in the `pseudo file - system `__ where the - mounted volume will appear. This mount point can only reside in - the NuttX `pseudo file - system `__. By + location in the :ref:`pseudo file system ` + where the mounted volume will appear. This mount point can only + reside in the NuttX + :ref:`pseudo file system `. 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 `__, it may be +After the volume has been mounted in the NuttX +:ref:`pseudo file system `, it may be access in the same way as other objects in the file system. **Examples**: @@ -1068,6 +1153,8 @@ Using ``mount`` to enumerate mounts:: /mnt/fs type vfat /tmp type vfat +.. _cmdmv: + Rename a File (mv) ****************** @@ -1079,6 +1166,8 @@ Rename a File (mv) ````. Both paths must reside in the same mounted file system. +.. _cmdnfsmount: + Mount an NFS file system (nfsmount) *********************************** @@ -1090,6 +1179,8 @@ Mount an NFS file system (nfsmount) at on the target machine. is the IP address of the remote server. +.. _cmdnslookup: + Lookup a network address (nslookup) *********************************** @@ -1100,6 +1191,8 @@ Lookup a network address (nslookup) **Synopsis**. Lookup and print the IP address associated with ````. +.. _cmdpasswd: + Change a User's Password (passwd) ********************************* @@ -1110,6 +1203,8 @@ Change a User's Password (passwd) **Synopsis**. Set the password for the existing user to . +.. _cmdpmconfig: + Manage Power Management Subsystem (pmconfig) ******************************************** @@ -1119,6 +1214,8 @@ Manage Power Management Subsystem (pmconfig) **Synopsis**. Control power management subsystem. +.. _cmdpoweroff: + Shut the system down (poweroff) ******************************* @@ -1134,6 +1231,8 @@ to provide power off mode to board-specific power off logic. NOTE: Supporting both the ``poweroff`` and ``shutdown`` commands is redundant. +.. _cmdput: + Send File Via TFTP (put) ************************ @@ -1153,6 +1252,8 @@ whose IP address is identified by ````. transfer mode. Default: text. ==================== ============================================= +.. _cmdpwd: + Show Current Working Directory (pwd) ************************************ @@ -1173,6 +1274,8 @@ Same as ``echo $PWD``:: /dev nsh> +.. _cmdreadlink: + Show target of a link (readlink) ******************************** @@ -1183,6 +1286,8 @@ Show target of a link (readlink) **Synopsis**. Show the target of the soft link at the path ````. +.. _cmdreboot: + Reboot the system (reboot) ************************** @@ -1198,6 +1303,8 @@ a reboot mode to board-specific reboot logic. NOTE: Supporting both the ``reboot`` and ``shutdown`` commands is redundant. +.. _cmdrm: + Remove a File (rm) ****************** @@ -1206,11 +1313,11 @@ Remove a File (rm) rm **Synopsis**. Remove the specified ```` name from the -mounted file system. Recall that NuttX uses a `pseudo file -system `__ for its root +mounted file system. Recall that NuttX uses a +:ref:`pseudo file system ` 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 +:ref:`mount ` command; it cannot be used to remove names in the *pseudo* file system. **Example**:: @@ -1225,6 +1332,8 @@ names in the *pseudo* file system. TESTFILE.TXT nsh> +.. _cmdrmdir: + Remove a Directory (rmdir) ************************** @@ -1233,11 +1342,11 @@ Remove a Directory (rmdir) rmdir **Synopsis**. Remove the specified ```` directory from -the mounted file system. Recall that NuttX uses a `pseudo file -system `__ for its root +the mounted file system. Recall that NuttX uses a +:ref:`pseudo file system ` 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* +directories from volumes set up with the :ref:`mount ` +command it cannot be used to remove directories from the *pseudo* file system. **Example**:: @@ -1253,6 +1362,8 @@ file system. drw-rw-rw- 0 TESTDIR/ nsh> +.. _cmdrmmod: + Remove on OS Module (rmmod) *************************** @@ -1274,6 +1385,8 @@ busy. NAME INIT UNINIT ARG TEXT SIZE DATA SIZE nsh> +.. _cmdroute: + Show routing table (route) ************************** @@ -1287,6 +1400,8 @@ If only IPv4 or IPv6 is enabled, then the argument is optional but, if provided, must match the enabled internet protocol version. +.. _cmdrptun: + Start/Stop the OpenAMP RPC Tunnel (rptun) ***************************************** @@ -1296,6 +1411,8 @@ Start/Stop the OpenAMP RPC Tunnel (rptun) **Synopsis**. Start or stop the OpenAMP RPC tunnel device at . +.. _cmdset: + Set a Variable (set) ******************** @@ -1320,7 +1437,7 @@ 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 +variable via the :ref:`export `, then the ``set`` command will set the value of the environment variable rather than the local NSH variable. @@ -1372,6 +1489,8 @@ script commands and set foobar to foovalue:: nsh> echo $foobar foovalue +.. _cmdsh: + Execute an NSH Script (sh) ************************** @@ -1382,6 +1501,8 @@ Execute an NSH Script (sh) **Synopsis**. Execute the sequence of NSH commands in the file referred to by ````. +.. _cmdshutdown: + Shut the system down (shutdown) ******************************* @@ -1397,6 +1518,8 @@ behavior may be supported. NOTE: The ``shutdown`` command duplicates the behavior of the ``poweroff`` and ``eboot`` commands. +.. _cmdsleep: + Wait for Seconds (sleep) ************************ @@ -1406,6 +1529,8 @@ Wait for Seconds (sleep) **Synopsis**. Pause execution (sleep) for ```` seconds. +.. _cmdtelnetd: + Time Start the Telnet Daemon (telnetd) ************************************** @@ -1429,6 +1554,8 @@ command line or via other applications. In that case, when ``nsh_telnetstart()`` is called before the the network is initialized, it will fail. +.. _cmdtime: + Time execution of another command (time) **************************************** @@ -1483,6 +1610,8 @@ command is run in background with the sleep command:: nsh> 2.0100 sec +.. _cmdtruncate: + Set the Size of a File (truncate) ********************************* @@ -1500,6 +1629,8 @@ If a is larger than the specified size, the extra data is lost. If a is shorter, it is extended and the extended part reads as zero bytes. +.. _cmdumount: + Unmount a File System (umount) ****************************** @@ -1509,7 +1640,7 @@ Unmount a File System (umount) **Synopsis**. Un-mount the file system at mount point ````. The ``umount`` command can only be used to un-mount volumes previously -mounted using ```mount`` <#cmdmount>`__ command. +mounted using :ref:`mount ` command. **Example**:: @@ -1522,6 +1653,8 @@ mounted using ```mount`` <#cmdmount>`__ command. nsh: ls: no such directory: /mnt/fs nsh> +.. _cmduname: + Print system information (uname) ******************************** @@ -1544,6 +1677,8 @@ output is the same as -s. ``-p`` Print "unknown" ========== ======================================== +.. _cmdunset: + Unset an Environment Variable (unset) ************************************* @@ -1562,6 +1697,8 @@ and the group-wide environment variables. For example:: nsh> +.. _cmdurldecode: + URL Decode (urldecode) ********************** @@ -1571,6 +1708,8 @@ URL Decode (urldecode) **Synopsis**. *To be provided.* +.. _cmdurlencode: + URL Encode (urlencode) ********************** @@ -1580,6 +1719,8 @@ URL Encode (urlencode) **Synopsis**. *To be provided.* +.. _cmduseradd: + Add a New User (useradd) ************************ @@ -1589,6 +1730,8 @@ Add a New User (useradd) **Synopsis**. Add a new user with and . +.. _cmduserdel: + Delete a user (userdel) *********************** @@ -1598,6 +1741,8 @@ Delete a user (userdel) **Synopsis**. Delete the user with the name . +.. _cmdusleep: + Wait for Microseconds (usleep) ****************************** @@ -1607,6 +1752,8 @@ Wait for Microseconds (usleep) **Synopsis**. Pause execution (sleep) of ```` microseconds. +.. _cmdwget: + Get File Via HTTP (wget) ************************ @@ -1625,6 +1772,8 @@ directory. unless is provided. =================== ================================================= +.. _cmdxd: + Hexadecimal Dump of Memory (xd) ******************************* @@ -1661,6 +1810,8 @@ 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. +.. _cmdping: + Check Network Peer (ping/ping6) ******************************* diff --git a/Documentation/applications/nsh/config.rst b/Documentation/applications/nsh/config.rst index a2a277a445..fd46ce6af2 100644 --- a/Documentation/applications/nsh/config.rst +++ b/Documentation/applications/nsh/config.rst @@ -8,17 +8,19 @@ 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 +:ref:`cmdtable ` indicates the dependency of each command on NuttX configuration settings. General configuration settings are -discussed in the `NuttX Porting Guide. `__ +discussed in the NuttX Porting Guide. Configuration settings specific to NSH as discussed at the -`bottom <#nshconfiguration>`__ of this document. +:ref:`cmdbottom ` 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. +.. _cmddependencies: + Command Dependencies on Configuration Settings ============================================== @@ -26,125 +28,125 @@ 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`` +:ref:`cmdaddroute` ``CONFIG_NET`` && ``CONFIG_NET_ROUTE`` ``CONFIG_NSH_DISABLE_ADDROUTE`` +:ref:`cmdarp` ``CONFIG_NET`` && ``CONFIG_NET_ARP`` ``CONFIG_NSH_DISABLE_ARP`` +:ref:`cmdbase64dec` ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_BASE64DEC`` ``CONFIG_CODECS_BASE64`` -``base64enc`` ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_BASE64ENC`` +:ref:`cmdbase64enc` ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_BASE64ENC`` ``CONFIG_CODECS_BASE64`` -``basename`` . ``CONFIG_NSH_DISABLE_BASENAME`` -``break`` ! ``CONFIG_NSH_DISABLESCRIPT`` && . +:ref:`cmdbasename` . ``CONFIG_NSH_DISABLE_BASENAME`` +:ref:`cmdbreak` ! ``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`` +:ref:`cmdcat` ``CONFIG_NSH_DISABLE_CAT`` . +:ref:`cmdcd` ! ``CONFIG_DISABLE_ENVIRON`` ``CONFIG_NSH_DISABLE_CD`` +:ref:`cmdcmp` ``CONFIG_NSH_DISABLE_CMP`` . +:ref:`cmdcp` ``CONFIG_NSH_DISABLE_CP`` . +:ref:`cmddate` ``CONFIG_NSH_DISABLE_DATE`` . +:ref:`cmddd` ``CONFIG_NSH_DISABLE_DD`` . +:ref:`cmddelroute` ``CONFIG_NET`` && ``CONFIG_NET_ROUTE`` ``CONFIG_NSH_DISABLE_DELROUTE`` +:ref:`cmddf` ! ``CONFIG_DISABLE_MOUNTPOINT`` ``CONFIG_NSH_DISABLE_DF`` +:ref:`cmddirname` ``CONFIG_NSH_DISABLE_DIRNAME`` . +:ref:`cmddmesg` ``CONFIG_RAMLOG_SYSLOG`` ``CONFIG_NSH_DISABLE_DMESG`` +:ref:`cmdecho` ``CONFIG_NSH_DISABLE_ECHO`` . +:ref:`cmdenv` ``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`` && +:ref:`cmdexec` ``CONFIG_NSH_DISABLE_EXEC`` . +:ref:`cmdexit` ``CONFIG_NSH_DISABLE_EXIT`` . +:ref:`cmdexport` ``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`` +:ref:`cmdfree` ``CONFIG_NSH_DISABLE_FREE`` . +:ref:`cmdget` ``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`` +:ref:`cmdhelp` [#3]_ ``CONFIG_NSH_DISABLE_HELP`` . +:ref:`cmdhexdump` ``CONFIG_NSH_DISABLE_HEXDUMP`` . +:ref:`cmdifconfig` ``CONFIG_NET`` && ``CONFIG_FS_PROCFS`` && ``CONFIG_NSH_DISABLE_IFCONFIG`` ! ``CONFIG_FS_PROCFS_EXCLUDE_NET`` -``ifdown`` ``CONFIG_NET`` && ``CONFIG_FS_PROCFS`` && ``CONFIG_NSH_DISABLE_IFUPDOWN`` +:ref:`cmdifdown` ``CONFIG_NET`` && ``CONFIG_FS_PROCFS`` && ``CONFIG_NSH_DISABLE_IFUPDOWN`` ! ``CONFIG_FS_PROCFS_EXCLUDE_NET`` -``ifup`` ``CONFIG_NET`` && ``CONFIG_FS_PROCFS`` && +:ref:`cmdifup` ``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`` && . +:ref:`cmdinsmod` ``CONFIG_MODULE`` ``CONFIG_NSH_DISABLE_MODCMDS`` +:ref:`cmdirqinfo` ! ``CONFIG_DISABLE_MOUNTPOINT`` && . ``CONFIG_FS_PROCFS`` && |br| ``CONFIG_SCHED_IRQMONITOR`` -``kill`` ``CONFIG_NSH_DISABLE_KILL`` . -``losetup`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_LOSETUP`` +:ref:`cmdkill` ``CONFIG_NSH_DISABLE_KILL`` . +:ref:`cmdlosetup` ! ``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`` +:ref:`cmdln` ``CONFIG_PSEUDOFS_SOFTLINKS`` ``CONFIG_NSH_DISABLE_LN`` +:ref:`cmdls` ``CONFIG_NSH_DISABLE_LS`` . +:ref:`cmdlsmod` ``CONFIG_MODULE`` && ``CONFIG_FS_PROCFS`` ``CONFIG_NSH_DISABLE_MODCMDS`` && |br| ! ``CONFIG_FS_PROCFS_EXCLUDE_MODULE`` -``md5`` ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_MD5`` +:ref:`cmdmd5` ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_MD5`` ``CONFIG_CODECS_HASH_MD5`` -``mb,mh,mw`` . ``CONFIG_NSH_DISABLE_MB``, |br| +:ref:`cmdmx` . ``CONFIG_NSH_DISABLE_MB``, |br| ``CONFIG_NSH_DISABLE_MH``, |br| ``CONFIG_NSH_DISABLE_MW`` -``mkdir`` (! ``CONFIG_DISABLE_MOUNTPOINT`` \|\| ``CONFIG_NSH_DISABLE_MKDIR`` +:ref:`cmdmkdir` (! ``CONFIG_DISABLE_MOUNTPOINT`` \|\| ``CONFIG_NSH_DISABLE_MKDIR`` ! ``CONFIG_DISABLE_PSEUDOFS_OPERATIONS``) -``mkfatfs`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_MKFATFS`` +:ref:`cmdmkfatfs` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_MKFATFS`` ``CONFIG_FSUTILS_MKFATFS`` -``mkfifo`` ``CONFIG_PIPES`` && ``CONFIG_NSH_DISABLE_MKFIFO`` +:ref:`cmdmkfifo` ``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`` +:ref:`cmdmkrd` ! ``CONFIG_DISABLE_MOUNTPOINT`` ``CONFIG_NSH_DISABLE_MKRD`` +:ref:`cmdmount` ! ``CONFIG_DISABLE_MOUNTPOINT`` ``CONFIG_NSH_DISABLE_MOUNT`` +:ref:`cmdmv` ! ``CONFIG_DISABLE_MOUNTPOINT`` \|\| ``CONFIG_NSH_DISABLE_MV`` ! ``CONFIG_DISABLE_PSEUDOFS_OPERATIONS`` -``nfsmount`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_NFSMOUNT`` +:ref:`cmdnfsmount` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_NFSMOUNT`` ``CONFIG_NET`` && ``CONFIG_NFS`` -``nslookup`` ``CONFIG_LIBC_NETDB`` && ``CONFIG_NSH_DISABLE_NSLOOKUP`` +:ref:`cmdnslookup` ``CONFIG_LIBC_NETDB`` && ``CONFIG_NSH_DISABLE_NSLOOKUP`` ``CONFIG_NETDB_DNSCLIENT`` -``passwd`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_PASSWD`` +:ref:`cmdpasswd` ! ``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`` +:ref:`cmdpmconfig` ``CONFIG_PM`` ``CONFIG_NSH_DISABLE_PMCONFIG`` +:ref:`cmdpoweroff` ``CONFIG_BOARDCTL_POWEROFF`` ``CONFIG_NSH_DISABLE_POWEROFF`` +:ref:`cmdps` ``CONFIG_FS_PROCFS`` && ``CONFIG_NSH_DISABLE_PS`` ! ``CONFIG_FS_PROCFS_EXCLUDE_PROC`` -``put`` ``CONFIG_NET`` && ``CONFIG_NET_UDP`` && ``CONFIG_NSH_DISABLE_PUT`` +:ref:`cmdput` ``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`` +:ref:`cmdpwd` ! ``CONFIG_DISABLE_ENVIRON`` ``CONFIG_NSH_DISABLE_PWD`` +:ref:`cmdreadlink` ``CONFIG_PSEUDOFS_SOFTLINKS`` ``CONFIG_NSH_DISABLE_READLINK`` +:ref:`cmdreboot` ``CONFIG_BOARD_RESET`` ``CONFIG_NSH_DISABLE_REBOOT`` +:ref:`cmdrm` ! ``CONFIG_DISABLE_MOUNTPOINT`` \|\| ``CONFIG_NSH_DISABLE_RM`` ! ``CONFIG_DISABLE_PSEUDOFS_OPERATIONS`` -``rmdir`` ! ``CONFIG_DISABLE_MOUNTPOINT`` \|\ +:ref:`cmdrmdir` ! ``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`` +:ref:`cmdrmmod` ``CONFIG_MODULE`` ``CONFIG_NSH_DISABLE_MODCMDS`` +:ref:`cmdroute` ``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`` +:ref:`cmdrptun` ``CONFIG_RPTUN`` ``CONFIG_NSH_DISABLE_RPTUN`` +:ref:`cmdset` ``CONFIG_NSH_VARS`` \|\| ``CONFIG_NSH_DISABLE_SET`` ! ``CONFIG_DISABLE_ENVIRON`` -``shutdown`` ``CONFIG_BOARDCTL_POWEROFF`` \|\| ``CONFIG_NSH_DISABLE_SHUTDOWN`` +:ref:`cmdshutdown` ``CONFIG_BOARDCTL_POWEROFF`` \|\| ``CONFIG_NSH_DISABLE_SHUTDOWN`` ``CONFIG_BOARD_RESET`` -``sleep`` . ``CONFIG_NSH_DISABLE_SLEEP`` -``source`` ``CONFIG_FILE_STREAM`` && ``CONFIG_NSH_DISABLE_SOURCE`` +:ref:`cmdsleep` . ``CONFIG_NSH_DISABLE_SLEEP`` +``cmdsource`` ``CONFIG_FILE_STREAM`` && ``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`` +:ref:`cmdtelnetd` ``CONFIG_NSH_TELNET`` ``CONFIG_NSH_DISABLE_TELNETD`` +:ref:`cmdtest` ! ``CONFIG_NSH_DISABLESCRIPT`` ``CONFIG_NSH_DISABLE_TEST`` +:ref:`cmdtime` . ``CONFIG_NSH_DISABLE_TIME`` +:ref:`cmdtruncate` ! ``CONFIG_DISABLE_MOUNTPOINT`` ``CONFIG_NSH_DISABLE_TRUNCATE`` +:ref:`cmdumount` ! ``CONFIG_DISABLE_MOUNTPOINT`` ``CONFIG_NSH_DISABLE_UMOUNT`` +:ref:`cmduname` . ``CONFIG_NSH_DISABLE_UNAME`` +:ref:`cmdunset` ``CONFIG_NSH_VARS`` \|\| ``CONFIG_NSH_DISABLE_UNSET`` ! ``CONFIG_DISABLE_ENVIRON`` -``urldecode`` ! ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_URLDECODE`` +:ref:`cmdurldecode` ! ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_URLDECODE`` ``CONFIG_CODECS_URLCODE`` -``urlencode`` ! ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_URLENCODE`` +:ref:`cmdurlencode` ! ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_URLENCODE`` ``CONFIG_CODECS_URLCODE`` -``useradd`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_USERADD`` +:ref:`cmduseradd` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_USERADD`` ``CONFIG_NSH_LOGIN_PASSWD`` -``userdel`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_USERDEL`` +:ref:`cmduserdel` ! ``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`` +:ref:`cmdusleep` . ``CONFIG_NSH_DISABLE_USLEEP`` +:ref:`cmdwget` ``CONFIG_NET`` && ``CONFIG_NET_TCP`` ``CONFIG_NSH_DISABLE_WGET`` +:ref:`cmdxd` . ``CONFIG_NSH_DISABLE_XD`` ====================== =========================================== ====================== .. [#1] Because of hardware padding, the actual required packet size may be larger @@ -165,6 +167,8 @@ Command Depends on Configuration ``ping6`` ``CONFIG_NET`` && ``CONFIG_NET_ICMPv6`` && ``CONFIG_NET_ICMPv6_SOCKET`` && ``CONFIG_SYSTEM_PING6`` ============= ================================================================================================== +.. _nshconfiguration: + NSH-Specific Configuration Settings =================================== @@ -249,7 +253,7 @@ Configuration Description command works very must like the set command except that is operates on environment variables. When CONFIG_NSH_VARS is enabled, there are changes in the behavior of certain commands. - See following :ref:`table `. + See following :ref:`cmdtable `. ``CONFIG_NSH_QUOTE`` Enables back-slash quoting of certain characters within the command. This option is useful for the case where an NSH script diff --git a/Documentation/components/binfmt.rst b/Documentation/components/binfmt.rst index 61b6f6579f..d109a705fb 100644 --- a/Documentation/components/binfmt.rst +++ b/Documentation/components/binfmt.rst @@ -1,3 +1,5 @@ +.. _binfmt: + ============= Binary Loader ============= @@ -26,8 +28,8 @@ 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 `__. + NXFLAT binary format can be found in the :ref:`NXFLAT + documentation `. **Executables and Libraries** The generic binary loader logic does not care what it is that it being loaded. It could load an executable diff --git a/Documentation/components/drivers/block/index.rst b/Documentation/components/drivers/block/index.rst index 51a09ec25e..f82ca26a9d 100644 --- a/Documentation/components/drivers/block/index.rst +++ b/Documentation/components/drivers/block/index.rst @@ -14,7 +14,7 @@ Block device drivers have these properties: - ``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 + will appear in the :ref:`pseudo file system ` and it's initialized instance of ``struct block_operations``. - **User Access**. Users do not normally access block drivers diff --git a/Documentation/components/drivers/character/index.rst b/Documentation/components/drivers/character/index.rst index 6983fbb0be..d72b6ccf61 100644 --- a/Documentation/components/drivers/character/index.rst +++ b/Documentation/components/drivers/character/index.rst @@ -1,3 +1,5 @@ +.. _chardev: + ======================== Character Device Drivers ======================== @@ -15,12 +17,12 @@ Character device drivers have these properties: - ``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 + appear in the :ref:`pseudo file system ` 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 `__ including + driver can be accessed by user code using the standard driver + operations including ``open()``, ``close()``, ``read()``, ``write()``, etc. - **Specialized Character Drivers**. Within the common character diff --git a/Documentation/components/drivers/character/serial.rst b/Documentation/components/drivers/character/serial.rst index 2d1f5eb68e..f45e45aa8b 100644 --- a/Documentation/components/drivers/character/serial.rst +++ b/Documentation/components/drivers/character/serial.rst @@ -13,7 +13,7 @@ Serial Device Drivers - ``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 + appear in the :ref:`pseudo file system ` 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 diff --git a/Documentation/components/drivers/character/timer.rst b/Documentation/components/drivers/character/timer.rst index c557d00d5b..4ca12565d6 100644 --- a/Documentation/components/drivers/character/timer.rst +++ b/Documentation/components/drivers/character/timer.rst @@ -56,7 +56,7 @@ Timer Example The previously selected example will basically consult the timer status, set a timer alarm interval, set a timer signal handler function to be notified at the alarm, which only increments a variable, and then it will start the timer. The application will periodically consult the timer status at the sample rate previously configured through the ``menuconfig`` to follow the time left until the timer expires. After the samples have been read, the application stops de timer. -The `example code `_ may be explored, its path is at ``/examples/timer/timer_main.c`` in the apps' repository. +The `example code `_ may be explored, its path is at ``/examples/timer/timer_main.c`` in the apps' repository. In NuttX, the timer driver is a character driver and when a chip supports multiple timers, each one is accessible through its respective file in ``/dev`` directory. Each timer is registered using a unique numeric identifier (i.e. ``/dev/timer0``, ``/dev/timer1``, ...). @@ -84,12 +84,12 @@ The first necessary thing to be done in order to use the timer driver in an appl At an application level, the timer functionalities may be accessed through ``ioctl`` systems calls. The available ``ioctl`` commands are: -.. c:macro:: TCIOC_START -.. c:macro:: TCIOC_STOP -.. c:macro:: TCIOC_GETSTATUS -.. c:macro:: TCIOC_SETTIMEOUT -.. c:macro:: TCIOC_NOTIFICATION -.. c:macro:: TCIOC_MAXTIMEOUT + * :c:macro:`TCIOC_START` + * :c:macro:`TCIOC_STOP` + * :c:macro:`TCIOC_GETSTATUS` + * :c:macro:`TCIOC_SETTIMEOUT` + * :c:macro:`TCIOC_NOTIFICATION` + * :c:macro:`TCIOC_MAXTIMEOUT` These ``ioctl`` commands internally call lower-half layer operations and the parameters are forwarded to these ops through the ``ioctl`` system call. The return of a system call is the return of an operation. These ``struct timer_ops_s`` keeps pointers to the implementation of each operation. Following is the struct. diff --git a/Documentation/components/drivers/special/usbdev.rst b/Documentation/components/drivers/special/usbdev.rst index 23c0a6abff..589a60b7b7 100644 --- a/Documentation/components/drivers/special/usbdev.rst +++ b/Documentation/components/drivers/special/usbdev.rst @@ -8,8 +8,8 @@ USB Device-Side Drivers - ``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 `__. + USB trace capability is detailed in :ref:`separate + document `. - ``struct usbdev_s``. Each USB device controller driver must implement an instance of ``struct usbdev_s``. This structure is diff --git a/Documentation/components/nxflat.rst b/Documentation/components/nxflat.rst index f7547cb53b..ca1dffd3f2 100644 --- a/Documentation/components/nxflat.rst +++ b/Documentation/components/nxflat.rst @@ -1,3 +1,5 @@ +.. _nxflat: + ====== NXFLAT ====== diff --git a/Documentation/components/nxgraphics/appendix.rst b/Documentation/components/nxgraphics/appendix.rst index 6167f863d9..ec0e4b8f8c 100644 --- a/Documentation/components/nxgraphics/appendix.rst +++ b/Documentation/components/nxgraphics/appendix.rst @@ -46,7 +46,7 @@ provided in sub-directories under ``nuttx/libnx``. 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 `__ code is provided as a separate + The :ref:`NxWidgets ` 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 diff --git a/Documentation/components/nxgraphics/index.rst b/Documentation/components/nxgraphics/index.rst index aecda44858..7c0614be4a 100644 --- a/Documentation/components/nxgraphics/index.rst +++ b/Documentation/components/nxgraphics/index.rst @@ -1,3 +1,5 @@ +.. _nxgraphics: + ===================== NX Graphics Subsystem ===================== @@ -135,7 +137,7 @@ than some utilities and types from NXGLIB. NX Widgets (``NxWidgets``) -------------------------- -`NxWidgets `__ is a higher level, C++, object-oriented +:ref:`NxWidgets ` 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 diff --git a/Documentation/components/nxwidgets.rst b/Documentation/components/nxwidgets.rst index ce880512de..6db9cb69a5 100644 --- a/Documentation/components/nxwidgets.rst +++ b/Documentation/components/nxwidgets.rst @@ -1,11 +1,13 @@ +.. _nxwidgets: + ========= 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 `__ in order to provide graphic +C++ and integrates seamlessly with the NuttX :ref:`NX graphics +subsystem ` in order to provide graphic objects, or "widgets," in the NX Graphics Subsystem Some of the features of NXWidgets include: @@ -14,8 +16,8 @@ Some of the features of NXWidgets include: 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 `__. Think of the X +- **NX Integration**. NXWidgets integrate seamlessly with the + :ref:`NX graphics subsystem `. 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 @@ -40,7 +42,7 @@ Some of the features of NXWidgets include: - **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 +Antony Dzeryn's "Woopsi" project which also has a BSD style license. See the COPYING file for details. NXWidgets Doxygen Documentation diff --git a/Documentation/components/paging.rst b/Documentation/components/paging.rst index ecede3a5e3..5aa55fb87e 100644 --- a/Documentation/components/paging.rst +++ b/Documentation/components/paging.rst @@ -1,3 +1,5 @@ +.. _ondemandpaging: + ================ On-Demand Paging ================ diff --git a/Documentation/conf.py b/Documentation/conf.py index 40cda45fd8..734e95b699 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -117,3 +117,11 @@ c_id_attributes = [ 'noreturn_function' ] +# This is required to allow running linkcheck with sphinx-tabs +sphinx_tabs_valid_builders = ['linkcheck'] + +# There are some sites where the linkchecker cannot handle anchors +linkcheck_ignore = [ + 'https://github.com/pyenv/pyenv#installation', + 'http://openocd.zylin.com/#/c/4103/', +] diff --git a/Documentation/guides/drivers.rst b/Documentation/guides/drivers.rst index 983c701ef4..4ff167fef8 100644 --- a/Documentation/guides/drivers.rst +++ b/Documentation/guides/drivers.rst @@ -7,6 +7,8 @@ Drivers Some NuttX boards don't have full support for all the on-chip peripherals. If you need support for this hardware, you will either need to port a driver from another chip, or write one yourself. This section discusses how to do that. +.. _drivers-porting: + Porting a Driver ---------------- diff --git a/Documentation/guides/nfs.rst b/Documentation/guides/nfs.rst index fda1a842e4..d603613fec 100644 --- a/Documentation/guides/nfs.rst +++ b/Documentation/guides/nfs.rst @@ -26,8 +26,7 @@ Mount Interface A low-level, C-callable interface is provided to mount a file system. That interface is called ``mount()`` and is mentioned in the -```porting guide`` `__ and is -prototyped in the header file ``include/sys/mount.h``: +porting guide and is prototyped in the header file ``include/sys/mount.h``: .. c:function:: int mount(const char *source, const char *target, const char *filesystemtype, unsigned long mountflags, const void *data) @@ -108,7 +107,7 @@ is defined as: NFS Mount Command ================= -The `NuttShell (NSH) `__ also supports a command called +The :ref:`NuttShell (NSH) ` also supports a command called ``nfsmount`` that can be used to mount a remote file system via the NSH command line. diff --git a/Documentation/guides/tasktraceinternal.rst b/Documentation/guides/tasktraceinternal.rst index 3e01598988..d2eefd6ab9 100644 --- a/Documentation/guides/tasktraceinternal.rst +++ b/Documentation/guides/tasktraceinternal.rst @@ -42,14 +42,14 @@ Noteram device driver (``nuttx/drivers/note/noteram_driver.c``) - Accumurate incoming note records into the buffer. - Read the note records from the buffer by user requests. - The notes are recorded in the binary format of ``struct note_*_s``. -- The detail function is described in :doc:`../reference/os/note`. +- The detail function is described in :doc:`../components/drivers/character/note`. Notectl device driver (``nuttx/drivers/note/notectl_driver.c``) --------------------------------------------------------------- - ``/dev/notectl`` device driver. - Control the filter logic in ``sched_note.c`` by calling note filter APIs. -- The detail function is described in :doc:`../reference/os/note`. +- The detail function is described in :doc:`../components/drivers/character/note`. "``trace``" Built-In Application (``apps/system/trace/trace.c``) ---------------------------------------------------------------- diff --git a/Documentation/guides/tasktraceuser.rst b/Documentation/guides/tasktraceuser.rst index b04db80ab8..a17657fb7c 100644 --- a/Documentation/guides/tasktraceuser.rst +++ b/Documentation/guides/tasktraceuser.rst @@ -59,7 +59,7 @@ The following configurations are configurable parameters for trace. After the configuration, rebuild the NuttX kernel and application. -If the trace function is enabled, "``trace``" :doc:`../components/nsh/builtin` will be available. +If the trace function is enabled, "``trace``" :doc:`../applications/nsh/builtin` will be available. How to get trace data ===================== diff --git a/Documentation/guides/usbtrace.rst b/Documentation/guides/usbtrace.rst index 0140a7265a..29358456ca 100644 --- a/Documentation/guides/usbtrace.rst +++ b/Documentation/guides/usbtrace.rst @@ -1,3 +1,5 @@ +.. _usbtrace: + ================ USB Device Trace ================ diff --git a/Documentation/introduction/about.rst b/Documentation/introduction/about.rst index 1cd8097646..fdee8aa8ae 100644 --- a/Documentation/introduction/about.rst +++ b/Documentation/introduction/about.rst @@ -222,7 +222,7 @@ Key features of NuttX include: The following packages are available to extend the basic NuttX feature set: * **NuttShell (NSH)** - A small, scalable, bash-like shell for NuttX with rich feature set and small footprint. See the :doc:`/components/nsh/index`. + A small, scalable, bash-like shell for NuttX with rich feature set and small footprint. See the :doc:`/applications/nsh/index`. * **BAS 2.4** Seamless integration of Michael Haardt's BAS 2.4: "Bas is an interpreter for the classic dialect of the programming language BASIC. It is pretty compatible to typical BASIC interpreters of the 1980s, unlike some other UNIX BASIC interpreters, that implement a different syntax, breaking compatibility to existing programs. Bas offers many ANSI BASIC statements for structured programming, such as procedures, local variables and various loop types. Further there are matrix operations, automatic LIST indentation and many statements and functions found in specific classic dialects. Line numbers are not required." diff --git a/Documentation/introduction/detailed_support.rst b/Documentation/introduction/detailed_support.rst index 4c49ff2f83..a9948ccb44 100644 --- a/Documentation/introduction/detailed_support.rst +++ b/Documentation/introduction/detailed_support.rst @@ -70,8 +70,7 @@ TI TMS320-DM320 (also called **DM320**) NuttX operates on the ARM9 of -this dual core processor. This port uses the `Neuros -OSD `__ +this dual core processor. This port uses the Neuros OSD with a GNU arm-nuttx-elf toolchain\* under Linux or Cygwin. The port was performed using the OSD v1.0, development board. @@ -80,15 +79,12 @@ NXP LPC3131 Two boards based on the NXP LPC3131 are supported: -- First, a port for the NXP - `LPC3131 `__ - on the `Embedded Artists - EA3131 `__ +- First, a port for the NXP LPC3131 + on the Embedded Artists EA3131 development board was first released in NuttX-5.1 (but was not functional until NuttX-5.2). -- A second port to the NXP - `LPC3131 `__ +- A second port to the NXP LPC3131 on the `Olimex LPC-H3131 `__ development board was added in NuttX-6.32. @@ -96,8 +92,7 @@ Two boards based on the NXP LPC3131 are supported: NXP LPC315x ----------- -Support for the NXP -`LPC315x `__ +Support for the NXP LPC315x family has been incorporated into the code base as of NuttX-6.4. Support was added for the Embedded Artists EA3152 board in NuttX-6.11. @@ -515,7 +510,7 @@ TI/Stellaris LM3S6432S2E ------------------------ This port uses Serial-to-Ethernet Reference -Design Kit (`RDK-S2E `__) and has +Design Kit and has similar support as for the other Stellaris family members. A configuration is available for the NuttShell (NSH) (see :ref:`NSH `). The NSH configuration including networking support with a Telnet NSH console. @@ -525,7 +520,7 @@ TI/Stellaris LM3S6918 --------------------- This port uses the -`Micromint <%20http://www.micromint.com/>`__ Eagle-100 development board +`Micromint `__ Eagle-100 development board with a GNU arm-nuttx-elf toolchain\* under either Linux or Cygwin. **Development Environments:** 1) Linux with native Linux GNU toolchain, @@ -623,7 +618,7 @@ This is a port for the Silicon Laboratories' EFM32 required to make further progress in testing. Refer to the Olimex EFM32G880F120-STK - `README.txt `__ + `README.txt `__ for further information. SiLabs EFM32 Giant Gecko @@ -850,7 +845,7 @@ specifically for: STM32F103ZET6, STM32F103RET6, STM32F103VCT, STM32F103VET6, STM32F103RBT6, and STM32103CBT6. Boards supported include: -#. **STM3210E-EVAL**. A port for the `STMicro <%20http://www.st.com/>`__ +#. **STM3210E-EVAL**. A port for the `STMicro `__ STM3210E-EVAL development board that features the STM32F103ZET6 MCU. Refer to the NuttX board `README `__ @@ -962,8 +957,8 @@ board `README `__ file for further information. -**ViewTool STM32F103/F107** Support for the `Viewtool -STM32F103/F107 `__ board was added in +**ViewTool STM32F103/F107** Support for the Viewtool +STM32F103/F107 board was added in NuttX-6.32. That board features the STMicro STM32F107VCT6 MCU. Networking, LCD, and touchscreen support were added in NuttX-6.33. @@ -1184,7 +1179,6 @@ boards. This board configuration was contributed and made available in NuttX-6.20. As contributed board support, I am unsure of what all has been verfied and what has not. See the Microment website - `Lincoln60 `__ board and the NuttX board `README `__ file for further information about the Lincoln board. @@ -1222,7 +1216,7 @@ The port of NuttX to the WaveShare Open1788 is a collaborative effort between Rommel Marcelo and myself (with Rommel being the leading contributor and I claiming only a support role). You can get more information at the Open1788 board from the WaveShare -`website `__. +website. ON Semiconductor LC823450 ------------------------- @@ -1858,8 +1852,7 @@ Three boards are supported in this family: - **STM32L476 MDK**. Very basic support for NuttX on the Motorola Moto Z MDK was contributed by Jim Wylder in NuttX 7.18. A simple NSH - configuration is available for the STM32L476 chip. See the `Moto Mods - Development Kit `__ and the board + configuration is available for the STM32L476 chip. See the board `README `__ file for further information. @@ -2866,12 +2859,7 @@ Microchip PIC32MX4xx **PIC32MX440F512H**. This port uses the "Advanced USB Storage Demo Board," Model DB-DP11215, from `Sure Electronics `__. This board features the -Microchip PIC32MX440F512H. See the `Sure -website `__ for -further information about the DB-DP11215 board. (I believe that that the -DB-DP11215 may be obsoleted now but replaced with the very similar, -DB-DP11212. The DB-DP11212 board differs, I believe, only in its serial -port configuration.) +Microchip PIC32MX440F512H. **PIC32MX460F512L**. There one two board ports using this chip: @@ -2895,7 +2883,7 @@ PIC32MX795F512L. There one two board ports using this chip: - **Microchip PIC32 Ethernet Starter Kit**. This port uses the Microchip PIC32 Ethernet Starter Kit (DM320004) with the Expansion - I/O board. See the `Microchip website `__ + I/O board. See the `Microchip website `__ for further information. - **Mikroelektronika PIC32MX7 Mulitmedia Board (MMB)**. A port has been completed for the Mikroelektronika PIC32MX7 Multimedia Board (MMB). @@ -3122,13 +3110,11 @@ environment is either Windows native or Cygwin under Windows. **STATUS:** This release has been verified only on the ZiLOG ZDS-II Z8Encore! chip simulation as of nuttx-0.3.9. Refer to the NuttX board README files for the -`z8encore000zco `__ +`z8encore000zco `__ and for -the\ `z8f64200100kit `__ +the\ `z8f64200100kit `__ for further information. - - Zilog Z180 ========== diff --git a/Documentation/introduction/resources.rst b/Documentation/introduction/resources.rst index 8fc4855ff9..0ac8cf4471 100644 --- a/Documentation/introduction/resources.rst +++ b/Documentation/introduction/resources.rst @@ -8,12 +8,12 @@ Here's a list of Apache NuttX resources that you might find helpful: * Apache NuttX - * `Apache NuttX website `_ - * `Apache NuttX online documentation `_ + * `Apache NuttX website `_ + * `Apache NuttX online documentation `_ * `Apache NuttX mailing list `_ – a very active mailing list, the place to get help with your application or any questions you have about NuttX. * `Apache NuttX YouTube channel `_ – Alan Carvalho de Assis's YouTube channel on NuttX. It's a source of a lot of great practical information. * `Apache NuttX Coding Standard `_ — How code should look when you submit new files or modify existing ones. - * `Apache NuttX Code Contribution Guidlines `_ — The full workflow to follow for submitting code with all the details. + * `Apache NuttX Code Contribution Guidlines `_ — The full workflow to follow for submitting code with all the details. * Git diff --git a/Documentation/quickstart/compiling.rst b/Documentation/quickstart/compiling.rst index 94cc5cdd2f..55f81d1350 100644 --- a/Documentation/quickstart/compiling.rst +++ b/Documentation/quickstart/compiling.rst @@ -23,7 +23,7 @@ a pre-existing configuration. To list all supported configurations you can do: The output is in the format ``:``. You will see that generally all boards support the ``nsh`` configuration which is a good sarting point since it enables booting into the interactive command line -:doc:`/components/nsh/index`. +:doc:`/applications/nsh/index`. To choose a configuration you pass the ``:`` option to ``configure.sh`` and indicate your host platform, such as: diff --git a/Documentation/quickstart/organization.rst b/Documentation/quickstart/organization.rst index eaf3b9598f..e2a1044ea2 100644 --- a/Documentation/quickstart/organization.rst +++ b/Documentation/quickstart/organization.rst @@ -78,8 +78,8 @@ README.md file for information on how to build it. ``nuttx/arch`` ============== -Subdirectory Structure ----------------------- +Arch Subdirectory Structure +--------------------------- This directory contains several sub-directories, each containing architecture-specific logic. The task of porting NuttX to a new @@ -91,8 +91,8 @@ directory (plus the board-specific configurations in the subdirectory, ** under ``arch/`` with the following characteristics: -Summary of Files ----------------- +Arch Summary of Files +--------------------- - ``include/``\ **\ ``/`` This sub-directory contains chip-specific header files. @@ -252,16 +252,16 @@ configurations plus the architecture-specific configurations in the ``arch/`` subdirectory complete define a customized port of NuttX. -Subdirectory Structure ----------------------- +Boards Subdirectory Structure +----------------------------- The ``boards/`` directory contains board specific configuration files. Each board must provide a sub-directory under ``boards/``\ **\ ``/``>\ **\ ``/`` with the following characteristics: -Summary of Files ----------------- +Boards Summary of Files +----------------------- **Board Specific Logic** diff --git a/Documentation/reference/os/paging.rst b/Documentation/reference/os/paging.rst index 3c303823de..9a4c5baab9 100644 --- a/Documentation/reference/os/paging.rst +++ b/Documentation/reference/os/paging.rst @@ -9,5 +9,5 @@ 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. Design and porting issues for this feature are discussed in a separate document. Please see the -`NuttX Demand Paging `__ design document +:ref:`NuttX Demand Paging ` design document for further information. diff --git a/Documentation/reference/user/01_task_control.rst b/Documentation/reference/user/01_task_control.rst index f0deda4684..3b4566f66f 100644 --- a/Documentation/reference/user/01_task_control.rst +++ b/Documentation/reference/user/01_task_control.rst @@ -30,8 +30,8 @@ pthreads the were started from the same parent thread. **Executing Programs within a File System**. NuttX also provides internal interfaces for the execution of separately built programs that reside in a file system. These internal interfaces are, however, -non-standard and are documented with the NuttX `binary -loader `__ and `NXFLAT `__. +non-standard and are documented with the NuttX binary +loader and NXFLAT documentation. **Task Control Interfaces**. The following task control interfaces are provided by NuttX: diff --git a/Documentation/reference/user/10_filesystem.rst b/Documentation/reference/user/10_filesystem.rst index 4d2762ef35..e867a31126 100644 --- a/Documentation/reference/user/10_filesystem.rst +++ b/Documentation/reference/user/10_filesystem.rst @@ -2,6 +2,8 @@ File System Interfaces ====================== +.. _file_system_overview: + NuttX File System Overview ========================== @@ -20,7 +22,7 @@ system). Any user supplied data or logic can be accessed via the pseudo-file system. Built in support is provided for character and block -`driver `__ *nodes* in the any +:ref:`driver ` *nodes* in the any pseudo file system directory. (By convention, however, all driver nodes should be in the ``/dev`` pseudo file system directory). diff --git a/Documentation/reference/user/11_network.rst b/Documentation/reference/user/11_network.rst index f3bbe0d8ce..0165485bd8 100644 --- a/Documentation/reference/user/11_network.rst +++ b/Documentation/reference/user/11_network.rst @@ -3,8 +3,8 @@ Network Interfaces ================== NuttX supports a BSD-compatible socket interface layer. These socket -interface can be enabled by settings in the architecture `configuration -file `__. Those socket APIs are discussed in +interface can be enabled by settings in the architecture configuration +file. Those socket APIs are discussed in the following paragraphs. - :c:func:`socket` diff --git a/Documentation/reference/user/index.rst b/Documentation/reference/user/index.rst index 4eb87e103c..ce0aa484b0 100644 --- a/Documentation/reference/user/index.rst +++ b/Documentation/reference/user/index.rst @@ -12,12 +12,12 @@ implementing applications on NuttX. Specifically, this documented is limited to addressing only NuttX RTOS APIs that are available to the application developer. As such, this document does not focus on any technical details of the organization or implementation of NuttX. Those -technical details are provided in the `NuttX Porting -Guide `__. +technical details are provided in the NuttX Porting +Guide. Information about configuring and building NuttX is also needed by the -application developer. That information can also be found in the `NuttX -Porting Guide `__. +application developer. That information can also be found in the NuttX +Porting Guide. .. toctree:: :maxdepth: 1 diff --git a/Documentation/reference/user/structures.rst b/Documentation/reference/user/structures.rst index f291cc1e52..73df918c61 100644 --- a/Documentation/reference/user/structures.rst +++ b/Documentation/reference/user/structures.rst @@ -106,7 +106,7 @@ NuttX and a MoBY application: size_t mq_curmsgs; /* Number of messages currently in queue */ }; -.. note that this gives a warning due to https://github.com/sphinx-doc/sphinx/issues/7819 +.. note that this gives a warning due to https://github.com/sphinx-doc/sphinx/issues/7819 https://github.com/sphinx-doc/sphinx/pull/8313 .. c:struct:: sigaction