diff --git a/Documentation/_templates/layout.html b/Documentation/_templates/layout.html index 2a3ebcdaf1..8f7c20e5f0 100644 --- a/Documentation/_templates/layout.html +++ b/Documentation/_templates/layout.html @@ -32,10 +32,10 @@ {% endif %} - + - +
- + {% include "searchbox.html" %} {% endblock %} diff --git a/Documentation/applications/index.rst b/Documentation/applications/index.rst index a718161de0..464f9c9d2e 100644 --- a/Documentation/applications/index.rst +++ b/Documentation/applications/index.rst @@ -1,10 +1,10 @@ .. todo:: Applications included in ``apps`` repo should be documented here. This should also include information - on how to create a given application. + on how to create a given application. Applications ============ -NuttX ships a large number of applications covering a wide spectrum of functionality. These can be found in the `apps `_ repository. At the moment, these are documented in their individual README files so you can find more information at the repository. +NuttX ships a large number of applications covering a wide spectrum of functionality. These can be found in the `apps `_ repository. At the moment, these are documented in their individual README files so you can find more information at the repository. diff --git a/Documentation/boards/index.rst b/Documentation/boards/index.rst index fa73bd14d9..7c3f711e89 100644 --- a/Documentation/boards/index.rst +++ b/Documentation/boards/index.rst @@ -1,9 +1,9 @@ -.. todo:: +.. todo:: Include a full list of supported boards, organized by architecture / family / vendor. Each board should have its own entry, a photo, brief hardware specifications, features supported (currently working in NuttX), how to flash, special toolchains required, etc. This will involve migrating most of the content existing currently in board README files - to RST documents here. + to RST documents here. Supported Boards ================ diff --git a/Documentation/components/binfmt.rst b/Documentation/components/binfmt.rst index 8fb237c338..61b6f6579f 100644 --- a/Documentation/components/binfmt.rst +++ b/Documentation/components/binfmt.rst @@ -87,7 +87,7 @@ pointer to a write-able instance of :c:struct:`binfmt_s`. structure is shown below: .. code-block:: c - + struct symtab_s; struct binary_s { @@ -137,9 +137,9 @@ pointer to a write-able instance of :c:struct:`binfmt_s`. Where the types ``binfmt_ctor_t`` and ``binfmt_dtor_t`` define the type of one C++ constructor or destructor: - + .. code-block:: c - + typedef FAR void (*binfmt_ctor_t)(void); typedef FAR void (*binfmt_dtor_t)(void); @@ -152,20 +152,20 @@ Binary format management .. c:function:: int register_binfmt(FAR struct binfmt_s *binfmt) Register a loader for a binary format. - + :return: This is a NuttX internal function so it follows the convention that 0 (OK) is returned on success and a negated errno is returned on failure. - + .. c:function:: int unregister_binfmt(FAR struct binfmt_s *binfmt) - Register a loader for a binary format. - + Register a loader for a binary format. + :return: This is a NuttX internal function so it follows the convention that 0 (OK) is returned on success and a negated errno is returned on failure. - + Basic module management ~~~~~~~~~~~~~~~~~~~~~~~ @@ -193,12 +193,12 @@ Basic module management (via :c:func:`exec_module`) and has not exited, calling this will be fatal. However, this function must be called after the module exist. How this is - done is up to your logic. Perhaps you register it to be called by :c:func:`on_exit`? + done is up to your logic. Perhaps you register it to be called by :c:func:`on_exit`? :return: This is a NuttX internal function so it follows the convention that 0 (``OK``) is returned on success and a negated ``errno`` is returned on failure. - + .. c:function:: int exec_module(FAR const struct binary_s *bin); Execute a module that has been loaded into memory by :c:func:`load_module`. @@ -209,10 +209,10 @@ Basic module management .. tip:: The function :c:func:`exec` is a convenience function that wraps - :c:func:`load_module` and :c:func:`exec_module` into one call. + :c:func:`load_module` and :c:func:`exec_module` into one call. ``PATH`` traversal logic -~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~ .. c:function:: ENVPATH_HANDLE envpath_init(void); @@ -232,17 +232,17 @@ Basic module management that may subsequently be used in calls to :c:func:`envpath_next` and :c:func:`envpath_release`. On error, a ``NULL`` handle value will be returned. The most likely cause of an error would be that there is no value - associated with the ``PATH`` variable. + associated with the ``PATH`` variable. .. c:function:: FAR char *envpath_next(ENVPATH_HANDLE handle, FAR const char *relpath) Traverse all possible values in the PATH variable in attempt to find the - full path to an executable file when only a relative path is provided. + full path to an executable file when only a relative path is provided. :param handle: The handle value returned by :c:func:`envpath_init`. :param relpath: The relative path to the file to be found. - :return: + :return: On success, a non-``NULL`` pointer to a null-terminated string is provided. This is the full path to a file that exists in the file system. This function will verify that the file exists (but will not verify that it is marked executable). @@ -262,7 +262,7 @@ Release all resources set aside by envpath_init when the handle value was created. The handle value is invalid on return from this function. Attempts to all :c:func:`envpath_next` or :c:func:`envpath_release` with such a stale handle will result -in undefined (i.e., not good) behavior. +in undefined (i.e., not good) behavior. :param handle: The handle value returned by :c:func:`envpath_init`. @@ -297,7 +297,7 @@ Symbol Table Data Structures Describes one entry in the symbol table. .. code-block:: c - + struct symtab_s { FAR const char *sym_name; /* A pointer to the symbol name string */ @@ -326,16 +326,16 @@ Symbol Table Function Interfaces to ``nsyms``. :return: - A reference to the symbol table entry if an entry with the matching name is found; NULL is returned if the entry is not found. - + A reference to the symbol table entry if an entry with the matching name is found; NULL is returned if the entry is not found. + .. c:function:: FAR const struct symtab_s *symtab_findorderedbyname(FAR const struct symtab_s *symtab, FAR const char *name, int nsyms); Find the symbol in the symbol table with the matching name. - This version assumes that table ordered with respect to symbol name. + This version assumes that table ordered with respect to symbol name. :return: A reference to the symbol table entry if an entry with - the matching name is found; NULL is returned if the entry is not found. + the matching name is found; NULL is returned if the entry is not found. .. c:function:: FAR const struct symtab_s *symtab_findbyvalue(FAR const struct symtab_s *symtab, FAR void *value, int nsyms); @@ -343,12 +343,12 @@ Symbol Table Function Interfaces Find the symbol in the symbol table whose value closest (but not greater than), the provided value. This version assumes that table is not ordered with respect to symbol name and, hence, - access time will be linear with respect to ``nsyms``. + access time will be linear with respect to ``nsyms``. :return: A reference to the symbol table entry if an entry with the matching name is found; ``NULL`` is returned if the entry is not found. - + Configuration Variables ======================= diff --git a/Documentation/components/drivers/character/index.rst b/Documentation/components/drivers/character/index.rst index e50dc89038..366cef5dff 100644 --- a/Documentation/components/drivers/character/index.rst +++ b/Documentation/components/drivers/character/index.rst @@ -50,7 +50,7 @@ Character device drivers have these properties: .. toctree:: :caption: Supported Drivers - + serial.rst touchscreen.rst analog.rst diff --git a/Documentation/components/drivers/character/timer.rst b/Documentation/components/drivers/character/timer.rst index 7710defdfc..c557d00d5b 100644 --- a/Documentation/components/drivers/character/timer.rst +++ b/Documentation/components/drivers/character/timer.rst @@ -16,7 +16,7 @@ locations: reside in ``arch/``\ **\ ``/src/``\ ** directory for the specific processor ** and for the specific ** timer peripheral devices. - + There are two ways to enable Timer Support along with the Timer Example. The first is faster and simpler. Just run the following command to use a ready config file with timer support and example included. You need to check if there's a timer config file for your specific chip. You may check it at the specific board's path: ``/boards////config``. .. code-block:: console @@ -49,30 +49,30 @@ Enabling the Timer Support and Example in ``menuconfing`` - [x] Timer example - Below the option, it is possible to manually configure some parameters as the standard timer device path, the timeout, the sample rate in which the counter will be read, the number of samples to be executed, and other parameters. - + Below the option, it is possible to manually configure some parameters as the standard timer device path, the timeout, the sample rate in which the counter will be read, the number of samples to be executed, and other parameters. + 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``, ...). +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``, ...). Use the following command to run the example: .. code-block:: console `nsh> timer` - + This command will use the timer 0. To use the others, specify it through a parameter (where x is the timer number): .. code-block:: console - `nsh> timer -d /dev/timerx` - -Application Level Interface + `nsh> timer -d /dev/timerx` + +Application Level Interface ---------------------------- The first necessary thing to be done in order to use the timer driver in an application is to include the header file for the NuttX timer driver. It contains the Application Level Interface to the timer driver. To do so, include: @@ -87,7 +87,7 @@ At an application level, the timer functionalities may be accessed through ``ioc .. c:macro:: TCIOC_START .. c:macro:: TCIOC_STOP .. c:macro:: TCIOC_GETSTATUS -.. c:macro:: TCIOC_SETTIMEOUT +.. c:macro:: TCIOC_SETTIMEOUT .. c:macro:: TCIOC_NOTIFICATION .. c:macro:: TCIOC_MAXTIMEOUT @@ -166,9 +166,9 @@ The ``TCIOC_START`` command calls the ``start`` operation, which is described be The start operation configures the timer, enables the interrupt if ``TCIOC_NOTIFICATION`` has already been called and finally starts the timer. - :return: A Linux System Error Code for failing or 0 for success. + :return: A Linux System Error Code for failing or 0 for success. -This command may be used like so: +This command may be used like so: .. code-block:: c @@ -192,9 +192,9 @@ The ``TCIOC_STOP`` command calls the ``stop`` operation, which is described belo The stop operation stops the timer and disables the interrupt. - :return: A Linux System Error Code for failing or 0 for success. + :return: A Linux System Error Code for failing or 0 for success. -This command may be used like so: +This command may be used like so: .. code-block:: c @@ -218,11 +218,11 @@ The ``TCIOC_GETSTATUS`` command calls the ``getstatus`` operation, which is desc The getstatus operation gathers the timer's current information. - :param status: A writable pointer to a struct ``timer_status_s``. This struct contains 3 fields: ``flags`` (``uint32_t``), ``timeout`` (``uint32_t``) and ``timeleft`` (``uint32_t``). Bit 0 from `flags` indicates the timer's status, 1 indicates that the timer is running, zero it is stopped. Bit 1 from `flags` indicates if there's a callback registered. The `timeout` indicates the time interval that was configured to trigger an alarm, it is in microseconds. The `timeleft` interval indicates how many microseconds it's missing to trigger the alarm. The following snippet demonstrates how to use it and how to access these fields. + :param status: A writable pointer to a struct ``timer_status_s``. This struct contains 3 fields: ``flags`` (``uint32_t``), ``timeout`` (``uint32_t``) and ``timeleft`` (``uint32_t``). Bit 0 from `flags` indicates the timer's status, 1 indicates that the timer is running, zero it is stopped. Bit 1 from `flags` indicates if there's a callback registered. The `timeout` indicates the time interval that was configured to trigger an alarm, it is in microseconds. The `timeleft` interval indicates how many microseconds it's missing to trigger the alarm. The following snippet demonstrates how to use it and how to access these fields. - :return: A Linux System Error Code for failing or 0 for success. + :return: A Linux System Error Code for failing or 0 for success. -This command may be used like so: +This command may be used like so: .. code-block:: c @@ -250,11 +250,11 @@ The ``TCIOC_SETTIMEOUT`` command calls the ``settimeout`` operation, which is de The getstatus operation sets a timeout interval to trigger the alarm and then trigger an interrupt. It defines the timer interval in which the handler will be called. - :param timeout: An argument of type ``uint32_t`` with the timeout value in microseconds. + :param timeout: An argument of type ``uint32_t`` with the timeout value in microseconds. - :return: A Linux System Error Code for failing or 0 for success. + :return: A Linux System Error Code for failing or 0 for success. -This command may be used like so: +This command may be used like so: .. code-block:: c @@ -273,11 +273,11 @@ This command may be used like so: .. c:macro:: TCIOC_NOTIFICATION -The ``TCIOC_NOTIFICATION`` is used to configure the timer callback to notify the application via a signal when the timer expires. This command calls the ``setcallback`` operation. Which will not be described here, since the application does not set a callback directly. Instead, the user should configure a signal handler to catch notifications, and then, configure a timer notifier to notify and to signal the previously configured signal handler. For a better performance, a separate pthread may be configured to wait on sigwaitinfo() for timer events. +The ``TCIOC_NOTIFICATION`` is used to configure the timer callback to notify the application via a signal when the timer expires. This command calls the ``setcallback`` operation. Which will not be described here, since the application does not set a callback directly. Instead, the user should configure a signal handler to catch notifications, and then, configure a timer notifier to notify and to signal the previously configured signal handler. For a better performance, a separate pthread may be configured to wait on sigwaitinfo() for timer events. In any case, this command expects a read-only pointer to a struct `timer_notify_s`. This struct contains 2 fields: ``pid`` (``pid_t``), that indicates the ID of the task/thread to receive the signal and ``event`` (``struct sigevent``), which describes the way a task will be notified. -This command may be used like so: +This command may be used like so: .. code-block:: c @@ -303,12 +303,12 @@ The ``TCIOC_MAXTIMEOUT`` command calls the ``maxtimeout`` operation, which is de .. c:function:: int maxtimeout(uint32_t *status) - The maxtimeout operation gets the maximum timeout value that can be configured. + The maxtimeout operation gets the maximum timeout value that can be configured. :param maxtimeout: A writable pointer to a variable of ``uint32_t`` type in which the value will be stored. - :return: A Linux System Error Code for failing or 0 for success. + :return: A Linux System Error Code for failing or 0 for success. -This command may be used like so: +This command may be used like so: .. code-block:: c @@ -330,4 +330,4 @@ This command may be used like so: Those snippets were taken from the Example which provides a great resource to demonstrate how to use those ``ioctl`` commands. - + diff --git a/Documentation/components/drivers/index.rst b/Documentation/components/drivers/index.rst index 5ccc1f0072..fb4821c4ac 100644 --- a/Documentation/components/drivers/index.rst +++ b/Documentation/components/drivers/index.rst @@ -1,7 +1,7 @@ ============== Device Drivers ============== - + NuttX supports a variety of device drivers, which can be broadly divided in three classes: @@ -10,8 +10,8 @@ divided in three classes: character/index.rst block/index.rst - special/index.rst - + special/index.rst + .. note:: Device driver support depends on the *in-memory*, *pseudo* file system that is enabled by default. diff --git a/Documentation/components/drivers/special/index.rst b/Documentation/components/drivers/special/index.rst index 1e8d4452de..f95fbdab49 100644 --- a/Documentation/components/drivers/special/index.rst +++ b/Documentation/components/drivers/special/index.rst @@ -21,7 +21,7 @@ following section. .. toctree:: :caption: Supported Drivers - + spi.rst i2c.rst ethernet.rst diff --git a/Documentation/components/index.rst b/Documentation/components/index.rst index 57ac542055..bda1802c34 100644 --- a/Documentation/components/index.rst +++ b/Documentation/components/index.rst @@ -1,8 +1,8 @@ OS Components ============= -NuttX is very feature-rich RTOS and is thus composed of various different subsystems. The following sections explain how each of these main RTOS components work and can be used. For detailed documentation on the specific API used in this case, you can head to the :doc:`reference <../reference/index>`. - +NuttX is very feature-rich RTOS and is thus composed of various different subsystems. The following sections explain how each of these main RTOS components work and can be used. For detailed documentation on the specific API used in this case, you can head to the :doc:`reference <../reference/index>`. + .. toctree:: :maxdepth: 2 :caption: Contents: diff --git a/Documentation/components/nsh/builtin.rst b/Documentation/components/nsh/builtin.rst index 338a539548..b158b8b559 100644 --- a/Documentation/components/nsh/builtin.rst +++ b/Documentation/components/nsh/builtin.rst @@ -135,17 +135,17 @@ registers the ``hello_main()`` application in the ``builtin``'s that in ``apps/examples/hello/Makefile`` is abstracted below: #. First, the ``Makefile`` includes ``apps/Make.defs``:: - + include $(APPDIR)/Make.defs This defines a macro called ``REGISTER`` that adds data to the *builtin* header files:: - + define REGISTER @echo "Register: $1" @echo "{ \"$1\", $2, $3, $4 }," >> "$(APPDIR)/builtin/builtin_list.h" @echo "EXTERN int $4(int argc, char *argv[]);" >> "$(APPDIR)/builtin/builtin_proto.h" - endef + endef When this macro runs, you will see the output in the build "``Register: hello``", that is a sure sign that the registration was @@ -154,21 +154,21 @@ that in ``apps/examples/hello/Makefile`` is abstracted below: #. The make file then defines the application name (``hello``), the task priority (default), and the stack size that will be allocated in the task runs (2K):: - + APPNAME = hello PRIORITY = SCHED_PRIORITY_DEFAULT STACKSIZE = 2048 - + #. And finally, the ``Makefile`` invokes the ``REGISTER`` macro to added the ``hello_main()`` builtin application. Then, when the system build completes, the ``hello`` command can be executed from the NSH command line. When the ``hello`` command is executed, it will start the task with entry point ``hello_main()`` with the default priority and with a stack size of 2K:: - + context: $(call REGISTER,$(APPNAME),$(PRIORITY),$(STACKSIZE),$(APPNAME)_main) - + **Other Uses of Built-In Application.** The primary purpose of builtin applications is to support command line execution of applications from diff --git a/Documentation/components/nsh/commands.rst b/Documentation/components/nsh/commands.rst index 3e125eee8d..5b00e091d0 100644 --- a/Documentation/components/nsh/commands.rst +++ b/Documentation/components/nsh/commands.rst @@ -406,7 +406,7 @@ examples: #. Using ``export`` to promote an NSH variable to an environment variable:: - + nsh> env PATH=/bin @@ -417,7 +417,7 @@ examples: nsh> export foo nsh> env PATH=/bin - foo=bar + foo=bar A group-wide environment variable is created with the same value as the local NSH variable; the local NSH variable is @@ -428,12 +428,12 @@ examples: environment variable of the same name and same value. #. Using ``export`` to set an environment variable:: - + nsh> export dog poop nsh> env PATH=/bin foo=bar - dog=poop + dog=poop The ``export`` command is not supported by NSH unless both ``CONFIG_NSH_VARS=y`` and ``CONFIG_DISABLE_ENVIRON``\ is not set. @@ -452,7 +452,7 @@ example:: total used free largest Mem: 4194288 1591552 2602736 2601584 nsh> - + **Where:** ======= ====================================== @@ -477,7 +477,7 @@ whose IP address is identified by ````. =================== ============================================ ``-f `` The file will be saved relative to the current working directory unless is provided. ``-n`` Selects text ("netascii") transfer mode (default). -``-b`` Selects binary ("octet") transfer mode +``-b`` Selects binary ("octet") transfer mode =================== ============================================ Show Usage Command Usage (help) @@ -509,7 +509,7 @@ character device ================= ================================== ``skip=`` Will skip number of bytes from the beginning. -``count=`` Will stop after dumping number of bytes. +``count=`` Will stop after dumping number of bytes. ================= ================================== The ``skip`` and ``count`` options are only available if @@ -529,9 +529,9 @@ supported: #. With one or no arguments, ``ifconfig`` will shows the current configuration of the network and, perhaps, the status of Ethernet device:: - + ifconfig - ifconfig [nic_name] + ifconfig [nic_name] As an example:: @@ -545,7 +545,7 @@ supported: #. If both the network interface name and an IP address are supplied as arguments, then ``ifconfig`` will set the address of the Ethernet device:: - + ifconfig nic_name ip_address #. Other forms *to be provided* @@ -553,7 +553,7 @@ supported: .. note:: This commands depends upon having the *procfs* file system configured into the system. The *procfs* file system must also have been mounted with a command like:: - + nsh> mount -t procfs /proc Take a network down (ifdown) @@ -820,7 +820,7 @@ accesses (mh), or 32-bit access (mw). In each case, ``=`` Read the value, then write to the location. ```` Perform the mb, mh, or mw operation on a total of bytes, increment the - appropriately after each access. + appropriately after each access. ============================= ============================================== **Example**:: @@ -1225,7 +1225,7 @@ names in the *pseudo* file system. TESTFILE.TXT nsh> -Remove a Directory (rmdir) +Remove a Directory (rmdir) ************************** **Command Syntax**:: @@ -1541,7 +1541,7 @@ output is the same as -s. ``-v`` Print the kernel version ``-m`` Print the machine hardware name ``-i`` Print the machine platform name -``-p`` Print "unknown" +``-p`` Print "unknown" ========== ======================================== Unset an Environment Variable (unset) diff --git a/Documentation/components/nsh/config.rst b/Documentation/components/nsh/config.rst index 2331ff11ed..6e48881e84 100644 --- a/Documentation/components/nsh/config.rst +++ b/Documentation/components/nsh/config.rst @@ -29,10 +29,10 @@ Command Depends on Configuration Can Be Disabl ``addroute`` ``CONFIG_NET`` && ``CONFIG_NET_ROUTE`` ``CONFIG_NSH_DISABLE_ADDROUTE`` ``arp`` ``CONFIG_NET`` && ``CONFIG_NET_ARP`` ``CONFIG_NSH_DISABLE_ARP`` ``base64dec`` ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_BASE64DEC`` - ``CONFIG_CODECS_BASE64`` + ``CONFIG_CODECS_BASE64`` ``base64enc`` ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_BASE64ENC`` ``CONFIG_CODECS_BASE64`` -``basename`` . ``CONFIG_NSH_DISABLE_BASENAME`` +``basename`` . ``CONFIG_NSH_DISABLE_BASENAME`` ``break`` ! ``CONFIG_NSH_DISABLESCRIPT`` && . ! ``CONFIG_NSH_DISABLE_LOOPS``   ``cat`` ``CONFIG_NSH_DISABLE_CAT`` . @@ -59,9 +59,9 @@ Command Depends on Configuration Can Be Disabl ``help`` [#3]_ ``CONFIG_NSH_DISABLE_HELP`` . ``hexdump`` ``CONFIG_NSH_DISABLE_HEXDUMP`` . ``ifconfig`` ``CONFIG_NET`` && ``CONFIG_FS_PROCFS`` && ``CONFIG_NSH_DISABLE_IFCONFIG`` - ! ``CONFIG_FS_PROCFS_EXCLUDE_NET`` + ! ``CONFIG_FS_PROCFS_EXCLUDE_NET`` ``ifdown`` ``CONFIG_NET`` && ``CONFIG_FS_PROCFS`` && ``CONFIG_NSH_DISABLE_IFUPDOWN`` - ! ``CONFIG_FS_PROCFS_EXCLUDE_NET`` + ! ``CONFIG_FS_PROCFS_EXCLUDE_NET`` ``ifup`` ``CONFIG_NET`` && ``CONFIG_FS_PROCFS`` && ! ``CONFIG_FS_PROCFS_EXCLUDE_NET`` ``CONFIG_NSH_DISABLE_IFUPDOWN`` ``insmod`` ``CONFIG_MODULE`` ``CONFIG_NSH_DISABLE_MODCMDS`` @@ -70,37 +70,37 @@ Command Depends on Configuration Can Be Disabl ``CONFIG_SCHED_IRQMONITOR`` ``kill`` ``CONFIG_NSH_DISABLE_KILL`` . ``losetup`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_LOSETUP`` - ``CONFIG_DEV_LOOP`` + ``CONFIG_DEV_LOOP`` ``ln`` ``CONFIG_PSEUDOFS_SOFTLINKS`` ``CONFIG_NSH_DISABLE_LN`` ``ls`` ``CONFIG_NSH_DISABLE_LS`` . ``lsmod`` ``CONFIG_MODULE`` && ``CONFIG_FS_PROCFS`` ``CONFIG_NSH_DISABLE_MODCMDS`` && |br| - ! ``CONFIG_FS_PROCFS_EXCLUDE_MODULE`` + ! ``CONFIG_FS_PROCFS_EXCLUDE_MODULE`` ``md5`` ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_MD5`` - ``CONFIG_CODECS_HASH_MD5`` + ``CONFIG_CODECS_HASH_MD5`` ``mb,mh,mw`` . ``CONFIG_NSH_DISABLE_MB``, |br| ``CONFIG_NSH_DISABLE_MH``, |br| ``CONFIG_NSH_DISABLE_MW`` ``mkdir`` (! ``CONFIG_DISABLE_MOUNTPOINT`` \|\| ``CONFIG_NSH_DISABLE_MKDIR`` - ! ``CONFIG_DISABLE_PSEUDOFS_OPERATIONS``) + ! ``CONFIG_DISABLE_PSEUDOFS_OPERATIONS``) ``mkfatfs`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_MKFATFS`` ``CONFIG_FSUTILS_MKFATFS`` ``mkfifo`` ``CONFIG_PIPES`` && ``CONFIG_NSH_DISABLE_MKFIFO`` - ``CONFIG_DEV_FIFO_SIZE`` > 0 + ``CONFIG_DEV_FIFO_SIZE`` > 0 ``mkrd`` ! ``CONFIG_DISABLE_MOUNTPOINT`` ``CONFIG_NSH_DISABLE_MKRD`` ``mount`` ! ``CONFIG_DISABLE_MOUNTPOINT`` ``CONFIG_NSH_DISABLE_MOUNT`` ``mv`` ! ``CONFIG_DISABLE_MOUNTPOINT`` \|\| ``CONFIG_NSH_DISABLE_MV`` - ! ``CONFIG_DISABLE_PSEUDOFS_OPERATIONS`` + ! ``CONFIG_DISABLE_PSEUDOFS_OPERATIONS`` ``nfsmount`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_NFSMOUNT`` - ``CONFIG_NET`` && ``CONFIG_NFS`` + ``CONFIG_NET`` && ``CONFIG_NFS`` ``nslookup`` ``CONFIG_LIBC_NETDB`` && ``CONFIG_NSH_DISABLE_NSLOOKUP`` - ``CONFIG_NETDB_DNSCLIENT`` + ``CONFIG_NETDB_DNSCLIENT`` ``passwd`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_PASSWD`` - ``CONFIG_NSH_LOGIN_PASSWD`` + ``CONFIG_NSH_LOGIN_PASSWD`` ``pmconfig`` ``CONFIG_PM`` ``CONFIG_NSH_DISABLE_PMCONFIG`` ``poweroff`` ``CONFIG_BOARDCTL_POWEROFF`` ``CONFIG_NSH_DISABLE_POWEROFF`` ``ps`` ``CONFIG_FS_PROCFS`` && ``CONFIG_NSH_DISABLE_PS`` - ! ``CONFIG_FS_PROCFS_EXCLUDE_PROC`` + ! ``CONFIG_FS_PROCFS_EXCLUDE_PROC`` ``put`` ``CONFIG_NET`` && ``CONFIG_NET_UDP`` && ``CONFIG_NSH_DISABLE_PUT`` ``MTU >= 558`` [#1]_, [#2]_ ``pwd`` ! ``CONFIG_DISABLE_ENVIRON`` ``CONFIG_NSH_DISABLE_PWD`` @@ -120,22 +120,22 @@ Command Depends on Configuration Can Be Disabl ``CONFIG_NET_IPv6``) ``rptun`` ``CONFIG_RPTUN`` ``CONFIG_NSH_DISABLE_RPTUN`` ``set`` ``CONFIG_NSH_VARS`` \|\| ``CONFIG_NSH_DISABLE_SET`` - ! ``CONFIG_DISABLE_ENVIRON`` + ! ``CONFIG_DISABLE_ENVIRON`` ``shutdown`` ``CONFIG_BOARDCTL_POWEROFF`` \|\| ``CONFIG_NSH_DISABLE_SHUTDOWN`` ``CONFIG_BOARD_RESET`` ``sleep`` . ``CONFIG_NSH_DISABLE_SLEEP`` ``source`` ``CONFIG_FILE_STREAM`` && ``CONFIG_NSH_DISABLE_SOURCE`` - ! ``CONFIG_NSH_DISABLESCRIPT`` -``telnetd`` ``CONFIG_NSH_TELNET`` ``CONFIG_NSH_DISABLE_TELNETD`` + ! ``CONFIG_NSH_DISABLESCRIPT`` +``telnetd`` ``CONFIG_NSH_TELNET`` ``CONFIG_NSH_DISABLE_TELNETD`` ``test`` ! ``CONFIG_NSH_DISABLESCRIPT`` ``CONFIG_NSH_DISABLE_TEST`` ``time`` . ``CONFIG_NSH_DISABLE_TIME`` ``truncate`` ! ``CONFIG_DISABLE_MOUNTPOINT`` ``CONFIG_NSH_DISABLE_TRUNCATE`` ``umount`` ! ``CONFIG_DISABLE_MOUNTPOINT`` ``CONFIG_NSH_DISABLE_UMOUNT`` ``uname`` . ``CONFIG_NSH_DISABLE_UNAME`` ``unset`` ``CONFIG_NSH_VARS`` \|\| ``CONFIG_NSH_DISABLE_UNSET`` - ! ``CONFIG_DISABLE_ENVIRON`` + ! ``CONFIG_DISABLE_ENVIRON`` ``urldecode`` ! ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_URLDECODE`` - ``CONFIG_CODECS_URLCODE`` + ``CONFIG_CODECS_URLCODE`` ``urlencode`` ! ``CONFIG_NETUTILS_CODECS`` && ``CONFIG_NSH_DISABLE_URLENCODE`` ``CONFIG_CODECS_URLCODE`` ``useradd`` ! ``CONFIG_DISABLE_MOUNTPOINT`` && ``CONFIG_NSH_DISABLE_USERADD`` @@ -172,226 +172,226 @@ The behavior of NSH can be modified with the following settings in the ``boards////defconfig`` file: =================================== ================================== -Configuration Description +Configuration Description =================================== ================================== - ``CONFIG_NSH_READLINE`` Selects the minimal implementation of ``readline()``. - This minimal implementation provides on backspace for command - line editing. It expects some minimal VT100 command support from the terminal. - - ``CONFIG_NSH_CLE`` Selects the more extensive, EMACS-like command line editor. - Select this option only if (1) you don't mind a modest increase - in the FLASH footprint, and (2) you work with a terminal that - supports extensive VT100 editing commands. Selecting this option - will add probably 1.5-2KB to the FLASH footprint. - - ``CONFIG_NSH_BUILTIN_APPS`` Support external registered, "builtin" applications that can - be executed from the NSH command line (see apps/README.txt for - more information). This required ``CONFIG_BUILTIN`` to enable - NuttX support for "builtin" applications. - - ``CONFIG_NSH_FILEIOSIZE`` Size of a static I/O buffer used for file access (ignored if there - is no file system). Default is 1024. - - ``CONFIG_NSH_STRERROR`` ``strerror(errno)`` makes more readable output but - ``strerror()`` is very large and will not be used unless this - setting is *y*. This setting depends upon the ``strerror()`` - having been enabled with ``CONFIG_LIBC_STRERROR``. - - ``CONFIG_NSH_LINELEN`` The maximum length of one command line and of one output line. - Default: 80 - - ``CONFIG_NSH_DISABLE_SEMICOLON`` By default, you can enter multiple NSH commands on a line - with each command separated by a semicolon. You can disable this - feature to save a little memory on FLASH challenged platforms. + ``CONFIG_NSH_READLINE`` Selects the minimal implementation of ``readline()``. + This minimal implementation provides on backspace for command + line editing. It expects some minimal VT100 command support from the terminal. + + ``CONFIG_NSH_CLE`` Selects the more extensive, EMACS-like command line editor. + Select this option only if (1) you don't mind a modest increase + in the FLASH footprint, and (2) you work with a terminal that + supports extensive VT100 editing commands. Selecting this option + will add probably 1.5-2KB to the FLASH footprint. + + ``CONFIG_NSH_BUILTIN_APPS`` Support external registered, "builtin" applications that can + be executed from the NSH command line (see apps/README.txt for + more information). This required ``CONFIG_BUILTIN`` to enable + NuttX support for "builtin" applications. + + ``CONFIG_NSH_FILEIOSIZE`` Size of a static I/O buffer used for file access (ignored if there + is no file system). Default is 1024. + + ``CONFIG_NSH_STRERROR`` ``strerror(errno)`` makes more readable output but + ``strerror()`` is very large and will not be used unless this + setting is *y*. This setting depends upon the ``strerror()`` + having been enabled with ``CONFIG_LIBC_STRERROR``. + + ``CONFIG_NSH_LINELEN`` The maximum length of one command line and of one output line. + Default: 80 + + ``CONFIG_NSH_DISABLE_SEMICOLON`` By default, you can enter multiple NSH commands on a line + with each command separated by a semicolon. You can disable this + feature to save a little memory on FLASH challenged platforms. Default: n - - ``CONFIG_NSH_CMDPARMS`` If selected, then the output from commands, from file applications, - and from NSH built-in commands can be used as arguments to other - commands. The entity to be executed is identified by + + ``CONFIG_NSH_CMDPARMS`` If selected, then the output from commands, from file applications, + and from NSH built-in commands can be used as arguments to other + commands. The entity to be executed is identified by enclosing the command line in back quotes. For example:: - - set FOO `myprogram $BAR` - - will execute the program named ``myprogram`` passing it the - value of the environment variable ``BAR``. The value of the - environment variable ``FOO`` is then set output of ``myprogram`` - on ``stdout``. Because this feature commits significant - resources, it is disabled by default. The ``CONFIG_NSH_CMDPARMS`` interim - output will be retained in a temporary file. Full path to a - directory where temporary files can be created is taken from - ``CONFIG_LIBC_TMPDIR`` and it defaults to ``/tmp`` if - ``CONFIG_LIBC_TMPDIR`` is not set. - - ``CONFIG_NSH_MAXARGUMENTS`` The maximum number of NSH command arguments. Default: 6 - - ``CONFIG_NSH_ARGCAT`` Support concatenation of strings with environment variables or + + set FOO `myprogram $BAR` + + will execute the program named ``myprogram`` passing it the + value of the environment variable ``BAR``. The value of the + environment variable ``FOO`` is then set output of ``myprogram`` + on ``stdout``. Because this feature commits significant + resources, it is disabled by default. The ``CONFIG_NSH_CMDPARMS`` interim + output will be retained in a temporary file. Full path to a + directory where temporary files can be created is taken from + ``CONFIG_LIBC_TMPDIR`` and it defaults to ``/tmp`` if + ``CONFIG_LIBC_TMPDIR`` is not set. + + ``CONFIG_NSH_MAXARGUMENTS`` The maximum number of NSH command arguments. Default: 6 + + ``CONFIG_NSH_ARGCAT`` Support concatenation of strings with environment variables or command output. For example:: - + set FOO XYZ set BAR 123 set FOOBAR ABC_${FOO}_${BAR} - - would set the environment variable ``FOO`` to ``XYZ``, - ``BAR`` to ``123`` and ``FOOBAR`` to ``ABC_XYZ_123``. If - ``CONFIG_NSH_ARGCAT`` is not selected, then a slightly small - FLASH footprint results but then also only simple environment - variables like ``$FOO`` can be used on the command line. - - ``CONFIG_NSH_VARS`` By default, there are no internal NSH variables. NSH will use OS - environment variables for all variable storage. If this option, - NSH will also support local NSH variables. These variables are, - for the most part, transparent and work just like the OS - environment variables. The difference is that when you - create new tasks, all of environment variables are - inherited by the created tasks. NSH local variables are not. - If this option is enabled (and ``CONFIG_DISABLE_ENVIRON`` is not), - then a new command called 'export' is enabled. The export - command works very must like the set command except that is - operates on environment variables. When CONFIG_NSH_VARS + + would set the environment variable ``FOO`` to ``XYZ``, + ``BAR`` to ``123`` and ``FOOBAR`` to ``ABC_XYZ_123``. If + ``CONFIG_NSH_ARGCAT`` is not selected, then a slightly small + FLASH footprint results but then also only simple environment + variables like ``$FOO`` can be used on the command line. + + ``CONFIG_NSH_VARS`` By default, there are no internal NSH variables. NSH will use OS + environment variables for all variable storage. If this option, + NSH will also support local NSH variables. These variables are, + for the most part, transparent and work just like the OS + environment variables. The difference is that when you + create new tasks, all of environment variables are + inherited by the created tasks. NSH local variables are not. + If this option is enabled (and ``CONFIG_DISABLE_ENVIRON`` is not), + then a new command called 'export' is enabled. The export + command works very must like the set command except that is + operates on environment variables. When CONFIG_NSH_VARS is enabled, there are changes in the behavior of certain commands. See following :ref:`table `. - - ``CONFIG_NSH_QUOTE`` Enables back-slash quoting of certain characters within the - command. This option is useful for the case where an NSH script - is used to dynamically generate a new NSH script. In that case, - commands must be treated as simple text strings without - interpretation of any special characters. Special characters - such as ``$``, :literal:`\``, ``"``, and others must be - retained intact as part of the test string. This option is - currently only available is ``CONFIG_NSH_ARGCAT`` is also - selected. - - ``CONFIG_NSH_NESTDEPTH`` The maximum number of nested ``if-then[-else]-fi`` <#conditional>`__ - sequences that are permissible. Default: 3 - - ``CONFIG_NSH_DISABLESCRIPT`` This can be set to *y* to suppress support for scripting. - This setting disables the ```sh`` <#cmdsh>`__, - ```test`` <#cmdtest>`__, and ```[`` <#cmtest>`__ commands and - the ```if-then[-else]-fi`` <#conditional>`__ - construct. This would only be set on systems where a minimal - footprint is a necessity and scripting is not. - - ``CONFIG_NSH_DISABLE_ITEF`` If scripting is enabled, then then this option can be selected - to suppress support for ``if-then-else-fi`` sequences in - scripts. This would only be set on systems where some minimal + + ``CONFIG_NSH_QUOTE`` Enables back-slash quoting of certain characters within the + command. This option is useful for the case where an NSH script + is used to dynamically generate a new NSH script. In that case, + commands must be treated as simple text strings without + interpretation of any special characters. Special characters + such as ``$``, :literal:`\``, ``"``, and others must be + retained intact as part of the test string. This option is + currently only available is ``CONFIG_NSH_ARGCAT`` is also + selected. + + ``CONFIG_NSH_NESTDEPTH`` The maximum number of nested ``if-then[-else]-fi`` <#conditional>`__ + sequences that are permissible. Default: 3 + + ``CONFIG_NSH_DISABLESCRIPT`` This can be set to *y* to suppress support for scripting. + This setting disables the ```sh`` <#cmdsh>`__, + ```test`` <#cmdtest>`__, and ```[`` <#cmtest>`__ commands and + the ```if-then[-else]-fi`` <#conditional>`__ + construct. This would only be set on systems where a minimal + footprint is a necessity and scripting is not. + + ``CONFIG_NSH_DISABLE_ITEF`` If scripting is enabled, then then this option can be selected + to suppress support for ``if-then-else-fi`` sequences in + scripts. This would only be set on systems where some minimal scripting is required but ``if-then-else-fi`` is not. - - ``CONFIG_NSH_DISABLE_LOOPS`` If scripting is enabled, then then this option can be selected - suppress support ``for while-do-done`` and - ``until-do-done`` sequences in scripts. This would only be set - on systems where some minimal scripting is required but looping - is not. - - ``CONFIG_NSH_DISABLEBG`` This can be set to *y* to suppress support for background - commands. This setting disables the ```nice`` <#cmdoverview>`__ - command prefix and the ```&`` <#cmdoverview>`__ command - suffix. This would only be set on systems where a minimal footprint - is a necessity and background command execution is not. - - ``CONFIG_NSH_MMCSDMINOR`` If the architecture supports an MMC/SD slot and if the NSH - architecture specific logic is present, this option will provide - the MMC/SD minor number, i.e., the MMC/SD block driver will be - registered as ``/dev/mmcsd``\ *N* where *N* is the minor number. - Default is zero. - - ``CONFIG_NSH_ROMFSETC`` Mount a ROMFS file system at ``/etc`` and provide a startup - script at ``/etc/init.d/rcS``. - The default startup script will mount a FAT FS RAMDISK at - ``/tmp`` but the logic is `easily extensible <#startupscript>`__. - - ``CONFIG_NSH_CONSOLE`` If ``CONFIG_NSH_CONSOLE`` is set to *y*, then a serial console - front-end is selected. - - Normally, the serial console device is a UART and RS-232 - interface. However, if ``CONFIG_USBDEV`` is defined, - then a USB serial device may, instead, be used if the one of - the following are defined: - - - ``CONFIG_PL2303`` and ``CONFIG_PL2303_CONSOLE``. - Sets up the Prolifics PL2303 emulation as a console device - at ``/dev/console``. - - ``CONFIG_CDCACM`` and ``CONFIG_CDCACM_CONSOLE``. - Sets up the CDC/ACM serial device as a console device at - ``/dev/console``. - - ``CONFIG_NSH_USBCONSOLE``. If defined, then an arbitrary USB - device may be used to as the NSH console. In this case, - ``CONFIG_NSH_USBCONDEV`` must be defined to indicate which - USB device to use as the console. The advantage of - using a device other that ``/dev/console`` is that - normal debug output can then use ``/dev/console`` while NSH - uses ``CONFIG_NSH_USBCONDEV``. - - ``CONFIG_NSH_USBCONDEV``. If ``CONFIG_NSH_USBCONSOLE`` is - set to 'y', then ``CONFIG_NSH_USBCONDEV`` must also be set to select the USB - device used to support the NSH console. This should be set to - the quoted name of a readable/write-able USB driver - such as: ``CONFIG_NSH_USBCONDEV="/dev/ttyACM0"``. - - If there are more than one USB slots, then a USB device minor - number may also need to be provided: - - - ``CONFIG_NSH_UBSDEV_MINOR``: The minor device number of the USB device. Default: 0 - - If USB tracing is enabled (``CONFIG_USBDEV_TRACE``), then - NSH will initialize USB tracing as requested by the following. - Default: Only USB errors are traced. - - - ``CONFIG_NSH_USBDEV_TRACEINIT``: Show initialization events - - ``CONFIG_NSH_USBDEV_TRACECLASS``: Show class driver events - - ``CONFIG_NSH_USBDEV_TRACETRANSFERS``: Show data transfer events - - ``CONFIG_NSH_USBDEV_TRACECONTROLLER``: Show controller events - - ``CONFIG_NSH_USBDEV_TRACEINTERRUPTS``: Show interrupt-related events. - + + ``CONFIG_NSH_DISABLE_LOOPS`` If scripting is enabled, then then this option can be selected + suppress support ``for while-do-done`` and + ``until-do-done`` sequences in scripts. This would only be set + on systems where some minimal scripting is required but looping + is not. + + ``CONFIG_NSH_DISABLEBG`` This can be set to *y* to suppress support for background + commands. This setting disables the ```nice`` <#cmdoverview>`__ + command prefix and the ```&`` <#cmdoverview>`__ command + suffix. This would only be set on systems where a minimal footprint + is a necessity and background command execution is not. + + ``CONFIG_NSH_MMCSDMINOR`` If the architecture supports an MMC/SD slot and if the NSH + architecture specific logic is present, this option will provide + the MMC/SD minor number, i.e., the MMC/SD block driver will be + registered as ``/dev/mmcsd``\ *N* where *N* is the minor number. + Default is zero. + + ``CONFIG_NSH_ROMFSETC`` Mount a ROMFS file system at ``/etc`` and provide a startup + script at ``/etc/init.d/rcS``. + The default startup script will mount a FAT FS RAMDISK at + ``/tmp`` but the logic is `easily extensible <#startupscript>`__. + + ``CONFIG_NSH_CONSOLE`` If ``CONFIG_NSH_CONSOLE`` is set to *y*, then a serial console + front-end is selected. + + Normally, the serial console device is a UART and RS-232 + interface. However, if ``CONFIG_USBDEV`` is defined, + then a USB serial device may, instead, be used if the one of + the following are defined: + + - ``CONFIG_PL2303`` and ``CONFIG_PL2303_CONSOLE``. + Sets up the Prolifics PL2303 emulation as a console device + at ``/dev/console``. + - ``CONFIG_CDCACM`` and ``CONFIG_CDCACM_CONSOLE``. + Sets up the CDC/ACM serial device as a console device at + ``/dev/console``. + - ``CONFIG_NSH_USBCONSOLE``. If defined, then an arbitrary USB + device may be used to as the NSH console. In this case, + ``CONFIG_NSH_USBCONDEV`` must be defined to indicate which + USB device to use as the console. The advantage of + using a device other that ``/dev/console`` is that + normal debug output can then use ``/dev/console`` while NSH + uses ``CONFIG_NSH_USBCONDEV``. + + ``CONFIG_NSH_USBCONDEV``. If ``CONFIG_NSH_USBCONSOLE`` is + set to 'y', then ``CONFIG_NSH_USBCONDEV`` must also be set to select the USB + device used to support the NSH console. This should be set to + the quoted name of a readable/write-able USB driver + such as: ``CONFIG_NSH_USBCONDEV="/dev/ttyACM0"``. + + If there are more than one USB slots, then a USB device minor + number may also need to be provided: + + - ``CONFIG_NSH_UBSDEV_MINOR``: The minor device number of the USB device. Default: 0 + + If USB tracing is enabled (``CONFIG_USBDEV_TRACE``), then + NSH will initialize USB tracing as requested by the following. + Default: Only USB errors are traced. + + - ``CONFIG_NSH_USBDEV_TRACEINIT``: Show initialization events + - ``CONFIG_NSH_USBDEV_TRACECLASS``: Show class driver events + - ``CONFIG_NSH_USBDEV_TRACETRANSFERS``: Show data transfer events + - ``CONFIG_NSH_USBDEV_TRACECONTROLLER``: Show controller events + - ``CONFIG_NSH_USBDEV_TRACEINTERRUPTS``: Show interrupt-related events. + ``CONFIG_NSH_ALTCONDEV`` and If ``CONFIG_NSH_CONSOLE`` is set ``CONFIG_NSH_CONDEV`` - to *y*, then ``CONFIG_NSH_ALTCONDEV`` may also - be selected to enable use of an alternate character device to - support the NSH console. If ``CONFIG_NSH_ALTCONDEV`` is - selected, then ``CONFIG_NSH_CONDEV`` holds the - quoted name of a readable/write-able character - driver such as: ``CONFIG_NSH_CONDEV="/dev/ttyS1"``. - This is useful, for example, to separate the NSH command line - from the system console when the system console is used to provide - debug output. Default: ``stdin`` and ``stdout`` (probably - "``/dev/console``") - - - **NOTE 1:** When any other device other than - ``/dev/console`` is used for a user interface, (1) linefeeds - (``\n``) will not be expanded to carriage return / linefeeds - (``\r\n``). You will need to configure your terminal - program to account for this. - And (2) input is not automatically echoed so you - will have to turn local echo on. - - **NOTE 2:** This option forces the console of all sessions to - use NSH_CONDEV. Hence, this option only makes sense for a - system that supports only a single session. This option - is, in particular, incompatible with Telnet - sessions because each Telnet session must use a different - console device. - - ``CONFIG_NSH_TELNET`` If ``CONFIG_NSH_TELNET`` is set to *y*, then a TELNET server - front-end is selected. When this option is provided, you may log - into NuttX remotely using telnet in order to access NSH. - - ``CONFIG_NSH_ARCHINIT`` Set ``CONFIG_NSH_ARCHINIT`` if your board provides architecture - specific initialization via the board-specific function - ``board_app_initialize()``. This function will be called early in - NSH initialization to allow board logic to do such things as - configure MMC/SD slots. + to *y*, then ``CONFIG_NSH_ALTCONDEV`` may also + be selected to enable use of an alternate character device to + support the NSH console. If ``CONFIG_NSH_ALTCONDEV`` is + selected, then ``CONFIG_NSH_CONDEV`` holds the + quoted name of a readable/write-able character + driver such as: ``CONFIG_NSH_CONDEV="/dev/ttyS1"``. + This is useful, for example, to separate the NSH command line + from the system console when the system console is used to provide + debug output. Default: ``stdin`` and ``stdout`` (probably + "``/dev/console``") + + - **NOTE 1:** When any other device other than + ``/dev/console`` is used for a user interface, (1) linefeeds + (``\n``) will not be expanded to carriage return / linefeeds + (``\r\n``). You will need to configure your terminal + program to account for this. + And (2) input is not automatically echoed so you + will have to turn local echo on. + - **NOTE 2:** This option forces the console of all sessions to + use NSH_CONDEV. Hence, this option only makes sense for a + system that supports only a single session. This option + is, in particular, incompatible with Telnet + sessions because each Telnet session must use a different + console device. + + ``CONFIG_NSH_TELNET`` If ``CONFIG_NSH_TELNET`` is set to *y*, then a TELNET server + front-end is selected. When this option is provided, you may log + into NuttX remotely using telnet in order to access NSH. + + ``CONFIG_NSH_ARCHINIT`` Set ``CONFIG_NSH_ARCHINIT`` if your board provides architecture + specific initialization via the board-specific function + ``board_app_initialize()``. This function will be called early in + NSH initialization to allow board logic to do such things as + configure MMC/SD slots. =================================== ================================== - + .. _nsh_vars_table: ================== =================================== ============================================= -CMD w/o ``CONFIG_NSH_VARS`` w/``CONFIG_NSH_VARS`` +CMD w/o ``CONFIG_NSH_VARS`` w/``CONFIG_NSH_VARS`` ================== =================================== ============================================= -``set `` Set environment variable to Set NSH variable to (Unless the NSH variable has been *promoted* via +``set `` Set environment variable to Set NSH variable to (Unless the NSH variable has been *promoted* via ``export``, in which case the env ironment variable of the same name is set to ). -``set`` Causes an error. Lists all NSH variables. -``unset `` Unsets environment variable Unsets both environment variable *and* NSH variable with and name -``export `` Causes an error, Unsets NSH variable . Sets environment variable to . -``export `` Causes an error. Sets environment variable to the value of NSH variable (or "" if the - NSH variable has not been set). Unsets NSH local variable . -``env`` Lists all environment variables Lists all environment variables (*only*) +``set`` Causes an error. Lists all NSH variables. +``unset `` Unsets environment variable Unsets both environment variable *and* NSH variable with and name +``export `` Causes an error, Unsets NSH variable . Sets environment variable to . +``export `` Causes an error. Sets environment variable to the value of NSH variable (or "" if the + NSH variable has not been set). Unsets NSH local variable . +``env`` Lists all environment variables Lists all environment variables (*only*) ================== =================================== ============================================= diff --git a/Documentation/components/nsh/customizing.rst b/Documentation/components/nsh/customizing.rst index fcd293b71b..38b28a0856 100644 --- a/Documentation/components/nsh/customizing.rst +++ b/Documentation/components/nsh/customizing.rst @@ -58,7 +58,7 @@ The NSH initialization function, ``nsh_initialize()``, be found in The ROMFS image is, itself, just built into the firmware. By default, this ``rcS`` start-up script contains the following logic:: - + # Create a RAMDISK and mount it at XXXRDMOUNTPOINTXXX mkrd -m XXXMKRDMINORXXX -s XXMKRDSECTORSIZEXXX XXMKRDBLOCKSXXX @@ -80,12 +80,12 @@ The NSH initialization function, ``nsh_initialize()``, be found in Default: ``/etc`` By default, the substituted values would yield an ``rcS`` file like:: - + # Create a RAMDISK and mount it at /tmp mkrd -m 1 -s 512 1024 mkfatfs /dev/ram1 - mount -t vfat /dev/ram1 /tmp + mount -t vfat /dev/ram1 /tmp This script will, then: diff --git a/Documentation/components/nsh/index.rst b/Documentation/components/nsh/index.rst index 7f7a4efcab..a6650d37f2 100644 --- a/Documentation/components/nsh/index.rst +++ b/Documentation/components/nsh/index.rst @@ -5,11 +5,11 @@ NuttShell (NSH) The NuttShell is a very complete shell system to be used in NuttX, similar to bash and other similar options. It supports a rich set of included commands, scripting and the ability to run your own applications as "builtin" (part of the same NuttX binary). NSH is implemented as an application where most of the functionality is part of the library called `nshlib`. As such, NSH is completely optional and can be disabled so that NuttX directly starts a given task instead of the main ``nsh`` application. - + .. toctree:: :maxdepth: 2 :caption: Contents - + nsh.rst commands.rst config.rst diff --git a/Documentation/components/nsh/installation.rst b/Documentation/components/nsh/installation.rst index 60ed8e6230..f8e0c79f90 100644 --- a/Documentation/components/nsh/installation.rst +++ b/Documentation/components/nsh/installation.rst @@ -61,39 +61,39 @@ behave as follows at NSH start-up time: - NSH will create a read-only RAM disk (a ROM disk), containing a tiny ROMFS file system containing the following:: - + `--init.d/ `-- rcS - + Where ``rcS`` is the NSH start-up script. - NSH will then mount the ROMFS file system at ``/etc``, resulting in:: - + |--dev/ | `-- ram0 `--etc/ `--init.d/ - `-- rcS + `-- rcS - By default, the contents of ``rcS`` script are:: - + # Create a RAMDISK and mount it at /tmp mkrd -m 1 -s 512 1024 mkfatfs /dev/ram1 mount -t vfat /dev/ram1 /tmp - + - NSH will execute the script at ``/etc/init.d/rcS`` at start-up (before the first NSH prompt). After execution of the script, the root FS will look like:: - + |--dev/ | |-- ram0 | `-- ram1 |--etc/ | `--init.d/ | `-- rcS - `--tmp/ + `--tmp/ **Example Configurations**. Here are some configurations that have ``CONFIG_NSH_ROMFSETC=y`` in the NuttX configuration file. They might diff --git a/Documentation/components/nsh/login.rst b/Documentation/components/nsh/login.rst index a33d8ecfd0..6aabfc3cbb 100644 --- a/Documentation/components/nsh/login.rst +++ b/Documentation/components/nsh/login.rst @@ -46,13 +46,13 @@ credentials at login time: #. The simplest implementation simply uses fixed login credentials and is selected with:: - - CONFIG_NSH_LOGIN_FIXED=y + + CONFIG_NSH_LOGIN_FIXED=y The fixed login credentials are selected via:: - + CONFIG_NSH_LOGIN_USERNAME=admin - CONFIG_NSH_LOGIN_PASSWORD="Administrator" + CONFIG_NSH_LOGIN_PASSWORD="Administrator" This is not very flexible since there can be only one user and the password is fixed in the FLASH image. This option is also not very @@ -61,22 +61,22 @@ credentials at login time: #. NSH can also be configured to defer the entire user credential verification to platform-specific logic with this setting:: - - CONFIG_NSH_LOGIN_PLATFORM=y + + CONFIG_NSH_LOGIN_PLATFORM=y In this case, NSH will call a platform-specific function to perform the verification of user credentials. The platform-specific logic must provide a function with the following prototype: - + .. code-block:: c - + int platform_user_verify(FAR const char *username, FAR const char *password); which is prototyped an described in ``apps/include/nsh.h`` and which may be included like: - + .. code-block:: c - + #include An appropriate place to implement this function might be in the @@ -85,7 +85,7 @@ credentials at login time: #. A final option is to use a password file contained encrypted password information. This final option is selected with the following and described in more detail in the following paragraph:: - + CONFIG_NSH_LOGIN_PASSWD=y Password Files @@ -126,17 +126,17 @@ The password file logic requires a few additional settings: #. The size of dynamically allocated and freed buffer that is used for file access:: - + CONFIG_FSUTILS_PASSWD_IOBUFFER_SIZE=512 #. And the 128-bit encryption key. The password file currently uses the Tiny Encryption Algorithm (TEA), but could be extended to use something more powerful. - + CONFIG_FSUTILS_PASSWD_KEY1=0x12345678 CONFIG_FSUTILS_PASSWD_KEY2=0x9abcdef0 CONFIG_FSUTILS_PASSWD_KEY3=0x12345678 - CONFIG_FSUTILS_PASSWD_KEY4=0x9abcdef0 + CONFIG_FSUTILS_PASSWD_KEY4=0x9abcdef0 Password can only be decrypted with access to this key. Note that this key could potentially be fished out of your FLASH image, but without any @@ -178,27 +178,27 @@ ROMFS file system, passwords, and login prompts. First, I make these changes to that configuration. #. Disable logins: - + .. code-block:: diff - + - CONFIG_NSH_CONSOLE_LOGIN=y + # CONFIG_NSH_CONSOLE_LOGIN is not set - # CONFIG_NSH_TELNET_LOGIN is not set + # CONFIG_NSH_TELNET_LOGIN is not set #. Move the password file to a write-able file system: - + .. code-block:: diff - + - CONFIG_FSUTILS_PASSWD_PATH="/etc/passwd" + CONFIG_FSUTILS_PASSWD_PATH="/tmp/passwd" - + #. Make the password file modifiable .. code-block:: diff - + - CONFIG_FSUTILS_PASSWD_READONLY=y # CONFIG_FSUTILS_PASSWD_READONLY is not set - + Now rebuild the simulation. No login should be required to enter the shell and you should find the ```useradd`` <#cmduseradd>`__, ```userdel`` <#cmduserdel>`__, and ```passwd`` <#cmdpasswd>`__ commands @@ -228,21 +228,21 @@ Then create/re-create the ``nsh_romfsimg.h`` file as described below. #. The content on the ``nsh_romfsimg.h`` header file is generated from a template directory structure. Create the directory structure:: - + mkdir etc - mkdir etc/init.d + mkdir etc/init.d And copy your existing startup script into ``etc/init.c`` as ``rcS``. #. Save your new password file in the ``etc/`` directory as ``passwd``. #. Create the new ROMFS image:: - - genromfs -f romfs_img -d etc -V MyVolName + + genromfs -f romfs_img -d etc -V MyVolName #. Convert the ROMFS image to a C header file:: - - xxd -i romfs_img >nsh_romfsimg.h + + xxd -i romfs_img >nsh_romfsimg.h #. Edit ``nsh_romfsimg.h``: Mark both data definitions as ``const`` so that the data will be stored in FLASH. diff --git a/Documentation/components/nsh/nsh.rst b/Documentation/components/nsh/nsh.rst index 317103c88e..06d0eb5a06 100644 --- a/Documentation/components/nsh/nsh.rst +++ b/Documentation/components/nsh/nsh.rst @@ -93,19 +93,19 @@ commands forms: Simple command ```` Command with re-directed output `` > >> `` Background command `` &`` -Re-directed background command `` > & >> &`` +Re-directed background command `` > & >> &`` =============================== ====================================== Where: * ```` is any one of the simple commands listed later. - * ```` is the full or relative path to any writable object in the file system name space (file or character driver). Such objects will be referred to simply as files throughout this document. + * ```` is the full or relative path to any writable object in the file system name space (file or character driver). Such objects will be referred to simply as files throughout this document. ``nice`` **'d Background Commands**. NSH executes at the mid-priority (128). Backgrounded commands can be made to execute at higher or lower priorities using ``nice``:: - [nice [-d >]] [> |>> ] [&] + [nice [-d >]] [> |>> ] [&] Where ```` is any value between -20 and 19 where lower (more negative values) correspond to higher priorities. The @@ -123,9 +123,9 @@ significant resources, they are disabled by default. commands can be used as arguments to other commands. The entity to be executed is identified by enclosing the command line in back quotes. For example, - + .. code-block:: bash - + set FOO myprogram $BAR Will execute the program named ``myprogram`` passing it the @@ -135,9 +135,9 @@ significant resources, they are disabled by default. - ``CONFIG_NSH_ARGCAT``: Support concatenation of strings with environment variables or command output. For example: - + .. code-block:: bash - + set FOO XYZ set BAR 123 set FOOBAR ABC_${FOO}_${BAR} @@ -191,20 +191,20 @@ the ```sh`` <#cmdsh>`__ command). - ``while-do-done``: Execute ``[sequence of ]`` as long as ```` has an exit status of zero. The syntax is as follows: - + .. code-block:: bash - + while do [sequence of ] - done + done - ``until-do-done``: Execute ``[sequence of ]`` as long as ```` has a non-zero exit status. The syntax is as follows: .. code-block:: - + until do [sequence of ] @@ -228,7 +228,7 @@ Built-In Variables ====== ==================================================== ``$?`` The result of the last simple command execution. |br| On backgrounded commands, this variable holds only |br| - the result of spawning the background command. + the result of spawning the background command. ====== ==================================================== Current Working Directory @@ -274,23 +274,23 @@ NSH to behave as follows at NSH startup time: - NSH will create a read-only RAM disk (a ROM disk), containing a tiny ROMFS file system containing the following:: - + `--init.d/ `-- rcS Where rcS is the NSH start-up script. - + - NSH will then mount the ROMFS file system at ``/etc``, resulting in:: - + |--dev/ | `-- ram0 `--etc/ `--init.d/ - `-- rcS + `-- rcS - By default, the contents of rcS script are:: - + # Create a RAMDISK and mount it at XXXRDMOUNTPOINTXXX mkrd -m 1 -s 512 1024 @@ -300,14 +300,14 @@ NSH to behave as follows at NSH startup time: - NSH will execute the script at ``/etc/init.d/rcS`` at start-up (before the first NSH prompt). After execution of the script, the root FS will look like:: - + |--dev/ | |-- ram0 | `-- ram1 |--etc/ | `--init.d/ | `-- rcS - `--tmp/ + `--tmp/ **Modifying the ROMFS Image**. The contents of the ``/etc`` directory are retained in the file ``apps/nshlib/nsh_romfsimg.h`` diff --git a/Documentation/components/nxflat.rst b/Documentation/components/nxflat.rst index be6c59dc41..69f5c051f5 100644 --- a/Documentation/components/nxflat.rst +++ b/Documentation/components/nxflat.rst @@ -77,7 +77,7 @@ Limitations of file system but will require copying of all NXFLAT executables to RAM. - **GCC/ARM/Cortex-M3/4 Only**: - At present, the NXFLAT toolchain is only available for ARM and Cortex-M3/4 (thumb2) targets. + At present, the NXFLAT toolchain is only available for ARM and Cortex-M3/4 (thumb2) targets. - **Read-Only Data in RAM**: With older GCC compilers (at least up to 4.3.3), read-only data must @@ -96,10 +96,10 @@ Limitations - **Globally Scoped Function Function Pointers**: If a function pointer is taken to a statically defined function, then (at least for ARM) GCC will generate a relocation that NXFLAT - cannot handle. The workaround is make all such functions global in + cannot handle. The workaround is make all such functions global in scope. A fix would involve a change to the GCC compiler as described - in Appendix B. - + in Appendix B. + - **Special Handling of Callbacks**: Callbacks through function pointers must be avoided or, when then cannot be avoided, handled very specially. The reason @@ -109,7 +109,7 @@ Limitations will be unable to correctly access data memory. Special logic is in place to handle some NuttX callbacks: Signal callbacks and watchdog timer callbacks. But other callbacks (like those - used with qsort() must be avoided in an NXFLAT module. + used with qsort() must be avoided in an NXFLAT module. Supported Processors -------------------- @@ -217,7 +217,7 @@ files. In particular, the CSV files: interface, and #. ``nuttx/libc/libc.csv`` that describes the NuttX C library interface. #. ``nuttx/libc/math.cvs`` that descirbes any math library. - + :: USAGE: ./mksymtab @@ -254,21 +254,21 @@ example). * Target 2: .. code-block:: makefile - + hello-thunk.S: hello.r1 mknxflat -o $@ $^ - + * Target 3: .. code-block:: makefile - - hello.r2: hello-thunk.S + + hello.r2: hello-thunk.S abc-nuttx-elf-ld -r -d -warn-common -T binfmt/libnxflat/gnu-nxflat-gotoff.ld -no-check-sections -o $@ hello.o hello-thunk.o * Target 4: .. code-block:: makefile - + hello: hello.r2 ldnxflat -e main -s 2048 -o $@ $^ diff --git a/Documentation/components/nxgraphics/appendix.rst b/Documentation/components/nxgraphics/appendix.rst index 7cfeb09a4c..85a5cdada0 100644 --- a/Documentation/components/nxgraphics/appendix.rst +++ b/Documentation/components/nxgraphics/appendix.rst @@ -14,22 +14,22 @@ the RTOS. User callable functions must be part of a library that can be linked against user applications. This user callable interfaces are provided in sub-directories under ``nuttx/libnx``. -``libnx/nx`` +``libnx/nx`` Common callable interfaces that are, logically, part of both nxmu and nxsu. -``graphics/nxglib`` and ``libnx/nxglib`` +``graphics/nxglib`` and ``libnx/nxglib`` The NuttX tiny graphics library. The directory contains generic utilities support operations on primitive graphics objects and logic to rasterize directly into a framebuffer or through an LCD driver interface. It has no concept of windows (other than the one, framebuffer or LCD window). -``graphics/nxbe`` +``graphics/nxbe`` This is the *back-end* of a tiny windowing system. It can be used with either of two front-ends to complete a windowing system (see ``nxmu`` and ``nxsu`` below). It contains most of the important window management logic: clipping, window controls, window drawing, etc. -``graphics/nxmu`` and ``libnx/nxmu`` +``graphics/nxmu`` and ``libnx/nxmu`` This is the NX multi user *front end*. When combined with the generic *back-end* (``nxbe``), it implements a multi-threaded, multi-user windowing system. The files in this directory present the window APIs @@ -37,18 +37,18 @@ provided in sub-directories under ``nuttx/libnx``. includes a graphics server that executes on its own thread; multiple graphics clients then communicate with the server via a POSIX message queue to serialize window operations from many threads. -``libnx/nxfonts`` +``libnx/nxfonts`` This is where the NXFONTS implementation resides. This is a relatively low-level set of charset set/glyph management APIs. See ``include/nuttx/nx/nxfonts.h``. -``libnx/nxtk`` +``libnx/nxtk`` This is where the NXTOOLKIT implementation resides. This toolkit is built on top of NX and works with the multi-user NX front-end. See ``include/nuttx/nx/nxtk.h``. -``apps/graphics/NxWidgets`` +``apps/graphics/NxWidgets`` The `NxWidgets `__ code is provided as a separate package provided in the ``apps/`` repository. -``graphics/nxterm`` +``graphics/nxterm`` The NxTerm driver is built on top of NX and works with the multi-user NX front-end. See ``include/nuttx/nx/nxterm.h``. @@ -58,9 +58,9 @@ NX Configuration Options General Configuration Settings ------------------------------ -``CONFIG_NX`` +``CONFIG_NX`` Enables overall support for graphics library and NX -``CONFIG_NX_RAMBACKED`` +``CONFIG_NX_RAMBACKED`` Enables RAM backed window support. If this option is selected, then windows may be optionally created with a RAM framebuffer backing up the window content. Rending into the window will result in rending @@ -87,21 +87,21 @@ General Configuration Settings NXGL Configuration Settings --------------------------- -``CONFIG_NX_NPLANES``: +``CONFIG_NX_NPLANES``: Some YUV color formats requires support for multiple planes, one for each color component. Unless you have such special hardware, this value should be undefined or set to 1. -``CONFIG_NX_DISABLE_1BPP``, ``CONFIG_NX_DISABLE_2BPP``, ``CONFIG_NX_DISABLE_4BPP``, ``CONFIG_NX_DISABLE_8BPP`` ``CONFIG_NX_DISABLE_16BPP``, ``CONFIG_NX_DISABLE_24BPP``, and ``CONFIG_NX_DISABLE_32BPP``: +``CONFIG_NX_DISABLE_1BPP``, ``CONFIG_NX_DISABLE_2BPP``, ``CONFIG_NX_DISABLE_4BPP``, ``CONFIG_NX_DISABLE_8BPP`` ``CONFIG_NX_DISABLE_16BPP``, ``CONFIG_NX_DISABLE_24BPP``, and ``CONFIG_NX_DISABLE_32BPP``: NX supports a variety of pixel depths. You can save some memory by disabling support for unused color depths. -``CONFIG_NX_PACKEDMSFIRST``: +``CONFIG_NX_PACKEDMSFIRST``: If a pixel depth of less than 8-bits is used, then NX needs to know if the pixels pack from the MS to LS or from LS to MS -``CONFIG_NX_LCDDRIVER``: +``CONFIG_NX_LCDDRIVER``: By default, NX builds to use a framebuffer driver (see ``include/nuttx/video/fb.h``). If this option is defined, NX will build to use an LCD driver (see ``include/nuttx/lcd/lcd.h``). -``CONFIG_NX_ANTIALIASING``: +``CONFIG_NX_ANTIALIASING``: Enable support for anti-aliasing when rendering lines as various orientations. This option is only available for use with frame buffer drivers and only with 16-, 24-, or 32-bit RGB color formats. @@ -109,11 +109,11 @@ NXGL Configuration Settings Configuration Settings ---------------------- -``CONFIG_NX_XYINPUT``: +``CONFIG_NX_XYINPUT``: Build in support for an X/Y input such as a mouse or a touscreen. -``CONFIG_NX_KBD``: +``CONFIG_NX_KBD``: Build in support of keypad/keyboard input. -``CONFIG_NX_WRITEONLY``: +``CONFIG_NX_WRITEONLY``: Define if the underlying graphics device does not support read operations. Automatically defined if ``CONFIG_NX_LCDDRIVER`` and ``CONFIG_LCD_NOGETRUN`` are defined. @@ -121,11 +121,11 @@ Configuration Settings NX Server Configuration Settings -------------------------------- -``CONFIG_NX_BLOCKING`` +``CONFIG_NX_BLOCKING`` Open the client message queues in blocking mode. In this case, ``nx_eventhandler()`` will not return until a message is received and processed. -``CONFIG_NX_MXSERVERMSGS`` and ``CONFIG_NX_MXCLIENTMSGS`` +``CONFIG_NX_MXSERVERMSGS`` and ``CONFIG_NX_MXCLIENTMSGS`` Specifies the maximum number of messages that can fit in the message queues. No additional resources are allocated, but this can be set to prevent flooding of the client or server with too many messages @@ -135,17 +135,17 @@ NX Server Configuration Settings NXTK Configuration Settings --------------------------- -``CONFIG_NXTK_BORDERWIDTH``: +``CONFIG_NXTK_BORDERWIDTH``: Specifies the width of the border (in pixels) used with framed windows. The default is 4. -``CONFIG_NXTK_BORDERCOLOR1``, ``CONFIG_NXTK_BORDERCOLOR2``, and ``CONFIG_NXTK_BORDERCOLOR3``: +``CONFIG_NXTK_BORDERCOLOR1``, ``CONFIG_NXTK_BORDERCOLOR2``, and ``CONFIG_NXTK_BORDERCOLOR3``: Specify the colors of the border used with framed windows. -``CONFIG_NXTK_BORDERCOLOR2`` +``CONFIG_NXTK_BORDERCOLOR2`` The shadow side color and so is normally darker. -``CONFIG_NXTK_BORDERCOLOR3`` +``CONFIG_NXTK_BORDERCOLOR3`` The shiny side color and so is normally brighter. The default is medium, dark, and light grey, respectively -``CONFIG_NXTK_AUTORAISE``: +``CONFIG_NXTK_AUTORAISE``: If set, a window will be raised to the top if the mouse position is over a visible portion of the window. Default: A mouse button must be clicked over a visible portion of the window. @@ -153,58 +153,58 @@ NXTK Configuration Settings NXFONTS Configuration Settings ------------------------------ -``CONFIG_NXFONTS_CHARBITS``: +``CONFIG_NXFONTS_CHARBITS``: The number of bits in the character set. Current options are only 7 and 8. The default is 7. -``CONFIG_NXFONT_SANS17X22``: +``CONFIG_NXFONT_SANS17X22``: This option enables support for a tiny, 17x22 san serif font (font ``ID FONTID_SANS17X22`` == 14). -``CONFIG_NXFONT_SANS20X26``: +``CONFIG_NXFONT_SANS20X26``: This option enables support for a tiny, 20x26 san serif font (font ``ID FONTID_SANS20X26`` == 15). -``CONFIG_NXFONT_SANS23X27``: +``CONFIG_NXFONT_SANS23X27``: This option enables support for a tiny, 23x27 san serif font (font ``ID FONTID_SANS23X27`` == 1). -``CONFIG_NXFONT_SANS22X29``: +``CONFIG_NXFONT_SANS22X29``: This option enables support for a small, 22x29 san serif font (font ``ID FONTID_SANS22X29`` == 2). -``CONFIG_NXFONT_SANS28X37``: +``CONFIG_NXFONT_SANS28X37``: This option enables support for a medium, 28x37 san serif font (font ``ID FONTID_SANS28X37`` == 3). -``CONFIG_NXFONT_SANS39X48``: +``CONFIG_NXFONT_SANS39X48``: This option enables support for a large, 39x48 san serif font (font ``ID FONTID_SANS39X48`` == 4). -``CONFIG_NXFONT_SANS17X23B``: +``CONFIG_NXFONT_SANS17X23B``: This option enables support for a tiny, 17x23 san serif bold font (font ``ID FONTID_SANS17X23B`` == 16). -``CONFIG_NXFONT_SANS20X27B``: +``CONFIG_NXFONT_SANS20X27B``: This option enables support for a tiny, 20x27 san serif bold font (font ``ID FONTID_SANS20X27B`` == 17). -``CONFIG_NXFONT_SANS22X29B``: +``CONFIG_NXFONT_SANS22X29B``: This option enables support for a small, 22x29 san serif bold font (font ID ``FONTID_SANS22X29B`` == 5). -``CONFIG_NXFONT_SANS28X37B``: +``CONFIG_NXFONT_SANS28X37B``: This option enables support for a medium, 28x37 san serif bold font (font ID ``FONTID_SANS28X37B`` == 6). -``CONFIG_NXFONT_SANS40X49B``: +``CONFIG_NXFONT_SANS40X49B``: This option enables support for a large, 40x49 san serif bold font (font ID ``FONTID_SANS40X49B`` == 7). -``CONFIG_NXFONT_SERIF22X29``: +``CONFIG_NXFONT_SERIF22X29``: This option enables support for a small, 22x29 font (with serifs) (font ID ``FONTID_SERIF22X29`` == 8). -``CONFIG_NXFONT_SERIF29X37``: +``CONFIG_NXFONT_SERIF29X37``: This option enables support for a medium, 29x37 font (with serifs) (font ID ``FONTID_SERIF29X37`` == 9). -``CONFIG_NXFONT_SERIF38X48``: +``CONFIG_NXFONT_SERIF38X48``: This option enables support for a large, 38x48 font (with serifs) (font ID ``FONTID_SERIF38X48`` == 10). -``CONFIG_NXFONT_SERIF22X28B``: +``CONFIG_NXFONT_SERIF22X28B``: This option enables support for a small, 27x38 bold font (with serifs) (font ID ``FONTID_SERIF22X28B`` == 11). -``CONFIG_NXFONT_SERIF27X38B``: +``CONFIG_NXFONT_SERIF27X38B``: This option enables support for a medium, 27x38 bold font (with serifs) (font ID ``FONTID_SERIF27X38B`` == 12). -``CONFIG_NXFONT_SERIF38X49B``: +``CONFIG_NXFONT_SERIF38X49B``: This option enables support for a large, 38x49 bold font (with serifs) (font ID ``FONTID_SERIF38X49B`` == 13). @@ -213,24 +213,24 @@ NxTerm Configuration Settings General NxTerm settings. -``CONFIG_NXTERM``: +``CONFIG_NXTERM``: Enables building of the NxTerm driver. NxTerm output text/graphics options: -``CONFIG_NXTERM_BPP``: +``CONFIG_NXTERM_BPP``: Currently, NxTerm supports only a single pixel depth. This configuration setting must be provided to support that single pixel depth. Default: The smallest enabled pixel depth. (see ``CONFIG_NX_DISABLE_*BPP``) -``CONFIG_NXTERM_CURSORCHAR``: +``CONFIG_NXTERM_CURSORCHAR``: The bitmap code to use as the cursor. Default '_' -``CONFIG_NXTERM_MXCHARS``: +``CONFIG_NXTERM_MXCHARS``: NxTerm needs to remember every character written to the console so that it can redraw the window. This setting determines the size of some internal memory allocations used to hold the character data. Default: 128. -``CONFIG_NXTERM_CACHESIZE``: +``CONFIG_NXTERM_CACHESIZE``: NxTerm supports caching of rendered fonts. This font caching is required for two reasons: (1) First, it improves text performance, but more importantly (2) it preserves the font memory. Since the NX @@ -251,26 +251,26 @@ NxTerm output text/graphics options: server task. ``CONFIG_NXTERM_CACHESIZE`` should be larger than ``CONFIG_MQ_MAXMSGSIZE`` in any event. -``CONFIG_NXTERM_LINESEPARATION``: +``CONFIG_NXTERM_LINESEPARATION``: This the space (in rows) between each row of test. Default: 0 -``CONFIG_NXTERM_NOWRAP``: +``CONFIG_NXTERM_NOWRAP``: By default, lines will wrap when the test reaches the right hand side of the window. This setting can be defining to change this behavior so that the text is simply truncated until a new line is encountered. NxTerm input options: -``CONFIG_NXTERM_NXKBDIN``: +``CONFIG_NXTERM_NXKBDIN``: Take input from the NX keyboard input callback. By default, keyboard input is taken from stdin (``/dev/console``). If this option is set, then the interface\ ``nxterm_kdbin()`` is enabled. That interface may be driven by window callback functions so that keyboard input *only* goes to the top window. -``CONFIG_NXTERM_KBDBUFSIZE``: +``CONFIG_NXTERM_KBDBUFSIZE``: If ``CONFIG_NXTERM_NXKBDIN`` is enabled, then this value may be used to define the size of the per-window keyboard input buffer. Default: 16 -``CONFIG_NXTERM_NPOLLWAITERS``: +``CONFIG_NXTERM_NPOLLWAITERS``: The number of threads that can be waiting for read data available. Default: 4 @@ -323,25 +323,25 @@ yournew font in a similar fashion: 4. ``include/nuttx/nx/nxfonts.h``. Add you new font as a possible system default font: - + .. code-block:: c - + #if defined(CONFIG_NXFONT_SANS23X27) # define NXFONT_DEFAULT FONTID_SANS23X27 #elif defined(CONFIG_NXFONT_MYFONT) # define NXFONT_DEFAULT FONTID_MYFONT #endif - + Then define the actual font ID. Make sure that the font ID value is unique: .. code-block:: c - + #if defined(CONFIG_NXFONT_SANS23X27) # define NXFONT_DEFAULT FONTID_SANS23X27 #elif defined(CONFIG_NXFONT_MYFONT) # define NXFONT_DEFAULT FONTID_MYFONT - #endif + #endif New Add the font to the NX build system. There are several files that you have to modify to do this. Look how the build system uses the font @@ -352,29 +352,29 @@ CONFIG_NXFONT_SANS23X27 for examaples: with the *bdf-converter* program. Notice ``NXFONTS_FONTID=2``; this must be set to the same font ID value that you defined in the ``include/nuttx/nx/nxfonts.h`` file. - + .. code-block:: makefile - + genfontsources: ifeq ($(CONFIG_NXFONT_SANS23X27),y) @$(MAKE) -C nxfonts -f Makefile.sources NXFONTS_FONTID=1 EXTRAFLAGS=$(EXTRAFLAGS) endif ifeq ($(CONFIG_NXFONT_MYFONT),y) @$(MAKE) -C nxfonts -f Makefile.sources NXFONTS_FONTID=2 EXTRAFLAGS=$(EXTRAFLAGS) - endif + endif 6. ``nuttx/graphics/nxfonts/Make.defs``. Set the make variable ``NXFSET_CSRCS``. ``NXFSET_CSRCS`` determines the name of the font C file to build when ``NXFONTS_FONTID=2``: - + .. code-block:: makefile - + ifeq ($(CONFIG_NXFONT_SANS23X27),y) NXFSET_CSRCS += nxfonts_bitmaps_sans23x27.c endif ifeq ($(CONFIG_NXFONT_MYFONT),y) NXFSET_CSRCS += nxfonts_bitmaps_myfont.c - endif + endif 7. ``nuttx/graphics/nxfonts/Makefile.sources``. This is the Makefile used in step 5 that will actually generate the font C file. So, given @@ -382,9 +382,9 @@ CONFIG_NXFONT_SANS23X27 for examaples: auto-generated variable and function names and (again) the name of the autogenerated file to create (this must be the same name that was used in ``nuttx/graphics/nxfonts/Make.defs``): - + .. code-block:: makefile - + ifeq ($(NXFONTS_FONTID),1) NXFONTS_PREFIX := g_sans23x27_ GEN_CSRC = nxfonts_bitmaps_sans23x27.c @@ -393,21 +393,21 @@ CONFIG_NXFONT_SANS23X27 for examaples: NXFONTS_PREFIX := g_myfont_ GEN_CSRC = nxfonts_bitmaps_myfont.c endif - + 8. ``graphics/nxfonts/nxfonts_bitmaps.c``. This is the file that contains the generic font structures. It is used as a "template&qout; file by ``nuttx/graphics/nxfonts/Makefile.sources``\ to create your customized font data set at build time. - + .. code-block:: c - + #if NXFONTS_FONTID == 1 # include "nxfonts_sans23x27.h" #elif NXFONTS_FONTID == 2 # include "nxfonts_myfont.h" #else # error "No font ID specified" - #endif + #endif Where ``nxfonts_myfont.h`` is the NuttX font file that we generated in step 2 using the *bdf-converter* tool. @@ -419,9 +419,9 @@ CONFIG_NXFONT_SANS23X27 for examaples: Note that the lookup is based on the font ID that was defined in step 4. The new font information needs to be added to data structures used by that function: - + .. code-block:: c - + #ifdef CONFIG_NXFONT_SANS23X27 extern const struct nx_fontpackage_s g_sans23x27_package; #endif @@ -439,7 +439,7 @@ CONFIG_NXFONT_SANS23X27 for examaples: #endif NULL }; - + NX Test Coverage ================ @@ -460,10 +460,10 @@ configurations for building the simulation: feedback. In this configuration, a very simple, simulated framebuffer driver is used that is based upon a simple region of memory posing as video memory. That default configuration can be built as follows:: - + tools/configure.sh sim:nx make - ./nuttx + ./nuttx #. The preferred configuration is at ``boards/sim/sim/sim/configs/nx11/defconfig``. This configuration @@ -471,10 +471,10 @@ configurations for building the simulation: window as a framebuffer. This is a superior test configuration because the X window appears at your desktop and you can see the NX output. This preferred configuration can be built as follows:: - + tools/configure sim:nx11 make - ./nuttx + ./nuttx *Update:* The sim target has suffered some bit-rot over the years and so the following caveats need to be added: @@ -537,7 +537,7 @@ Function Special Setup/Notes Verified There is a "fudge factor" that seems to eliminate the problem, but there could still be issues in some - configurations. + configurations. ``nxgl_circlepts`` Verified by apps/examples/nxlines. YES ``nxgl_circletraps`` Verified by apps/examples/nxlines. YES ================================ ==================================== ======== @@ -569,25 +569,25 @@ Function Special Setup/Notes ``nx_openwindow()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES ``/.config file`` ``nx_closewindow()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` YES - in the ``/.config`` file + in the ``/.config`` file ``nx_requestbkgd()`` Verified by ``apps/examples/nxtext`` and YES - ``apps/examples/nxhello``. + ``apps/examples/nxhello``. ``nx_releasebkgd()`` Verified by ``apps/examples/nxtext`` and YES - ``apps/examples/nxhello``. + ``apps/examples/nxhello``. ``nx_getposition()`` . NO ``nx_setposition()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES - ``/.config`` file + ``/.config`` file ``nx_setsize()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES - ``/.config`` file + ``/.config`` file ``nx_raise()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES - ``/.config`` file + ``/.config`` file ``nx_lower()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES - ``/.config`` file + ``/.config`` file ``nx_modal()`` . NO ``nx_setvisibility()`` Exercized using Twm4Nx YES, Informally ``nx_ishidden()`` Exercized using Twm4Nx YES, Informally ``nx_fill()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES - ``/.config`` file + ``/.config`` file ``nx_getrectangle()`` . YES ``nx_filltrapezoid()`` Verified by ``apps/examples/nxlines``. YES ``nx_drawline()`` by ``apps/examples/nxlines``. YES @@ -595,9 +595,9 @@ Function Special Setup/Notes ``nx_fillcircle()`` Verified by ``apps/examples/nxlines``. YES ``nx_setbgcolor()`` . YES ``nx_move()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES - ``/.config`` file + ``/.config`` file ``nx_bitmap()`` Change to ``CONFIG_EXAMPLES_NX_RAWWINDOWS=y`` in the YES - ``/.config`` file. + ``/.config`` file. ``nx_kbdin()`` . YES ``nx_mousein()`` . YES ========================= =============================================================== ======== @@ -640,7 +640,7 @@ Function Special Setup/Notes Verified NXFONTS API Test Coverage ------------------------- - + ======================== ============================= ======== Function Special Setup/Notes Verified ======================== ============================= ======== diff --git a/Documentation/components/nxgraphics/index.rst b/Documentation/components/nxgraphics/index.rst index 1c49a934c1..aecda44858 100644 --- a/Documentation/components/nxgraphics/index.rst +++ b/Documentation/components/nxgraphics/index.rst @@ -9,7 +9,7 @@ organization, and OS configuration options. .. figure:: NuttXScreenShot.jpg :align: center - + **Figure 1**. This screnshot shows the final frame for the NuttX example at ``apps/examples/nx`` running on the simulated, Linux x86 platform with simulated framebuffer output to an X window. This picture shows to framed window @@ -152,18 +152,18 @@ and ``stderr`` and, hence, can provide the output side of NuttX console. NX Header Files =============== -``include/nuttx/nx/nxglib.h`` +``include/nuttx/nx/nxglib.h`` Describes the NXGLIB C interfaces -``include/nuttx/nx/nx.h`` +``include/nuttx/nx/nx.h`` Describes the NX C interfaces -``include/nutt/nxtk.h`` +``include/nutt/nxtk.h`` Describe the NXTOOLKIT C interfaces -``include/nutt/nxfont.h`` +``include/nutt/nxfont.h`` Describe sthe NXFONT C interfaces .. toctree:: :Caption: User APIs - + nxgl.rst nx.rst nxtk.rst @@ -171,4 +171,4 @@ NX Header Files nxcursor.rst sample.rst appendix.rst - + diff --git a/Documentation/components/nxgraphics/nx.rst b/Documentation/components/nxgraphics/nx.rst index 0206a4d338..dc2457d5fd 100644 --- a/Documentation/components/nxgraphics/nx.rst +++ b/Documentation/components/nxgraphics/nx.rst @@ -38,7 +38,7 @@ These callbacks will be invoked as part of the processing performed by .. c:struct:: nx_callback_s .. code-block:: c - + struct nx_callback_s { void (*redraw)(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect, @@ -70,9 +70,9 @@ start this daemon. There are two ways that this can be done: ``CONFIG_BOARD_LATE_INITIALIZE`` is defined in the configuration. Or, the board startup logic can execute under control of the application by calling :c:func:`boardctl` as: - + .. code-block:: c - + boardctl(BOARDIOC_INIT, arg) The board initialization logic will run in either case and the simple @@ -98,7 +98,7 @@ start this daemon. There are two ways that this can be done: waiting to accept connections from NX clients. A negated ``errno`` value is returned on failure. The ``errno`` value indicates the nature of the failure. - + NX Server Callbacks =================== @@ -107,12 +107,12 @@ NX Server Callbacks NX requests that the client re-draw the portion of the window within with rectangle. - :param hwnd: + :param hwnd: The handle created by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd` :param rect: The rectangle that needs to be re-drawn (in window relative coordinates) - :param more: + :param more: true: More re-draw requests will follow :param arg: User provided argument (see :c:func:`nx_openwindow`) @@ -125,7 +125,7 @@ NX Server Callbacks The size or position of the window has changed (or the window was just created with zero size. - :param hwnd: + :param hwnd: The handle created by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd` :param size: The size of the window @@ -155,11 +155,11 @@ NX Server Callbacks New keyboard/keypad data is available for the window. - :param hwnd: + :param hwnd: The handle created by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd` - :param nch: + :param nch: The number of characters that are available in ch[] - :param ch: + :param ch: The array of characters :param arg: User provided argument (see :c:func:`nx_openwindow`) @@ -168,7 +168,7 @@ NX Server Callbacks This callback is used to communicate server events to the window listener. - - ``NXEVENT_BLOCKED``: Window messages are blocked. + - ``NXEVENT_BLOCKED``: Window messages are blocked. This callback is the response from :c:func:`nx_block`, :c:func:`nxtk_block`. Those blocking interfaces are used to assure that no further messages are directed to the window. @@ -180,7 +180,7 @@ NX Server Callbacks callbacks are processed. Then the window may be safely closed. Closing the window prior with pending callbacks can lead to bad behavior when the callback is executed. - - ``NXEVENT_SYNCHED``: Synchronization handshake + - ``NXEVENT_SYNCHED``: Synchronization handshake This completes the handshake started by :c:func:`nx_synch`, or :c:func:`nxtk_synch`. Those interfaces send a synchronization messages to the NX server @@ -190,23 +190,23 @@ NX Server Callbacks synchronization is sometimes necessary to assure that the client and server are working together properly. - :param hwnd: + :param hwnd: TWindow handle of window receiving the event - :param event: + :param event: The server event - :param arg1: + :param arg1: User provided argument (see :c:func:`nx_openwindow`, :c:func:`nx_requestbkgd`, or :c:func:`nxtk_opentoolbar`) - :param arg2: + :param arg2: TUser provided argument (see :c:func:`nx_block`, :c:func:`nxtk_block`, :c:func:`nx_synch`, or :c:func:`nxtk_synch`) .. c:macro:: nx_run(fb) .. code-block:: c - + #define nx_run(fb) nx_runinstance(NX_DEFAULT_SERVER_MQNAME, dev) - + .. c:function:: int nx_runinstance(FAR const char *mqname, FAR struct fb_vtable_s *fb) This is the server entry point. It does not return; the @@ -227,9 +227,9 @@ NX Server Callbacks .. c:macro:: nx_connect(cb) .. code-block:: c - + #define nx_connect(cb) nx_connectinstance(NX_DEFAULT_SERVER_MQNAME) - + .. c:function:: NXHANDLE nx_connectinstance(FAR const char *svrmqname); Open a connection from a client to the NX server. One @@ -250,8 +250,8 @@ NX Server Callbacks :param svrmqname: The name for the server incoming message queue :return: Success: A non-NULL handle used with subsequent NX accesses - Failure: NULL is returned and errno is set appropriately. - + Failure: NULL is returned and errno is set appropriately. + .. c:function:: void nx_disconnect(NXHANDLE handle) Disconnect a client from the NX server and/or free @@ -321,7 +321,7 @@ NX Server Callbacks prior with pending callbacks can lead to bad behavior when the callback is executed. - :param wnd: The window to be blocked + :param wnd: The window to be blocked :param arg: An argument that will accompany the block messages (This is ``arg2`` in the event callback). @@ -341,7 +341,7 @@ NX Server Callbacks server are fully synchronized in time. Usage by the window client might be something like this: - + .. code-block:: c extern bool g_synched; @@ -376,7 +376,7 @@ NX Server Callbacks .. c:function:: NXWINDOW nx_openwindow(NXHANDLE handle, uint8_t flags, \ FAR const struct nx_callback_s *cb, \ FAR void *arg); - + Create a new window. :param handle: The handle returned by ```nx_connect()`` <#nxconnectinstance>`__. @@ -388,7 +388,7 @@ NX Server Callbacks :param arg: User provided value that will be returned with NX callbacks. :return: Success: A non-NULL handle used with subsequent NX accesses - Failure: NULL is returned and errno is set appropriately. + Failure: NULL is returned and errno is set appropriately. .. c:function:: int nx_closewindow(NXWINDOW hwnd) @@ -543,7 +543,7 @@ NX Server Callbacks .. c:function:: int nx_fill(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect, \ nxgl_mxpixel_t color[CONFIG_NX_NPLANES]); - + Fill the specified rectangle in the window with the specified color. @@ -608,7 +608,7 @@ NX Server Callbacks :param color: The color to use to fill the line :param caps: Draw a circular cap on the ends of the line to support better line joins. One of:: - + /* Line caps */ #define NX_LINECAP_NONE 0x00, /* No line caps */ diff --git a/Documentation/components/nxgraphics/nxcursor.rst b/Documentation/components/nxgraphics/nxcursor.rst index 77205ab3d0..92c0d5647c 100644 --- a/Documentation/components/nxgraphics/nxcursor.rst +++ b/Documentation/components/nxgraphics/nxcursor.rst @@ -20,7 +20,7 @@ NX Cursor Support (``NXCURSOR``) The image is provided a a 2-bits-per-pixel image. The two bit incoding is as following: - + - 00: The transparent background. - 01: Color1: The main color of the cursor. - 10: Color2: The color of any border. diff --git a/Documentation/components/nxgraphics/nxfonts.rst b/Documentation/components/nxgraphics/nxfonts.rst index 98da7d3842..db00502407 100644 --- a/Documentation/components/nxgraphics/nxfonts.rst +++ b/Documentation/components/nxgraphics/nxfonts.rst @@ -34,7 +34,7 @@ NXFONTS types }; -.. c:struct:: nx_fontset_s +.. c:struct:: nx_fontset_s This structure describes one contiguous grouping of glyphs that can be described by an array starting with encoding ``first`` and extending @@ -84,7 +84,7 @@ NXFONTS types Return font bitmap information for the selected character encoding. - :param ch: The char code for the requested bitmap. + :param ch: The char code for the requested bitmap. :param handle: A font handle previously returned by :c:func:`nxf_getfonthandle`. :return: An instance of :c:struct:`nx_fontbitmap_s` describing the glyph. @@ -92,7 +92,7 @@ NXFONTS types uint16_t width, uint16_t stride, \ FAR const struct nx_fontbitmap_s *bm, \ nxgl_mxpixel_t color); - + .. c:function:: int nxf_convert_4bpp(FAR uint8_t *dest, uint16_t height, \ uint16_t width, uint16_t stride, \ FAR const struct nx_fontbitmap_s *bm, \ @@ -113,7 +113,7 @@ NXFONTS types uint16_t width, uint16_t stride, \ FAR const struct nx_fontbitmap_s *bm, \ nxgl_mxpixel_t color); - + Convert the 1BPP font to a new pixel depth. :param dest: The destination buffer provided by the caller. diff --git a/Documentation/components/nxgraphics/nxgl.rst b/Documentation/components/nxgraphics/nxgl.rst index 45d89cd77c..391a7fe0fc 100644 --- a/Documentation/components/nxgraphics/nxgl.rst +++ b/Documentation/components/nxgraphics/nxgl.rst @@ -21,17 +21,17 @@ NXGL Types if 24, and 32 resolution support is disabled, or ``uint32_t``. .. c:type:: nxgl_coord_t - + A given coordinate is limited to the screen height an width. If either of those values exceed 32,767 pixels, then the following will have to need to change: .. c:struct:: nxgl_point_s - + Describes a point on the display: - + .. code-block:: c - + struct nxgl_point_s { nxgl_coord_t x; /* X position, range: 0 to screen width - 1 */ @@ -39,28 +39,28 @@ NXGL Types }; .. c:struct:: nxgl_size_s - + Describes the size of a rectangular region. - + .. code-block:: c - + struct nxgl_size_s { nxgl_coord_t w; /* Width in pixels */ nxgl_coord_t h; /* Height in rows */ - }; + }; .. c:struct:: nxgl_rect_s Describes a positioned rectangle on the display. - + .. code-block:: c - + struct nxgl_rect_s { struct nxgl_point_s pt1; /* Upper, left-hand corner */ struct nxgl_point_s pt2; /* Lower, right-hand corner */ - }; + }; .. c:struct:: nxgl_run_s @@ -68,30 +68,30 @@ NXGL Types that the start/end positions have fractional precision. This is necessary for good joining of trapezoids when a more complex shape is decomposed into trapezoids. - + .. code-block:: c - + struct nxgl_run_s { b16_t x1; /* Left X position, range: 0 to x2 */ b16_t x2; /* Right X position, range: x1 to screen width - 1 */ nxgl_coord_t y; /* Top Y position, range: 0 to screen height - 1 */ }; - + .. c:struct:: nxgl_trapezoid_s Describes a horizontal trapezoid on the display in terms the run at the top of the trapezoid and the run at the bottom. - + .. code-block:: c - + struct nxgl_trapezoid_s { struct nxgl_run_s top; /* Top run */ struct nxgl_run_s bot; /* bottom run */ }; - + .. c:function:: void nxgl_rgb2yuv(uint8_t r, uint8_t g, uint8_t b, uint8_t *y, uint8_t *u, uint8_t *v) Convert 8-bit RGB triplet to 8-bit YUV triplet. @@ -144,24 +144,24 @@ NXGL Types .. c:function:: void nxgl_nonintersecting(FAR struct nxgl_rect_s result[4], \ FAR const struct nxgl_rect_s *rect1, \ FAR const struct nxgl_rect_s *rect2); - + Return the regions of rectangle ``rect1`` that do not intersect with ``rect2``. This will four rectangles, some of which may be degenerate (and can be picked off with :c:func:`nxgl_nullrect`). .. c:function:: bool nxgl_rectoverlap(FAR struct nxgl_rect_s *rect1, \ FAR struct nxgl_rect_s *rect2); - + Return true if the two rectangles overlap. .. c:function:: bool nxgl_rectinside(FAR const struct nxgl_rect_s *rect, \ FAR const struct nxgl_point_s *pt); - + Return true if the point ``pt`` lies within ``rect``. .. c:function:: void nxgl_rectsize(FAR struct nxgl_size_s *size, \ FAR const struct nxgl_rect_s *rect); - + Return the size of the specified rectangle. .. c:function:: bool nxgl_nullrect(FAR const struct nxgl_rect_s *rect); @@ -171,33 +171,33 @@ NXGL Types .. c:function:: void nxgl_runoffset(FAR struct nxgl_run_s *dest, \ FAR const struct nxgl_run_s *src, \ nxgl_coord_t dx, nxgl_coord_t dy); - + Offset the run position by the specified ``dx``, ``dy`` values. .. c:function:: void nxgl_runcopy(FAR struct nxgl_run_s *dest, \ FAR const struct nxgl_run_s *src); - + This is essentially ``memcpy()``\ for runs. We don't do structure assignments because some compilers are not good at that. .. c:function:: void nxgl_trapoffset(FAR struct nxgl_trapezoid_s *dest, \ FAR const struct nxgl_trapezoid_s *src, \ nxgl_coord_t dx, nxgl_coord_t dy); - + Offset the trapezoid position by the specified ``dx``, ``dy`` values. .. c:function:: void nxgl_trapcopy(FAR struct nxgl_trapezoid_s *dest, \ FAR const struct nxgl_trapezoid_s *src); - + This is essentially ``memcpy()``\ for trapezoids. We don't do structure assignments because some compilers are not good at that. .. c:function:: void nxgl_colorcopy(nxgl_mxpixel_t dest[CONFIG_NX_NPLANES], \ const nxgl_mxpixel_t src[CONFIG_NX_NPLANES]); - + This is essentially ``memcpy()``\ for colors. This does very little for us other than hide all of the conditional compilation for planar colors in one place. @@ -230,7 +230,7 @@ NXGL Types - 0: Line successfully broken up into three trapezoids. Values in traps[0], traps[1], and traps[2] are valid. - 1: Line successfully represented by one trapezoid. Value in traps[1] is valid. - 2: Line successfully represented by one rectangle. Value in rect is valid - - <0: On errors, a negated errno value is returned. + - <0: On errors, a negated errno value is returned. .. c:function:: void nxgl_circlepts(FAR const struct nxgl_point_s *center, nxgl_coord_t radius, \ FAR struct nxgl_point_s *circle); diff --git a/Documentation/components/nxgraphics/nxtk.rst b/Documentation/components/nxgraphics/nxtk.rst index 52a80cc1c5..6ff4a0271b 100644 --- a/Documentation/components/nxgraphics/nxtk.rst +++ b/Documentation/components/nxgraphics/nxtk.rst @@ -26,10 +26,10 @@ these sub-windows to be managed more-or-less independently: coordinate system for each sub-window begins at the top left corner of the subwindow. This means that toolbar logic need not be concerned about client window geometry (and vice versa) and, - for example, common toolbar logic can be used with different windows. + for example, common toolbar logic can be used with different windows. .. c:type:: FAR void *NXTKWINDOW - + This is the handle that can be used to access the window data region. .. c:function:: int nxtk_block(NXWINDOW hwnd, FAR void *arg) @@ -71,9 +71,9 @@ these sub-windows to be managed more-or-less independently: server are fully synchronized in time. Usage by the window client might be something like this: - + .. code-block:: c - + extern bool g_synched; extern sem_t g_synch_sem; @@ -91,7 +91,7 @@ these sub-windows to be managed more-or-less independently: { -- Handle the error -- } - } + } When the window listener thread receives the ``NXEVENT_SYNCHED`` event, it would set ``g_synched`` to ``true`` and post ``g_synch_sem``, waking @@ -128,7 +128,7 @@ these sub-windows to be managed more-or-less independently: User provided argument (see ```nx_openwindow()`` <#nxopenwindow>`__) :return: Success: A non-NULL handle used with subsequent NXTK window accesses - Failure: NULL is returned and errno is set appropriately. + Failure: NULL is returned and errno is set appropriately. .. c:function:: int nxtk_closewindow(NXTKWINDOW hfwnd); @@ -204,7 +204,7 @@ these sub-windows to be managed more-or-less independently: Lower the window containing the specified client sub-window to the bottom of the display. - :param hfwnd: + :param hfwnd: A handle previously returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__ specifying the window to be lowered. @@ -251,7 +251,7 @@ these sub-windows to be managed more-or-less independently: is reported by ``nxtk_ishidden()``. ``nxtk_synch()`` may be used if temporal synchronization is required. - :param hfwnd: + :param hfwnd: The handle returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__ that identifies the window to be queried. @@ -351,7 +351,7 @@ these sub-windows to be managed more-or-less independently: Draw a circular outline using the specified line thickness and color. - :param hfwnd: + :param hfwnd: A handle previously returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__. :param center: @@ -371,7 +371,7 @@ these sub-windows to be managed more-or-less independently: Fill a circular region using the specified color. - :param hfwnd: + :param hfwnd: A handle previously returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__. :param center: @@ -548,16 +548,16 @@ these sub-windows to be managed more-or-less independently: :param caps: Draw a circular cap on the ends of the line to support better line joins. One of: - + .. code-block:: c - + /* Line caps */ #define NX_LINECAP_NONE 0x00, /* No line caps */ #define NX_LINECAP_PT1 0x01 /* Line cap on pt1 on of the vector only */ #define NX_LINECAP_PT2 0x02 /* Line cap on pt2 on of the vector only */ #define NX_LINECAP_BOTH 0x03 /* Line cap on both ends of the vector only */ - + :return: ``OK`` on success; ``ERROR`` on failure with ``errno`` set appropriately @@ -569,7 +569,7 @@ these sub-windows to be managed more-or-less independently: Draw a circular outline using the specified line thickness and color. - :param hfwnd: + :param hfwnd: A handle previously returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__. :param center: @@ -608,7 +608,7 @@ these sub-windows to be managed more-or-less independently: Move a rectangular region within the toolbar sub-window of a framed window. - :param hfwnd: + :param hfwnd: A handle identifying sub-window containing the toolbar within which the move is to be done. This handle must have previously been returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__. @@ -633,10 +633,10 @@ these sub-windows to be managed more-or-less independently: :param hfwnd: A handle previously returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__. - :param dest: + :param dest: Describes the rectangular region on in the toolbar sub-window will receive the bit map. - :param src: + :param src: The start of the source image. :param origin: The origin of the upper, left-most corner of the full bitmap. Both diff --git a/Documentation/components/power.rst b/Documentation/components/power.rst index 3a41debd0e..7b9e35aa7d 100644 --- a/Documentation/components/power.rst +++ b/Documentation/components/power.rst @@ -30,26 +30,26 @@ consumption states have various names and are sometimes used in conflicting ways. In the NuttX PM logic, we will use the following terminology: - ``NORMAL`` + ``NORMAL`` The normal, full power operating mode. - ``IDLE`` + ``IDLE`` This is still basically normal operational mode, the system is, however, ``IDLE`` and some simple simple steps to reduce power consumption provided that they do not interfere with normal Operation. Simply dimming the a backlight might be an example some that that would be done when the system is idle. - ``STANDBY`` + ``STANDBY`` Standby is a lower power consumption mode that may involve more extensive power management steps such has disabling clocking or setting the processor into reduced power consumption modes. In this state, the system should still be able to resume normal activity almost immediately. - ``SLEEP`` + ``SLEEP`` The lowest power consumption mode. The most drastic power reduction measures possible should be taken in this state. It may require some time to get back to normal operation from ``SLEEP`` (some MCUs may even require going through reset). - + .. c:enum:: pm_state_e These various states are represented with type :c:enum:`pm_state_e` @@ -117,7 +117,7 @@ All PM interfaces are declared in the file ``include/nuttx/power/pm.h``. and prevent entering reduced power states. :param domain: Identifies the domain of the new PM activity - :param priority: + :param priority: Activity priority, range 0-9. Larger values correspond to higher priorities. Higher priority activity can prevent the system from entering reduced power states for a longer period @@ -199,16 +199,16 @@ Callbacks state change mode by returning a non-zero value from the callback function. - :param cb: + :param cb: Returned to the driver. The driver version of the callback structure may include additional, driver-specific state data at the end of the structure. - :param domain: + :param domain: Identifies the activity domain of the state change - :param pmstate: + :param pmstate: Identifies the new PM state - :return: + :return: Zero (``OK``) means the event was successfully processed and that the driver is prepared for the PM state change. Non-zero means that the driver is not prepared to perform the @@ -225,13 +225,13 @@ Callbacks callback is called after all drivers have had the opportunity to prepare for the new power state. - :param cb: + :param cb: Returned to the driver. The driver version of the callback structure may include additional, driver-specific state data at the end of the structure. - :param domain: + :param domain: Identifies the activity domain of the state change - :param pmstate: + :param pmstate: Identifies the new PM state The driver already agreed to transition diff --git a/Documentation/components/socketcan.rst b/Documentation/components/socketcan.rst index 9c3b71b293..cd9556fc48 100644 --- a/Documentation/components/socketcan.rst +++ b/Documentation/components/socketcan.rst @@ -17,7 +17,7 @@ SocketCAN Device Drivers dlc to CAN FD len sizes named .. code-block:: c - + extern const uint8_t can_dlc_to_len[16]; extern const uint8_t len_to_can_dlc[65]; diff --git a/Documentation/components/syslog.rst b/Documentation/components/syslog.rst index 58b1467cc3..a19f3e4b7f 100644 --- a/Documentation/components/syslog.rst +++ b/Documentation/components/syslog.rst @@ -62,11 +62,11 @@ extent, its companion ``vsyslog()``: controlling the SYSLOG output only form that process. There will be a separate mask accessible only in the kernel code to control kernel SYSLOG output. - + The above are all standard interfaces as defined at `OpenGroup.org `__. Those interfaces are available for use by application software. -The remaining interfaces discussed in this section are non-standard, OS-internal interfaces. +The remaining interfaces discussed in this section are non-standard, OS-internal interfaces. Debug Interfaces ---------------- @@ -166,7 +166,7 @@ The channel interface is instantiated by calling :return: Zero (OK)is returned on success. A negated errno value is - returned on any failure. + returned on any failure. SYSLOG Channel Initialization ----------------------------- @@ -423,14 +423,14 @@ SYSLOG file channel: NOTE interrupt level SYSLOG output will be lost in this case unless the interrupt buffer is used. - :param devpath: + :param devpath: The full path to the file to be used for SYSLOG output. This may be an existing file or not. If the file exists, ``syslog_file_channel()`` will append new SYSLOG data to the end of the file. If it does not, then ``syslog_file_channel()`` will create the file. - :return: + :return: Zero (``OK``) is returned on success; a negated ``errno`` value is returned on any failure. diff --git a/Documentation/contributing/documentation.rst b/Documentation/contributing/documentation.rst index 8fde17f25c..9b19650208 100644 --- a/Documentation/contributing/documentation.rst +++ b/Documentation/contributing/documentation.rst @@ -12,32 +12,32 @@ Using Sphinx, the RST files are rendered into HTML files that can be read in you Building ======== -To render the Documentation locally, you should clone the NuttX main repository, and +To render the Documentation locally, you should clone the NuttX main repository, and go into ``Documentation`` directory. Then, 1. Install Sphinx and other dependencies using pipenv. You may also find it helpful on platforms such as Windows and MacOS to use *pyenv* to manage your python installation. You can read about installing that on the project `site `_. - + .. code-block:: console - + $ pip3 install pipenv $ pipenv install $ # activate the virtual environent $ pipenv shell - + 2. Build documentation: - + .. code-block:: console - + $ make html - + The resulting HTMLs will end up under ``_build/html``. You can open your browser at the root with: - + .. code-block:: console - - $ xdg-open _build/html/index.html + + $ xdg-open _build/html/index.html Contributing ============ @@ -85,35 +85,35 @@ Sections should look like this: Subsection ========== - + Subsubsection ------------- - + Code ---- -Code should be documented using the `C domain `_. +Code should be documented using the `C domain `_. This means for example that a function should be documented as: .. code-block:: RST .. c:function:: bool myfunction(int arg1, int arg2) - + Here the function should be described - + :param arg1: Description of arg1 :param arg2: Description of arg2 - + :return: Description of return value - + To document a piece of code, use a ``code-block`` `directive `_, specifying the highlight language. If the block is not of code but some verbatim piece of text, it is acceptable to use RST standard `::`. This is specially useful and compact when used in the following mode: .. code-block:: RST The text file should have the following content:: - - Line1 + + Line1 Line2 Line3 @@ -124,15 +124,15 @@ To generate internal links, Sphinx's `roles `_`` for internal links. Moreover, sphinx is configured to use `autosectionlabel `_ extension. This means that sections will automatically get a label that can be linked with the -`:ref:`. For example: +`:ref:`. For example: .. code-block:: RST This is a Section ================= - + :ref:`This is a Section` is a link to this very same section. - + If the target is in a different file, you can refer it with: ``:ref:`link text ```. Notes and TODOS @@ -176,10 +176,10 @@ Generally, you should follow this format: .. code-block:: RST .. directive:: - - child content - - non-child content which appears after previous directive - -Note the line between directive and content and the indentation. + + child content + + non-child content which appears after previous directive + +Note the line between directive and content and the indentation. diff --git a/Documentation/contributing/index.rst b/Documentation/contributing/index.rst index b2428f0750..526e0d72e2 100644 --- a/Documentation/contributing/index.rst +++ b/Documentation/contributing/index.rst @@ -1,7 +1,7 @@ Contributing ============ -In the following sections you will find important information on how to contribute to NuttX codebase (from small bugfixes to large new features) +In the following sections you will find important information on how to contribute to NuttX codebase (from small bugfixes to large new features) and documentation (the one you are reading now): .. toctree:: diff --git a/Documentation/contributing/workflow.rst b/Documentation/contributing/workflow.rst index 41bd934ff8..574c873794 100644 --- a/Documentation/contributing/workflow.rst +++ b/Documentation/contributing/workflow.rst @@ -11,32 +11,32 @@ You should be aware of the following: - All contributions must adhere to the :doc:`Coding Standard `. You can check your files using ``nxstyle`` or complete patchsets using ``checkpatch`` script (both found in ``tools`` subdirectory of NuttX repository). This check will also run automatically during CI to ensure conformance. - + Note that not all existing files in the repository are already adapted to conform to the standard as this is an ongoing effort. Thus, if you're submitting a patch to an existing file you may have to make the file conform to the standard, even if you are not reponsible - for those standard violations. - + for those standard violations. + It is also appreciated that you separate any styling fixes in a separate commit from the functional changes so that these are more easily readable during review. - + - Before starting work on any given non trivial contribution, do subscribe to the mailing list and ask about your idea to avoid wasted effort by going the wrong-route. - + - If you are submitting an original contribution (you wrote the code yourself from scratch) it will have to be submitted under the terms of the Apache 2.0 License using the corresponding :ref:`header `. - + Note that if you are working as an employee in a company, usually copyright belongs to the company and thus this means the company will have to authorize this and submit the appropriate license agreements. - + - If you are submitting third-party code: - - - Code from actively developed projects is not accepted to be included in NuttX (i.e.: creating a fork). It is expected that + + - Code from actively developed projects is not accepted to be included in NuttX (i.e.: creating a fork). It is expected that changes required in third-party code for NuttX support are to be implemented in these projects. As an intermediate solution, it is acceptable to include a patch to be applied to this third-party code, which will be pulled during built. - + - If this is from an inactive project, it may be considered for inclusion in NuttX, provided that licensing terms allow to do so and it is deemed of sufficient value to be included, considering that this code will have to be maintained in NuttX afterwards. - + Note that it is undesireable to included non Apache 2.0 Licensed code inside the repository, even if the license itself allows it (for example BSD License). - + diff --git a/Documentation/guides/tasktraceuser.rst b/Documentation/guides/tasktraceuser.rst index 82629a6a03..5dad737ab8 100644 --- a/Documentation/guides/tasktraceuser.rst +++ b/Documentation/guides/tasktraceuser.rst @@ -31,7 +31,7 @@ The following configurations must be enabled. - ``CONFIG_SYSTEM_SYSTEM`` : Enables "``system``" command (required by :ref:`trace_cmd`) -The following configurations are configurable parameters for trace. +The following configurations are configurable parameters for trace. - ``CONFIG_SCHED_INSTRUMENTATION_FILTER_DEFAULT_MODE`` diff --git a/Documentation/guides/usbtrace.rst b/Documentation/guides/usbtrace.rst index 31089c125f..0140a7265a 100644 --- a/Documentation/guides/usbtrace.rst +++ b/Documentation/guides/usbtrace.rst @@ -120,16 +120,16 @@ N. USB EVENT ID 8-bit EVENT DATA MEANING NOTES: 1. See include/nuttx/usb/usbdev_trace.h - 2. See arch/arm/src/lpc17xx_40xx/lpc17_40_usbdev.c + 2. See arch/arm/src/lpc17xx_40xx/lpc17_40_usbdev.c In the above example you can see that: - **1**. The serial class USB setup method was called for the USB serial class. This is the corresponds to the following logic in ``drivers/usbdev/pl2303.c``: - + .. code-block:: c - + static int pl2303_setup(FAR struct uart_dev_s *dev) { ... @@ -139,7 +139,7 @@ In the above example you can see that: - **2**. An error occurred while processing the setup command because no configuration has yet been selected by the host. This corresponds to the following logic in ``drivers/usbdev/pl2303.c``: - + .. code-block:: c static int pl2303_setup(FAR struct uart_dev_s *dev) @@ -175,19 +175,19 @@ Device Drivers -> USB Device Driver Support . . (or increase the rate at which the trace buffer is emptied). ``CONFIG_USBDEV_TRACE_STRINGS=y`` Optionally, convert trace ID numbers to strings. . This feature may not be supported by all drivers. -=========================================== =================================================== - -=========================================== =================================================== +=========================================== =================================================== + +=========================================== =================================================== Application Configuration -> NSH LIbrary . ``CONFIG_NSH_USBDEV_TRACE=n`` Make sure that any built-in tracing from NSH is disabled. ``CONFIG_NSH_ARCHINIT=y`` Enable this option only if your board-specific logic . has logic to automatically start the USB monitor. . Otherwise the USB monitor can be started or stopped . with the usbmon_start and usbmon_stop commands from the NSH console. -=========================================== =================================================== - - - +=========================================== =================================================== + + + =============================================== ============================================ Application Configuration -> System NSH Add-Ons . ``CONFIG_USBMONITOR=y`` Enable the USB monitor daemon @@ -201,13 +201,13 @@ Application Configuration -> System NSH Add-Ons . . If you lose buffered USB trace data, then dropping . this value will help by increasing the rate at which . the USB trace buffer is emptied. -``CONFIG_USBMONITOR_TRACEINIT=y`` Selects which USB event(s) that you want to be traced. +``CONFIG_USBMONITOR_TRACEINIT=y`` Selects which USB event(s) that you want to be traced. ``CONFIG_USBMONITOR_TRACECLASS=y`` . ``CONFIG_USBMONITOR_TRACETRANSFERS=y`` . ``CONFIG_USBMONITOR_TRACECONTROLLER=y`` . ``CONFIG_USBMONITOR_TRACEINTERRUPTS=y`` . =============================================== ============================================ - + NOTE: If USB debug output is also enabled, both outputs will appear on the serial console. However, the debug output will be asynchronous with diff --git a/Documentation/index.rst b/Documentation/index.rst index a221e39b8b..eb78d5ab16 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -1,12 +1,12 @@ .. note:: - The present documentation is a recent addition to NuttX and was migrated from previous + The present documentation is a recent addition to NuttX and was migrated from previous documentation content. For this reason, it is possible you may find broken links or formatting errors. You can help contribute fixes or improvements to this documentation by following these :doc:`instructions `. .. tip:: - You can find the old documentation `here `_. - + You can find the old documentation `here `_. + =================== NuttX Documentation =================== @@ -31,5 +31,5 @@ Last Updated: |today| releases/index.rst contributing/index.rst glossary.rst - + .. include:: substitutions.rst diff --git a/Documentation/make.bat b/Documentation/make.bat index 2119f51099..922152e96a 100644 --- a/Documentation/make.bat +++ b/Documentation/make.bat @@ -1,35 +1,35 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=. -set BUILDDIR=_build - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/Documentation/quickstart/compiling.rst b/Documentation/quickstart/compiling.rst index 9d343077e0..94cc5cdd2f 100644 --- a/Documentation/quickstart/compiling.rst +++ b/Documentation/quickstart/compiling.rst @@ -19,7 +19,7 @@ a pre-existing configuration. To list all supported configurations you can do: $ cd nuttx $ ./tools/configure.sh -L | less - + 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 @@ -32,7 +32,7 @@ to ``configure.sh`` and indicate your host platform, such as: $ cd nuttx $ ./tools/configure.sh -l stm32f4discovery:nsh - + The ``-l`` tells use that we're on Linux (macOS and Windows builds are possible). Use the ``-h`` argument to see all available options. @@ -50,7 +50,7 @@ Don't worry about the complexity– you don't have to use most of the options. $ cd nuttx/ $ make menuconfig - + .. todo:: Explain some useful options. @@ -63,18 +63,18 @@ We can now build NuttX. To do so, you can simply run: $ cd nuttx/ $ make make - + The build will complete by generating the binary outputs inside `nuttx` directory. Typically this includes the `nuttx` ELF file (suitable for debugging using `gdb`) and a `nuttx.bin` -file that can be flashed to the board. - +file that can be flashed to the board. + To clean the build, you can do: .. code-block:: console $ make clean - + .. warning:: At the moment it is recommended that after modifying the configuration you first clean before building again. This diff --git a/Documentation/quickstart/index.rst b/Documentation/quickstart/index.rst index a6c6a26870..0a02947303 100644 --- a/Documentation/quickstart/index.rst +++ b/Documentation/quickstart/index.rst @@ -14,7 +14,7 @@ to build NuttX. .. toctree:: :maxdepth: 1 - + quickstart.rst install.rst compiling.rst diff --git a/Documentation/quickstart/install.rst b/Documentation/quickstart/install.rst index d7265e6ee8..c80b14dbe7 100644 --- a/Documentation/quickstart/install.rst +++ b/Documentation/quickstart/install.rst @@ -14,7 +14,7 @@ Prerequisites .. tabs:: .. tab:: Linux - + #. Install system packages .. code-block:: console @@ -63,7 +63,7 @@ Prerequisites gcc-g++ gperf libncurses-devel flex gdb libmpfr-devel git unzip zlib-devel - + To complete the installation of prerequisites, you need to install `kconfig-frontends` as instructed in the :doc:`quickstart` guide. @@ -74,7 +74,7 @@ To build Apache NuttX you need the appropriate toolchain according to your target platform. Some Operating Systems such as Linux distribute toolchains for various architectures. This is usually an easy choice however you should be aware -that in some cases the version offered by your OS may have +that in some cases the version offered by your OS may have problems and it may better to use a widely used build from another source. @@ -84,15 +84,15 @@ ARM architecture: .. tabs:: .. code-tab:: console Ubuntu (deb) - + $ apt install gcc-arm-none-eabi binutils-arm-none-eabi - + .. tab:: From arm.com - + First, create a directory to hold the toolchain: - + .. code-block:: console - + $ usermod -a -G users $USER $ # get a login shell that knows we're in this group: $ su - $USER @@ -100,25 +100,25 @@ ARM architecture: $ sudo chgrp -R users /opt/gcc $ sudo chmod -R u+rw /opt/gcc $ cd /opt/gcc - + Download and extract toolchain: - + .. code-block:: console - + $ HOST_PLATFORM=x86_64-linux # use "mac" for macOS. $ # For windows there is a zip instead (gcc-arm-none-eabi-9-2019-q4-major-win32.zip) $ wget https://developer.arm.com/-/media/Files/downloads/gnu-rm/9-2019q4/gcc-arm-none-eabi-9-2019-q4-major-${HOST_PLATFORM}.tar.bz2 $ tar xf gcc-arm-none-eabi-9-2019-q4-major-${HOST_PLATFORM}.tar.bz2 - + Add the toolchain to your `PATH`: - + .. code-block:: console - + $ echo "export PATH=/opt/gcc/gcc-arm-none-eabi-9-2019-q4-major/bin:$PATH" >> ~/.bashrc - + You can edit your shell's rc files if you don't use bash. -.. tip:: +.. tip:: There are hints on how to get the latest tool chains for most supported architectures in the Apache NuttX CI helper `script `_ @@ -130,7 +130,7 @@ Get Source Code Now that all required tools are installed, you need to download NuttX source-code. .. tabs:: - + .. tab:: Development (Git) Apache NuttX is `actively developed on GitHub `_. @@ -153,7 +153,7 @@ Now that all required tools are installed, you need to download NuttX source-cod # optionally, zipball is also available (for Windows users). .. tab:: Stable Release - + Apache NuttX releases are published on the project `Downloads `_ page and distributed by the Apache mirrors. Be sure to download both the `nuttx` and `apps` tarballs. diff --git a/Documentation/quickstart/quickstart.rst b/Documentation/quickstart/quickstart.rst index 734a585e6b..3b5301afa9 100644 --- a/Documentation/quickstart/quickstart.rst +++ b/Documentation/quickstart/quickstart.rst @@ -53,7 +53,7 @@ computer, you're using an ARM microcontroller on your embedded board, and you're NuttX is configured using ``kconfig`` system via an interactive menu system (``menuconfig``). It also includes the ``kconfig-tweak`` utility that can be used to quickly change debug settings without going into the menu system. .. tabs:: - + .. code-tab:: console Ubuntu 20.04 LTS and later $ apt install kconfig-frontends @@ -91,7 +91,7 @@ computer, you're using an ARM microcontroller on your embedded board, and you're $ ./tools/configure.sh -l : # for instance: $ ./tools/configure.sh -l sama5d27-xult:nsh - + #. Customize Your Configuration (Optional) This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change @@ -104,7 +104,7 @@ computer, you're using an ARM microcontroller on your embedded board, and you're $ make menuconfig Use your arrows to navigate the menu and :kbd:`Enter` key to enable/disable options. To exit and save your configuration, go back to the main menu, choose ```` and select "yes" when asked if you want to save. - + #. Compile Apache NuttX .. code-block:: bash diff --git a/Documentation/quickstart/running.rst b/Documentation/quickstart/running.rst index 4ef05ce18c..4bc59b225c 100644 --- a/Documentation/quickstart/running.rst +++ b/Documentation/quickstart/running.rst @@ -21,14 +21,14 @@ Flashing There are various tools you can use to flash the NuttX binary to your Nucleo board. One common option is to use `openocd` which supports a large number -of programmers and target microcontrollers. +of programmers and target microcontrollers. To install the stable version of openocd you can do: .. code-block:: console $ apt install openocd - + .. todo:: add instructions for other platforms You should note that openocd project has not made stable releases for long @@ -42,7 +42,7 @@ latest Git version. To install it you should: $ ./bootstrap $ ./configure --prefix install/ $ make install - + The resulting installation will be under ``openocd/install``. You can add ``openocd/install/bin`` to your ``PATH``. @@ -53,7 +53,7 @@ Now, to flash the binary to your board, connect the USB cable and do: $ cd nuttx/ $ openocd -f interface/st-link-v2.cfg -f target/stm32f1x.cfg -c 'init' \ -c 'program nuttx/nuttx.bin verify reset' -c 'shutdown' - + Access NuttShell ================ @@ -64,13 +64,13 @@ of your choice where you will see the ``nsh>`` prompt: .. tabs:: .. code-tab:: console picocom (CLI) - + $ picocom -b 115200 /dev/ttyUSB0 - + .. code-tab:: console gtkterm (GUI) - + $ gtkterm -s 115200 -p /dev/ttyUSB0 - + Debugging ========= @@ -80,20 +80,20 @@ Using ``openocd`` you can also debug NuttX. To do so, first run: .. code-block:: console $ openocd -f interface/st-link-v2.cfg -f target/stm32f1x.cfg - + which will start a GDB server. Then, start ``gdb`` as: .. code-block:: console $ cd nuttx/ $ gdb-multiarch nuttx/nuttx - + Inside ``gdb`` console, connect to the ``openocd`` server with: .. code-block:: (gdb) target extended-remote :3333 - + You can debug using standard ``gdb`` commands. Advanced Debugging with JTAG diff --git a/Documentation/reference/os/addrenv.rst b/Documentation/reference/os/addrenv.rst index 112cde0b5b..fe3625f2c5 100644 --- a/Documentation/reference/os/addrenv.rst +++ b/Documentation/reference/os/addrenv.rst @@ -1,6 +1,6 @@ ==================== Address Environments -==================== +==================== CPUs that support memory management units (MMUs) may provide *address environments* within which tasks and their child threads @@ -93,7 +93,7 @@ The CPU-specific logic must provide two categories in interfaces: This function is called when a new task is created in order to instantiate an address environment for the new task group. - up_addrenv_create() is essentially the allocator of the physical memory for the new task. + up_addrenv_create() is essentially the allocator of the physical memory for the new task. :param textsize: The size (in bytes) of the ``.text`` address environment needed by the task. This region may be read/execute @@ -125,19 +125,19 @@ The CPU-specific logic must provide two categories in interfaces: Return the virtual .text address associated with the newly create address environment. This function is used by the binary loaders - in order get an address that can be used to initialize the new task. + in order get an address that can be used to initialize the new task. :param addrenv: The representation of the task address environment previously returned by ``up_addrenv_create()``. :param vtext: The location to return the virtual address. - :return: Zero (OK) on success; a negated errno value on failure. + :return: Zero (OK) on success; a negated errno value on failure. .. c:function:: int up_addrenv_vdata(FAR group_addrenv_t *addrenv, size_t textsize, FAR void **vdata) Return the virtual .text address associated with the newly create address environment. This function is used by the binary loaders - in order get an address that can be used to initialize the new task. + in order get an address that can be used to initialize the new task. :param addrenv: The representation of the task address environment previously returned by ``up_addrenv_create()``. @@ -147,28 +147,28 @@ The CPU-specific logic must provide two categories in interfaces: offset into the common region. :param vdata: The location to return the virtual address. - :return: Zero (OK) on success; a negated errno value on failure. + :return: Zero (OK) on success; a negated errno value on failure. .. c:function:: ssize_t up_addrenv_heapsize(FAR const group_addrenv_t *addrenv) Return the initial heap allocation size. That is the amount of memory allocated by up_addrenv_create() when the heap memory region was first created. This may or may not differ from the - heapsize parameter that was passed to up_addrenv_create(). + heapsize parameter that was passed to up_addrenv_create(). :param addrenv: The representation of the task address environment previously returned by ``up_addrenv_create()``. :return: The initial heap size allocated is returned on success; - a negated errno value on failure. + a negated errno value on failure. .. c:function:: int up_addrenv_select(group_addrenv_t *addrenv, save_addrenv_t *oldenv) - After an address environment has been established for a task + After an address environment has been established for a task (via up_addrenv_create()), this function may be called to instantiate that address environment in the virtual address space. This might be necessary, for example, to load the code for the task from a file or - to access address environment private data. + to access address environment private data. :param addrenv: The representation of the task address environment previously returned by ``up_addrenv_create()``. @@ -180,13 +180,13 @@ The CPU-specific logic must provide two categories in interfaces: platform-specific representation that may or may not be different from ``group_addrenv_t``. - :return: Zero (OK) on success; a negated errno value on failure. + :return: Zero (OK) on success; a negated errno value on failure. .. c:function:: int up_addrenv_restore(save_addrenv_t oldenv) After an address environment has been temporarily instantiated by up_addrenv_select, this function may be called to restore - the original address environment. + the original address environment. :param oldenv: The platform-specific representation of the address environment previously returned by ``up_addrenv_select()``. @@ -197,13 +197,13 @@ The CPU-specific logic must provide two categories in interfaces: Duplicate an address environment. This does not copy the underlying memory, only the representation that can be used to instantiate - that memory as an address environment. + that memory as an address environment. :param src: The address environment to be copied. :param dest: The location to receive the copied address environment. - :return: Zero (OK) on success; a negated errno value on failure. + :return: Zero (OK) on success; a negated errno value on failure. .. c:function:: int up_addrenv_attach(FAR struct task_group_s *group, FAR struct tcb_s *tcb) @@ -220,7 +220,7 @@ The CPU-specific logic must provide two categories in interfaces: :param ctcb: The TCB of the thread needing the address environment. - :return: Zero (OK) on success; a negated errno value on failure. + :return: Zero (OK) on success; a negated errno value on failure. .. c:function:: int up_addrenv_detach(FAR struct task_group_s *group, FAR struct task_group_s *tcb) @@ -228,17 +228,17 @@ The CPU-specific logic must provide two categories in interfaces: to release its reference to an address environment. The address environment, however, should persist until up_addrenv_destroy() is called when the task group is itself destroyed. Any resources - unique to this thread may be destroyed now. + unique to this thread may be destroyed now. :param group: The group to which the thread belonged. :param tcb: The TCB of the task or thread whose the address environment will be released. - :return: Zero (OK) on success; a negated errno value on failure. + :return: Zero (OK) on success; a negated errno value on failure. .. c:function:: int up_addrenv_ustackalloc(FAR struct tcb_s *tcb, size_t stacksize) - This function is called when a new thread is created in order + This function is called when a new thread is created in order to instantiate an address environment for the new thread's stack. up_addrenv_ustackalloc() is essentially the allocator of the physical memory for the new task's stack. @@ -249,13 +249,13 @@ The CPU-specific logic must provide two categories in interfaces: environment needed by the task. This region may be read/write only. - :return: Zero (OK) on success; a negated errno value on failure. + :return: Zero (OK) on success; a negated errno value on failure. .. c:function:: int up_addrenv_ustackfree(FAR struct tcb_s *tcb) This function is called when any thread exits. This function then destroys the defunct address environment for the thread's stack, - releasing the underlying physical memory. + releasing the underlying physical memory. :param tcb: The TCB of the thread that no longer requires the stack address environment. @@ -269,7 +269,7 @@ The CPU-specific logic must provide two categories in interfaces: :param tcb: The TCB of the thread with the stack address environment of interest. :param vstack: The location to return the stack virtual base address. - :return: Zero (OK) on success; a negated errno value on failure. + :return: Zero (OK) on success; a negated errno value on failure. .. c:function:: int up_addrenv_ustackselect(FAR const struct tcb_s *tcb) @@ -289,7 +289,7 @@ The CPU-specific logic must provide two categories in interfaces: This function is called when a new thread is created to allocate the new thread's kernel stack. This function may be called for certain terminating threads which have no kernel stack. It must be - tolerant of that case. + tolerant of that case. :param tcb: The TCB of the thread that requires the kernel stack. @@ -297,9 +297,9 @@ The CPU-specific logic must provide two categories in interfaces: .. c:function:: int up_addrenv_kstackfree(FAR struct tcb_s *tcb); - This function is called when any thread exits. This function frees the kernel stack. + This function is called when any thread exits. This function frees the kernel stack. :param tcb: The TCB of the thread that no longer requires the kernel stack. - :return: Zero (OK) on success; a negated errno value on failure. + :return: Zero (OK) on success; a negated errno value on failure. diff --git a/Documentation/reference/os/boardctl.rst b/Documentation/reference/os/boardctl.rst index 4ac9886d73..d3b81f5a2c 100644 --- a/Documentation/reference/os/boardctl.rst +++ b/Documentation/reference/os/boardctl.rst @@ -36,5 +36,5 @@ of the argument is determined by the specific command. :return: On success zero (OK) is returned; -1 (ERROR) is - returned on failure with the errno variable set to indicate the nature of the failure. + returned on failure with the errno variable set to indicate the nature of the failure. diff --git a/Documentation/reference/os/iob.rst b/Documentation/reference/os/iob.rst index 3f4f3b2c5a..c4d9e46dfe 100644 --- a/Documentation/reference/os/iob.rst +++ b/Documentation/reference/os/iob.rst @@ -29,10 +29,10 @@ networking subsystem. This objectives of this feature are: Configuration Options ===================== -``CONFIG_MM_IOB`` +``CONFIG_MM_IOB`` Enables generic I/O buffer support. This setting will build the common I/O buffer (IOB) support library. -``CONFIG_IOB_NBUFFERS`` +``CONFIG_IOB_NBUFFERS`` Number of pre-allocated I/O buffers. Each packet is represented by a series of small I/O buffers in a chain. This setting determines the number of preallocated I/O buffers available for @@ -41,12 +41,12 @@ Configuration Options is enabled (neither ``CONFIG_NET_TCP_WRITE_BUFFERS`` nor ``CONFIG_NET_TCP``), 24 if only TCP/UDP is enabled, and 36 if both TCP/UDP and write buffering are enabled. -``CONFIG_IOB_BUFSIZE`` +``CONFIG_IOB_BUFSIZE`` Payload size of one I/O buffer. Each packet is represented by a series of small I/O buffers in a chain. This setting determines the data payload each preallocated I/O buffer. The default value is 196 bytes. -``CONFIG_IOB_NCHAINS`` +``CONFIG_IOB_NCHAINS`` Number of pre-allocated I/O buffer chain heads. These tiny nodes are used as *containers* to support queueing of I/O buffer chains. This will limit the number of I/O transactions @@ -59,7 +59,7 @@ Configuration Options zero if nether TCP nor UDP is enabled (i.e., neither ``CONFIG_NET_TCP`` && !\ ``CONFIG_NET_UDP`` or eight if either is enabled. -``CONFIG_IOB_THROTTLE`` +``CONFIG_IOB_THROTTLE`` I/O buffer throttle value. TCP write buffering and read-ahead buffer use the same pool of free I/O buffers. In order to prevent uncontrolled incoming TCP packets from hogging all of @@ -68,7 +68,7 @@ Configuration Options denied to the read-ahead logic before TCP writes are halted. The default 0 if neither TCP write buffering nor TCP read-ahead buffering is enabled. Otherwise, the default is 8. -``CONFIG_IOB_DEBUG`` +``CONFIG_IOB_DEBUG`` Force I/O buffer debug. This option will force debug output from I/O buffer logic. This is not normally something that would want to do but is convenient if you are debugging the I/O diff --git a/Documentation/reference/os/led.rst b/Documentation/reference/os/led.rst index f8d443545d..eaa4502c17 100644 --- a/Documentation/reference/os/led.rst +++ b/Documentation/reference/os/led.rst @@ -108,13 +108,13 @@ The ``include/nuttx/board.h`` includes the following declarations: interfaces (such as ``stm32_led_initialize()``). .. c:function:: void board_autoled_on(int led) - + Called to instantiate the LED presentation of the event. The ``led`` argument is one of the definitions provided in ``/include/board.h``. .. c:function:: void board_autoled_off(int led) - + Called to terminate the LED presentation of the event. The ``led`` argument is one of the definitions provided in ``/include/board.h``. Note diff --git a/Documentation/reference/os/note.rst b/Documentation/reference/os/note.rst index 1ce84983bf..cd2e942cf1 100644 --- a/Documentation/reference/os/note.rst +++ b/Documentation/reference/os/note.rst @@ -33,21 +33,21 @@ Notectl Device (``/dev/notectl``) unsigned int flag; /* Filter mode flag */ #ifdef CONFIG_SMP unsigned int cpuset; /* The set of monitored CPUs */ - #endif + #endif }; - ``flag`` : Filter mode flag. The bitwise OR of the following defines are available. .. c:macro:: NOTE_FILTER_MODE_FLAG_ENABLE - + Enable instrumentation .. c:macro:: NOTE_FILTER_MODE_FLAG_SYSCALL - + Enable syscall instrumentation .. c:macro:: NOTE_FILTER_MODE_FLAG_IRQ - + Enable IRQ instrumentaiton - ``cpuset`` : (SMP only) Monitor only CPUs in the bitset. Bit 0=CPU0, Bit1=CPU1, etc. @@ -199,7 +199,7 @@ Noteram Device (``/dev/note``) The overwrite mode takes one of the following values. .. c:macro:: NOTERAM_MODE_OVERWRITE_DISABLE - + Overwrite mode is disabled. When the buffer is full, accepting the data will be stopped. .. c:macro:: NOTERAM_MODE_OVERWRITE_ENABLE diff --git a/Documentation/reference/os/nuttx.rst b/Documentation/reference/os/nuttx.rst index 2020583e40..8651d00a7d 100644 --- a/Documentation/reference/os/nuttx.rst +++ b/Documentation/reference/os/nuttx.rst @@ -30,7 +30,7 @@ OS List Management APIs the tick-less OS expires. **Assumptions**: Base code implementation assumes that this - function is called from interrupt handling logic with interrupts disabled. + function is called from interrupt handling logic with interrupts disabled. .. c:function:: void nxsched_alarm_expiration(void); @@ -40,7 +40,7 @@ OS List Management APIs the tick-less OS expires. **Assumptions**: Base code implementation assumes that this - function is called from interrupt handling logic with interrupts disabled. + function is called from interrupt handling logic with interrupts disabled. .. c:function:: void irq_dispatch(int irq, FAR void *context) diff --git a/Documentation/reference/os/shm.rst b/Documentation/reference/os/shm.rst index 339539f2aa..334825e10f 100644 --- a/Documentation/reference/os/shm.rst +++ b/Documentation/reference/os/shm.rst @@ -14,7 +14,7 @@ below: .. c:function:: int up_shmat(FAR uintptr_t *pages, unsigned int npages, uintptr_t vaddr) - Attach, i.e, map, on shared memory region to a user virtual address. + Attach, i.e, map, on shared memory region to a user virtual address. :param pages: A pointer to the first element in a array of physical address, each corresponding to one page of memory. @@ -23,16 +23,16 @@ below: :param vaddr: The virtual address corresponding to the beginning of the (contiguous) virtual address region. - :return: Zero (OK) is returned on success; a negated errno value is returned on failure. + :return: Zero (OK) is returned on success; a negated errno value is returned on failure. .. c:function:: int up_shmdt(uintptr_t vaddr, unsigned int npages) - Detach, i.e, unmap, on shared memory region from a user virtual address. + Detach, i.e, unmap, on shared memory region from a user virtual address. :param vaddr: The virtual address corresponding to the beginning of the (contiguous) virtual address region. :param npages: T The number of pages to be unmapped. - :return: Zero (OK) is returned on success; a negated errno value is returned on failure. + :return: Zero (OK) is returned on success; a negated errno value is returned on failure. diff --git a/Documentation/reference/os/smp.rst b/Documentation/reference/os/smp.rst index 505923144e..a4ae791366 100644 --- a/Documentation/reference/os/smp.rst +++ b/Documentation/reference/os/smp.rst @@ -26,7 +26,7 @@ Page `__. .. c:function:: spinlock_t up_testset(volatile FAR spinlock_t *lock) - Perform and atomic test and set operation on the provided spinlock. + Perform and atomic test and set operation on the provided spinlock. :param lock: The address of spinlock object. @@ -35,16 +35,16 @@ Page `__. either SP_LOCKED if the spinlock was previously locked (meaning that the test-and-set operation failed to obtain the lock) or SP_UNLOCKED if the spinlock was previously unlocked - (meaning that we successfully obtained the lock) + (meaning that we successfully obtained the lock) .. c:function:: int up_cpu_index(void) Return an index in the range of 0 through (CONFIG_SMP_NCPUS-1) - that corresponds to the currently executing CPU. + that corresponds to the currently executing CPU. :return: An integer index in the range of 0 through (CONFIG_SMP_NCPUS-1) that corresponds to the - currently executing CPU. + currently executing CPU. .. c:function:: int up_cpu_start(int cpu) @@ -66,7 +66,7 @@ Page `__. numeric value in the range of from one to ``(CONFIG_SMP_NCPUS-1)``). (CPU 0 is already active). - :return: Zero (OK) is returned on success; a negated errno value on failure. + :return: Zero (OK) is returned on success; a negated errno value on failure. .. c:function:: int up_cpu_pause(int cpu) @@ -84,7 +84,7 @@ Page `__. .. c:function:: int up_cpu_resume(int cpu) - Restart the cpu after it was paused via up_cpu_pause(), + Restart the cpu after it was paused via up_cpu_pause(), restoring the state of the task at the head of the ``g_assignedtasks[cpu]`` list, and resume normal tasking. @@ -95,5 +95,5 @@ Page `__. :param cpu: The index of the CPU being resumed. This will not be the index of the currently executing CPU. - :return: Zero (OK) is returned on success; a negated errno value on failure. + :return: Zero (OK) is returned on success; a negated errno value on failure. diff --git a/Documentation/reference/os/time_clock.rst b/Documentation/reference/os/time_clock.rst index 3892825ea0..09be335fc6 100644 --- a/Documentation/reference/os/time_clock.rst +++ b/Documentation/reference/os/time_clock.rst @@ -56,9 +56,9 @@ run. Consider this example implementation: #. Initially an accumulator is zero an the match value is programmed to 328: - + .. code-block:: c - + accumulator = 0; match = 328; @@ -66,9 +66,9 @@ run. Consider this example implementation: that, in this reflects, 100\* the error in interval that just passed. So on the first timer interrupt, the accumulator would be updated like: - + .. code-block:: c - + if (match == 328) { accumulator += 32; // 100*(328 - 327.68) @@ -76,13 +76,13 @@ run. Consider this example implementation: else { accumulator -= 68; // (100*(327 - 327.68) - } + } #. And on that same timer interrupt a new match value would be programmed: - + .. code-block:: c - + if (accumulator < 0) { match = 328; @@ -91,7 +91,7 @@ run. Consider this example implementation: { match = 327; } - + In this way, the timer interval is controlled from interrupt-to-interrupt to produce an average frequency of exactly 100Hz. @@ -101,10 +101,10 @@ Hardware To enable hardware module use the following configuration options: -``CONFIG_RTC`` +``CONFIG_RTC`` Enables general support for a hardware RTC. Specific architectures may require other specific settings. -``CONFIG_RTC_EXTERNAL`` +``CONFIG_RTC_EXTERNAL`` Most MCUs include RTC hardware built into the chip. Other RTCs, *external* MCUs, may be provided as separate chips typically interfacing with the MCU via a serial interface such as SPI or @@ -113,7 +113,7 @@ To enable hardware module use the following configuration options: booted and can support the required serial communications. ``CONFIG_RTC_EXTERNAL`` will configure the operating system so that it defers initialization of its time facilities. -``CONFIG_RTC_DATETIME`` +``CONFIG_RTC_DATETIME`` There are two general types of RTC: (1) A simple battery backed counter that keeps the time when power is down, and (2) A full date / time RTC the provides the date and time information, @@ -121,7 +121,7 @@ To enable hardware module use the following configuration options: specifies this second kind of RTC. In this case, the RTC is used to "seed"" the normal NuttX timer and the NuttX system timer provides for higher resolution time. -``CONFIG_RTC_HIRES`` +``CONFIG_RTC_HIRES`` If ``CONFIG_RTC_DATETIME`` not selected, then the simple, battery backed counter is used. There are two different implementations of such simple counters based on the time @@ -132,11 +132,11 @@ To enable hardware module use the following configuration options: If ``CONFIG_RTC_HIRES`` is enabled in the NuttX configuration, then the RTC provides higher resolution time and completely replaces the system timer for purpose of date and time. -``CONFIG_RTC_FREQUENCY`` +``CONFIG_RTC_FREQUENCY`` If ``CONFIG_RTC_HIRES`` is defined, then the frequency of the high resolution RTC must be provided. If ``CONFIG_RTC_HIRES`` is not defined, ``CONFIG_RTC_FREQUENCY`` is assumed to be one. -``CONFIG_RTC_ALARM`` +``CONFIG_RTC_ALARM`` Enable if the RTC hardware supports setting of an alarm. A callback function will be executed when the alarm goes off @@ -377,9 +377,9 @@ timer implementation: On return, the current up-time should be available from up_timer_gettime() and the interval timer is ready for use (but not actively timing). The naming will depend on the architecture so for STM32 ``archname`` will - be ``stm32``. + be ``stm32``. - :return: Zero (OK) on success; a negated errno value on failure. + :return: Zero (OK) on success; a negated errno value on failure. **Assumptions**: Called early in the initialization sequence before any special concurrency protections are required. @@ -395,12 +395,12 @@ timer implementation: :param ts: Provides the location in which to return the up-time.. - :return: Zero (OK) on success; a negated errno value on failure. + :return: Zero (OK) on success; a negated errno value on failure. **Assumptions**: Called from the normal tasking context. The implementation must provide whatever mutual exclusion is necessary for correct operation. This can include disabling interrupts in - order to assure atomic register operations. + order to assure atomic register operations. .. c:function:: int up_alarm_cancel(FAR struct timespec *ts) @@ -415,11 +415,11 @@ timer implementation: time should be returned if the timer is not active. ``ts`` may be ``NULL`` in which case the time is not returned - :return: Zero (OK) on success; a negated errno value on failure. + :return: Zero (OK) on success; a negated errno value on failure. **Assumptions**: May be called from interrupt level handling or from the normal tasking level. interrupts may need to be disabled - internally to assure non-reentrancy. + internally to assure non-reentrancy. .. c:function:: int up_alarm_start(FAR const struct timespec *ts) @@ -431,11 +431,11 @@ timer implementation: occur. When the alarm occurs the timer logic will call ``nxsched_timer_expiration()``. - :return: Zero (OK) on success; a negated errno value on failure. + :return: Zero (OK) on success; a negated errno value on failure. **Assumptions**: May be called from interrupt level handling or from the normal tasking level. Interrupts may need to be - disabled internally to assure non-reentrancy. + disabled internally to assure non-reentrancy. .. c:function:: int up_timer_cancel(FAR struct timespec *ts) @@ -451,11 +451,11 @@ remaining time of zero should be returned. :param ts: Location to return the remaining time. Zero should be returned if the timer is not active. -:return: Zero (OK) on success; a negated errno value on failure. +:return: Zero (OK) on success; a negated errno value on failure. **Assumptions**: May be called from interrupt level handling or -from the normal tasking level. interrupts may need to be -disabled internally to assure non-reentrancy. +from the normal tasking level. interrupts may need to be +disabled internally to assure non-reentrancy. .. c:function:: int up_timer_start(FAR const struct timespec *ts) @@ -466,11 +466,11 @@ called at the completion of the timeout (unless :param ts: Provides the time interval until ``nxsched_timer_expiration()`` is called. -:return: Zero (OK) on success; a negated errno value on failure. +:return: Zero (OK) on success; a negated errno value on failure. **Assumptions**: May be called from interrupt level handling or from the normal tasking level. Interrupts may need to be -disabled internally to assure non-reentrancy. +disabled internally to assure non-reentrancy. Watchdog Timer Interfaces ========================= @@ -562,18 +562,18 @@ with NuttX tasks. watchdog time expires. Zero means either that wdog is not valid or that the wdog has already expired. -.. c:type:: void (*wdentry_t)(wdparm_t arg) +.. c:type:: void (*wdentry_t)(wdparm_t arg) **Watchdog Timer Callback**: when a watchdog expires, the callback function with this type is called. - + The argument is passed as scalar ``wdparm_t`` values. For systems where the ``sizeof(pointer) < sizeof(uint32_t)``, the following union defines the alignment of the pointer within the ``uint32_t``. For example, the SDCC MCS51 general pointer is 24-bits, but ``uint32_t`` is 32-bits (of course). - + We always have ``sizeof(pointer) <= sizeof(uintptr_t)`` by definition. diff --git a/Documentation/reference/os/wqueue.rst b/Documentation/reference/os/wqueue.rst index 5749234ac7..d22291bdb3 100644 --- a/Documentation/reference/os/wqueue.rst +++ b/Documentation/reference/os/wqueue.rst @@ -237,7 +237,7 @@ Work Queue Interfaces until the worker is invoked. Zero means to perform the work immediately. - :return: Zero is returned on success; a negated errno is returned on failure. + :return: Zero is returned on success; a negated errno is returned on failure. .. c:function:: int work_cancel(int qid, FAR struct work_s *work) @@ -263,15 +263,15 @@ Work Queue Interfaces :param qid: The work queue ID. - :return: Zero is returned on success; a negated errno is returned on failure. + :return: Zero is returned on success; a negated errno is returned on failure. .. c:function:: bool work_available(FAR struct work_s *work) - Check if the work structure is available. - + Check if the work structure is available. + :param work: The work queue structure to check. - :return: ``true`` if available; ``false`` if busy (i.e., there is still pending work). + :return: ``true`` if available; ``false`` if busy (i.e., there is still pending work). .. c:function:: int work_usrstart(void) @@ -285,7 +285,7 @@ Work Queue Interfaces :return: The task ID of the worker thread is returned on success. A negated ``errno`` value is returned on failure. - + .. c:function:: void lpwork_boostpriority(uint8_t reqprio) Called by the work queue client to assure that diff --git a/Documentation/reference/user/01_task_control.rst b/Documentation/reference/user/01_task_control.rst index 6e47244613..f0deda4684 100644 --- a/Documentation/reference/user/01_task_control.rst +++ b/Documentation/reference/user/01_task_control.rst @@ -90,12 +90,12 @@ Non-standard task control interfaces inspired by ``posix_spawn``: - :c:func:`task_spawnattr_getstacksize` - :c:func:`task_spawnattr_setstacksize` - :c:func:`posix_spawn_file_actions_init` - + Functions --------- .. c:function:: int task_create(char *name, int priority, int stack_size, main_t entry, char * const argv[]) - + This function creates and activates a new task with a specified priority and returns its system-assigned ID. @@ -127,16 +127,16 @@ Functions :param argv: A pointer to an array of input parameters. The array should be terminated with a NULL argv[] value. If no parameters are required, argv may be NULL. - + :return: the non-zero task ID of the new task or ERROR if memory is insufficient or the task cannot be created (```errno`` <#ErrnoAccess>`__ is not set). **Defined in:** ``sched.h`` - + **POSIX Compatibility:** This is a NON-POSIX interface. VxWorks provides the following similar interface: - + .. code-block:: c int taskSpawn(char *name, int priority, int options, int stackSize, FUNCPTR entryPt, @@ -240,7 +240,7 @@ Functions - Restart of the currently running task is not supported by NuttX. - The VxWorks description says that the ID, priority, etc. take the value that they had when the task was *terminated*. - + .. c:function:: int task_setcancelstate(int state, int *oldstate) This function atomically sets @@ -305,7 +305,7 @@ Functions the functionality of ``pthread_testcancel()`` to tasks and supports use of ``task_delete()``. -.. c:function:: void exit(int code) +.. c:function:: void exit(int code) .. c:function:: void _exit(int code) .. #include @@ -793,7 +793,7 @@ Functions FAR const posix_spawn_file_actions_t *file_actions, \ FAR const posix_spawnattr_t *attr, \ FAR char * const argv[], FAR char * const envp[]) - + The ``task_spawn()`` function will create a new, child task, where the entry point to the task is an address in memory. diff --git a/Documentation/reference/user/02_task_scheduling.rst b/Documentation/reference/user/02_task_scheduling.rst index 004ea59fe8..6ccb7c4fbd 100644 --- a/Documentation/reference/user/02_task_scheduling.rst +++ b/Documentation/reference/user/02_task_scheduling.rst @@ -55,13 +55,13 @@ Functions name. Differences from the full POSIX implementation include: - The range of priority values for the POSIX call is 0 to 255. - + .. note:: Setting a task's priority to the same value has the similar effect to ``sched_yield()``: The task will be moved to after all other tasks - with the same priority. + with the same priority. .. c:function:: int sched_getparam(pid_t pid, FAR struct sched_param *param) - + This function gets the scheduling priority of the task specified by pid. diff --git a/Documentation/reference/user/03_task_control.rst b/Documentation/reference/user/03_task_control.rst index 0fac316586..85f1358263 100644 --- a/Documentation/reference/user/03_task_control.rst +++ b/Documentation/reference/user/03_task_control.rst @@ -26,11 +26,11 @@ Task Control Interfaces within the task group. Members of a task group share certain resources such as environment variables, file descriptors, ``FILE`` streams, sockets, pthread keys and open message queues. - + - :c:func:`atexit` - :c:func:`on_exit` - - .. note:: + + .. note:: Behavior of features related to task group's depend of NuttX configuration settings. See the discussion of "Parent and Child Tasks," below. See also the\ `NuttX @@ -132,9 +132,9 @@ Functions **POSIX Compatibility:** This is a NON-POSIX interface. VxWorks provides the comparable interface: - + .. code-block:: c - + STATUS taskLock(void); .. c:function:: int sched_unlock(void) @@ -147,10 +147,10 @@ Functions task will execute. :return: OK or ERROR. - + **POSIX Compatibility:** This is a NON-POSIX interface. VxWorks provides the comparable interface: - + .. code-block:: c STATUS taskUnlock(void); @@ -168,7 +168,7 @@ Functions .. c:function:: ipid_t waitpid(pid_t pid, int *stat_loc, int options) - .. note:: + .. note:: The following discussion is a general description of the ``waitpid()`` interface. However, as of this writing, the implementation of ``waitpid()`` is incomplete (but usable). If @@ -363,7 +363,7 @@ Functions the structure pointed to by ``info`` will be filled in by the system with the status of the process. The ``si_signo`` member will always be equal to ``SIGCHLD``. - + :return: If ``waitid()`` returns due to the change of state of one of its children, 0 is returned. Otherwise, -1 is returned and ``errno`` is set to indicate the error. diff --git a/Documentation/reference/user/05_counting_semaphore.rst b/Documentation/reference/user/05_counting_semaphore.rst index 8be699d507..3f940e7a66 100644 --- a/Documentation/reference/user/05_counting_semaphore.rst +++ b/Documentation/reference/user/05_counting_semaphore.rst @@ -308,7 +308,7 @@ page `__ with a NULL ``from`` parameter. diff --git a/Documentation/reference/user/12_shared_memory.rst b/Documentation/reference/user/12_shared_memory.rst index 31f1b13d2f..ee1eafdef7 100644 --- a/Documentation/reference/user/12_shared_memory.rst +++ b/Documentation/reference/user/12_shared_memory.rst @@ -10,7 +10,7 @@ memory interfaces: - :c:func:`shmat` - :c:func:`shmctl` - :c:func:`shmdt` - + Functions --------- @@ -83,7 +83,7 @@ Functions because user and group IDs are not yet supported by NuttX. .. c:function:: void *shmat(int shmid, FAR const void *shmaddr, int shmflg) - + Attaches the shared memory segment associated with the shared memory identifier specified by ``shmid`` to the address space of the calling process. The segment is @@ -199,4 +199,4 @@ Functions - ``EINVAL``. The value of ``shmaddr`` is not the data segment start address of a shared memory segment. - + diff --git a/Documentation/reference/user/index.rst b/Documentation/reference/user/index.rst index de648f2b49..b6f37744ee 100644 --- a/Documentation/reference/user/index.rst +++ b/Documentation/reference/user/index.rst @@ -23,6 +23,6 @@ Porting Guide `__. :maxdepth: 1 :caption: Contents :glob: - + *_* structures.rst diff --git a/Documentation/reference/user/structures.rst b/Documentation/reference/user/structures.rst index ef05ee6273..f291cc1e52 100644 --- a/Documentation/reference/user/structures.rst +++ b/Documentation/reference/user/structures.rst @@ -38,8 +38,8 @@ Access to the ``errno`` Variable A pointer to the thread-specific ``errno`` value is available through a function call: -.. c:function:: int *__errno(void) - +.. c:function:: int *__errno(void) + ``__errno()`` returns a pointer to the thread-specific ``errno`` value. Note that the symbol ``errno`` is defined to be ``__errno()`` so that the usual access by referencing the symbol @@ -66,7 +66,7 @@ User Interface Structures .. c:type:: int (*main_t)(int argc, char *argv[]) :c:type:`main_t` defines the type of a task entry point. :c:type:`main_t` is declared in -``sys/types.h``. +``sys/types.h``. .. c:struct:: sched_param diff --git a/Documentation/releases/index.rst b/Documentation/releases/index.rst index e83e335c80..005b06f9d8 100644 --- a/Documentation/releases/index.rst +++ b/Documentation/releases/index.rst @@ -1,6 +1,6 @@ Releases ======== -.. todo:: +.. todo:: This should link (or include?) release notes. Maybe only show some recent ones and link older ones