This is an automated email from the ASF dual-hosted git repository. acassis pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit e9c107e0bab34473dee9d31922c2af48f005d20d Author: Ludovic Vanasse <[email protected]> AuthorDate: Sun Oct 20 12:02:20 2024 -0400 Doc: Migrate logging to a ram buffer Migrate https://cwiki.apache.org/confluence/display/NUTTX/Logging+to+a+RAM+Buffer to official wiki Signed-off-by: Ludovic Vanasse <[email protected]> --- Documentation/guides/index.rst | 1 + Documentation/guides/logging_rambuffer.rst | 170 +++++++++++++++++++++++++++++ 2 files changed, 171 insertions(+) diff --git a/Documentation/guides/index.rst b/Documentation/guides/index.rst index 3a3d82dd47..3ff5697012 100644 --- a/Documentation/guides/index.rst +++ b/Documentation/guides/index.rst @@ -44,3 +44,4 @@ Guides specialstuff_in_nuttxheaderfiles.rst kernel_threads_with_custom_stacks.rst versioning_and_task_names.rst + logging_rambuffer.rst \ No newline at end of file diff --git a/Documentation/guides/logging_rambuffer.rst b/Documentation/guides/logging_rambuffer.rst new file mode 100644 index 0000000000..515be6aa57 --- /dev/null +++ b/Documentation/guides/logging_rambuffer.rst @@ -0,0 +1,170 @@ +======================= +Logging to a RAM Buffer +======================= + +.. warning:: + Migrated from: + https://cwiki.apache.org/confluence/display/NUTTX/Logging+to+a+RAM+Buffer + + +Default Debug Output +==================== + +By default, when you enable debug output, that output goes to the system +console and is mixed up with the normal console output. Normally, that is +sufficient. However there are some cases where you might want to do things +differently. For example, if there is time critical debug output that +interferes with the operation of the device. Or, if you would like to +separate the normal console output from the debug output. + +One particularly troublesome case is network debug output to console in a +Telnet session. Since the telnet session remaps the console output to the +Telnet connection, the network debug output can generate infinite loops +because the network operation generates debug output to the console, which +generates more debug output, ... and on and on. + +With some creative configuration of the NuttX SYStem LOGging (SYSLOG) feature, +these problems can all be eliminated. + +The syslog Device +================= + +Debug output goes to the `syslog` device. As mentioned above, the default syslog +device device is the system console. However there are many options to control +the behavior of the syslog – too many in fact. There are so many options that +you will probably have to perform experiments to get the syslog working as you +would like it too. + +The RAMLOG Device +================= + +The RAMLOG device is a special character device that can really be used for +most any purpose. However, the RAMLOG device has some special attributes +that make it ideal for use as a syslogging device. + +* It supports the ``syslog_putc`` interface needed for system logging +* It behaves much like a pipe: It implements a queue. Writing to the RAMLOG + device adds data to the head of the queue; reading from the RAMLOG device + removes data from the tail of the queue. +* It can be configured to return EOF when you try to read and there is + nothing available in the RAMLOG. + + +Using the RAMLOG as the syslog Device +===================================== + +This Wiki page addresses the setup for one configuration: Using a `RAMLOG` as +the syslog device. A RAMLOG is a circular buffer in memory. In this +configuration, all debugout output goes to this circular buffer and can later +be retrieved using the NSH ``dmesg`` command + +Here is the summary of what I had to do to get the RAMLOG working as the +syslog device. I use a simulation configuration, but for this feature this +does not matter. + +.. code-block:: bash + + tools/configure.sh sim:nsh + make menuconfig + +I added the following settings. First, these just give me some debug output +to test against: + +.. code-block:: c + + CONFIG_DEBUG=y + CONFIG_DEBUG_FS=y + CONFIG_DEBUG_SCHED=y + +This configures the virtual file system to support the syslog device and is a +necessary pre-condition for other settings: + +.. code-block:: c + + CONFIG_SYSLOG=y + +These enables the RAMLOG and configure it for use as the syslog device + +.. code-block:: c + + CONFIG_RAMLOG=y + CONFIG_RAMLOG_CONSOLE_BUFSIZE=8192 + CONFIG_RAMLOG_NONBLOCKING=y + CONFIG_RAMLOG_SYSLOG=y + #CONFIG_SYSLOG_CHAR undefined, else duplicate output with syslog_putc() + +Now when I run NuttX, I get output like this. The ``dmesg`` command now appears +as an NSH command: + +.. code-block:: bash + + NuttShell (NSH) NuttX-7.1 + nsh> help + help usage: help [-v] [<cmd>] + [ dd free mkdir mw sleep + ? df help mkfatfs ps test + break dmesg hexdump mkfifo pwd true + cat echo kill mkrd rm umount + cd exec losetup mh rmdir unset + cp exit ls mount set usleep + cmp false mb mv sh xd + Builtin Apps: + hello + +The ``dmesg`` command dumps the contents and clears the RAMLOG: + +.. code-block:: bash + + nsh> dmesg + nx_start: Entry + up_unblock_task: Unblocking TCB=52bc70 + up_unblock_task: New Active Task TCB=52bc70 + posix_spawn_exec: ERROR: exec failed: 22 + cmd_mkrd: RAMDISK at 52d4f0 + posix_spawn_exec: ERROR: exec failed: 22 + mkfatfs_tryfat16: Too few or too many clusters for FAT16: 4081 < 983 < 1022 + mkfatfs_clustersearch: Cannot format FAT16 at 1 sectors/cluster + mkfatfs_configfatfs: Sector size: 512 bytes + mkfatfs_configfatfs: Number of sectors: 1024 sectors + mkfatfs_configfatfs: FAT size: 12 bits + mkfatfs_configfatfs: Number FATs: 2 + mkfatfs_configfatfs: Sectors per cluster: 1 sectors + mkfatfs_configfatfs: FS size: 3 sectors + mkfatfs_configfatfs: 985 clusters + mkfatfs_configfatfs: Root directory slots: 512 + mkfatfs_configfatfs: Volume ID: 00000000 + mkfatfs_configfatfs: Volume Label: " " + posix_spawn_exec: ERROR: exec failed: 22 + fat_mount: FAT12: + fat_mount: HW sector size: 512 + fat_mount: sectors: 1024 + fat_mount: FAT reserved: 1 + fat_mount: sectors: 1024 + fat_mount: start sector: 1 + fat_mount: root sector: 7 + fat_mount: root entries: 512 + fat_mount: data sector: 39 + fat_mount: FSINFO sector: 0 + fat_mount: Num FATs: 2 + fat_mount: FAT sectors: 3 + fat_mount: sectors/cluster: 1 + fat_mount: max clusters: 985 + fat_mount: FSI free count -1 + fat_mount: next free 0 + posix_spawn_exec: ERROR: exec failed: 22 + posix_spawn_exec: ERROR: exec failed: 22 + nsh> + +As mentioned, the dmesg command clears the RAMLOG. So when it is used again, +only new debug output is shown: + +.. code-block:: bash + + nsh> dmesg + posix_spawn_exec: ERROR: exec failed: 22 + +As a side note, the ``posix_spawn_exec`` error will occur on each command in +this configuration. That is because NSH first tries to execute a command from +a file found in the file system on the ``PATH`` variable. You will not see +this error in your system unless you have ``CONFIG_NSH_FILE_APPS=y`` +defined in your configuration. \ No newline at end of file
