acassis commented on code in PR #17752:
URL: https://github.com/apache/nuttx/pull/17752#discussion_r2657535857
##########
Documentation/components/drivers/special/sensors/sensor_monitor.rst:
##########
@@ -0,0 +1,523 @@
+==========================
+Sensor Monitor (procfs)
+==========================
+
+Overview
+========
+
+The Sensor Monitor is a dynamic debugging tool implemented as a procfs
interface
+that allows users to monitor and control sensor logging at runtime. It provides
+a flexible way to enable/disable sensor debug output without rebuilding the
system,
+making it particularly useful for debugging sensor-related issues in production
+environments.
+
+The monitor uses a hash table to store monitored sensor topics and their
associated
+log levels, allowing efficient lookup and modification of monitoring settings.
+
+Features
+========
+
+- **Dynamic Configuration**: Add or remove monitored sensors at runtime
+- **Log Level Control**: Set different log levels for different sensors
+- **Batch Operations**: Add or remove multiple sensors in a single command
+- **Procfs Interface**: Easy to use through standard file operations
+- **Hash Table Backend**: Efficient storage and lookup using ``hsearch_r()``
+- **Persistent Configuration**: Default sensor list can be configured at build
time
+
+Configuration
+=============
+
+To enable the Sensor Monitor, the following configuration options are required:
+
+.. code-block:: kconfig
+
+ CONFIG_SENSORS_MONITOR=y # Enable sensor monitor
+ CONFIG_SENSORS_MONITOR_BUCKET=<size> # Hash table bucket size
+ CONFIG_SENSORS_MONITOR_LIST="<sensors>" # Default monitored sensors
+
+Configuration Options
+---------------------
+
+**CONFIG_SENSORS_MONITOR**
+ Enable the sensor monitor procfs interface.
+
+**CONFIG_SENSORS_MONITOR_BUCKET**
+ Specifies the number of buckets in the hash table used to store monitored
+ sensors. A larger value provides better performance for many sensors but
+ uses more memory. Recommended values:
+
+ - Small systems: 16-32
+ - Medium systems: 64-128
+ - Large systems: 256+
+
+**CONFIG_SENSORS_MONITOR_LIST**
+ A string containing space-separated sensor names to monitor by default.
+ This list is applied during initialization.
+
+ Example::
+
+ CONFIG_SENSORS_MONITOR_LIST="sensor_accel sensor_gyro"
+
+Usage
+=====
+
+The Sensor Monitor is accessed through the ``/proc/sensor_monitor`` file.
+
+Reading Status
+--------------
+
+To view currently monitored sensors and their log levels:
+
+.. code-block:: bash
+
+ cat /proc/sensor_monitor
+
+This displays:
+
+1. Usage instructions
+2. Command examples
+3. List of currently monitored sensors with their log levels
+
+Example output::
+
+ Sensor procfs - Dynamic sensor debugging tool
+
+ Usage:
+ cat /proc/sensor_monitor - Show currently monitored topics
+ echo <level> <topic> > /proc/sensor_monitor - Add topic(s)
+ echo rm <topic> > /proc/sensor_monitor - Remove topic(s)
+ ...
+
+ sensor_accel 1
+ sensor_gyro 2
+ sensor_compass 1
+
+Adding Sensors
+--------------
+
+**Add with Default Log Level (1)**
+
+.. code-block:: bash
+
+ echo sensor_accel > /proc/sensor_monitor
+
+**Add with Specific Log Level**
+
+.. code-block:: bash
+
+ echo 2 sensor_accel > /proc/sensor_monitor
+
+Log levels correspond to syslog levels (0-7), where:
+
+- 0 = LOG_EMERG (Emergency)
+- 1 = LOG_ALERT (Alert)
+- 2 = LOG_CRIT (Critical)
Review Comment:
Initially this order was confuse to me, but after some search I understood
that it came from BSD syslog, later standardized in RFC 3164 and RFC 5424.
```
Level | Name | Meaning (operationally)
0 | EMERG | System is unusable right now
1 | ALERT | Immediate action required
2 | CRIT | Serious failure, but system may still run
3 | ERR | Error condition. Operation failed, but scope is limited
and system remains stable.
4 | WARNING | Abnormal situation. Something unexpected happened, but
no failure yet.
5 | NOTICE | Significant normal event. Expected behavior, but
important enough to be logged.
6 | INFO | Informational message. Routine state changes, progress
messages, normal operation.
7 | DEBUG | Debug-level detail. Developer-oriented, noisy, not for
production diagnosis.
```
I think the Documentation is very good now, please just include this
information above, then I will approve.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
