Customizing NSH Initialization

Ways to Customize NSH Initialization. There are three ways to customize the NSH start-up behavior. Here they are presented in order of increasing difficulty:

  1. You can extend the initialization logic in boards/arm/stm32/stm3240g-eval/src/stm32_appinit.c. The logic there is called each time that NSH is started and is good place in particular for any device-related initialization.

  2. You replace the sample code at apps/examples/nsh/nsh_main.c with whatever start-up logic that you want. NSH is a library at apps/nshlib. apps.examples/nsh is just a tiny, example start-up function (CONFIG_USER_ENTRYPOINT()) that that runs immediately and illustrates how to start NSH If you want something else to run immediately then you can write your write your own custom CONFIG_USER_ENTRYPOINT() function and then start other tasks from your custom CONFIG_USER_ENTRYPOINT().

  3. NSH also supports a start-up script that executed when NSH first runs. This mechanism has the advantage that the start-up script can contain any NSH commands and so can do a lot of work with very little coding. The disadvantage is that is is considerably more complex to create the start-up script. It is sufficiently complex that is deserves its own paragraph

NuttShell Start up Scripts

First of all you should look at NSH Start-Up Script paragraph. Most everything you need to know can be found there. That information will be repeated and extended here for completeness.

NSH Start-Up Script. NSH supports options to provide a start up script for NSH. The start-up script contains any command support by NSH (i.e., that you see when you enter ‘nsh> help’). In general this capability is enabled with CONFIG_NSH_ROMFSETC=y, but has several other related configuration options as described with the NSH-specific configuration settings paragraph. This capability also depends on:

  • CONFIG_DISABLE_MOUNTPOINT=n. If mount point support is disabled, then you cannot mount any file systems.

  • CONFIG_NFILE_DESCRIPTORS > 4. Of course you have to have file descriptions to use any thing in the file system.

  • CONFIG_FS_ROMFS enabled. This option enables ROMFS file system support.

Default Start-Up Behavior. The implementation that is provided is intended to provide great flexibility for the use of Start-Up files. This paragraph will discuss the general behavior when all of the configuration options are set to the default values.

In this default case, enabling CONFIG_NSH_ROMFSETC will cause NSH to behave as follows at NSH start-up time:

  • NSH will create a read-only RAM disk (a ROM disk), containing a tiny ROMFS file system containing the following:

    `--init.d/
    `-- rcS

    Where rcS is the NSH start-up script.

  • NSH will then mount the ROMFS file system at /etc, resulting in:

    |--dev/
|   `-- ram0
`--etc/
    `--init.d/
        `-- rcS

  • By default, the contents of rcS script are:

    # Create a RAMDISK and mount it at /tmp

mkrd -m 1 -s 512 1024
mkfatfs /dev/ram1
mount -t vfat /dev/ram1 /tmp

  • NSH will execute the script at /etc/init.d/rcS at start-up (before the first NSH prompt). After execution of the script, the root FS will look like:

    |--dev/
|   |-- ram0
|   `-- ram1
|--etc/
|   `--init.d/
|       `-- rcS
`--tmp/

Example Configurations. Here are some configurations that have CONFIG_NSH_ROMFSETC=y in the NuttX configuration file. They might provide useful examples:

  • boards/arm/stm32/hymini-stm32v/nsh2

  • boards/arm/dm320/ntosd-dm320/nsh

  • boards/sim/sim/sim/nsh

  • boards/sim/sim/sim/nsh2

  • boards/sim/sim/sim/nx

  • boards/sim/sim/sim/nx11

  • boards/sim/sim/sim/touchscreen

In most of these cases, the configuration sets up the default /etc/init.d/rcS script. The default script is here: apps/nshlib/rcS.template. (The funny values in the template like XXXMKRDMINORXXX get replaced via sed at build time). This default configuration creates a ramdisk and mounts it at /tmp as discussed above.

If that default behavior is not what you want, then you can provide your own custom rcS script by defining CONFIG_NSH_ARCHROMFS=y in the configuration file.

Modifying the ROMFS Image. The contents of the /etc directory are retained in the file apps/nshlib/nsh_romfsimg.h OR, if CONFIG_NSH_ARCHROMFS is defined, include/arch/board/nsh_romfsimg.h. In order to modify the start-up behavior, there are three things to study:

  1. Configuration Options. The additional CONFIG_NSH_ROMFSETC configuration options discussed with the other NSH-specific configuration settings.

  2. tools/mkromfsimg.sh Script. The script tools/mkromfsimg.sh creates nsh_romfsimg.h. It is not automatically executed. If you want to change the configuration settings associated with creating and mounting the /tmp directory, then it will be necessary to re-generate this header file using the tools/mkromfsimg.sh script.

    The behavior of this script depends upon several things:

    1. The configuration settings then installed configuration.

    2. The genromfs tool(available from http://romfs.sourceforge.net) or included within the NuttX buildroot toolchain. There is also a snapshot available in the NuttX tools repository here.

    3. The xxd tool that is used to generate the C header files (xxd is a normal part of a complete Linux or Cygwin installation, usually as part of the vi package).

    4. The file apps/nshlib/rcS.template (OR, if CONFIG_NSH_ARCHROMFS is defined include/arch/board/rcs.template.

  3. rcS.template. The file apps/nshlib/rcS.template contains the general form of the rcS file; configured values are plugged into this template file to produce the final rcS file.

    To generate a custom rcS file a copy of rcS.template needs to be placed at tools/ and changed according to the desired start-up behaviour. Running tools/mkromfsimg.h creates nsh_romfsimg.h which needs to be copied to apps/nshlib OR if CONFIG_NSH_ARCHROMFS is defined to boards/<arch>/<chip>/<board>/include.

rcS.template. The default rcS.template, apps/nshlib/rcS.template, generates the standard, default apps/nshlib/nsh_romfsimg.h file.

If CONFIG_NSH_ARCHROMFS is defined in the NuttX configuration file, then a custom, board-specific nsh_romfsimg.h file residing in boards/<arch>/<chip>/<board>/includewill be used. NOTE when the OS is configured, include/arch/board will be linked to boards/<arch>/<chip>/<board>/include.

All of the startup-behavior is contained in rcS.template. The role of mkromfsimg.sh script is to (1) apply the specific configuration settings to rcS.template to create the final rcS, and (2) to generate the header file nsh_romfsimg.h containing the ROMFS file system image. To do this, mkromfsimg.sh uses two tools that must be installed in your system:

  1. The genromfs tool that is used to generate the ROMFS file system image.

  2. The xxd tool that is used to create the C header file.