From: Daniel F. Dickinson <redacted>
Date: Sat, 29 Aug 2026 21:01:39 +0000 (-0400)
Subject: nut: improve documentation
X-Git-Url: http://git.99rst.org/?a=commitdiff_plain;h=2537757a3be297b15a27867d25d951759c9eeced;p=openwrt-packages.git

nut: improve documentation

Include more inline comments to document the nut-server initscript and
usb hotplug.

Also trim an extraneous space in a comment.

Signed-off-by: Daniel F. Dickinson <redacted>
---

diff --git a/net/nut/files/libhid-ups.hotplug b/net/nut/files/libhid-ups.hotplug
index 883f40de6..3be1a6c8b 100644
--- a/net/nut/files/libhid-ups.hotplug
+++ b/net/nut/files/libhid-ups.hotplug
@@ -76,6 +76,9 @@ start_stop_driver() {
 		# We check enabled again here, in case of a race condition since
 		# our last check.
 		if /etc/init.d/nut-server enabled; then
+			# As the driver start goes through the initscript's start which has a
+			# procd_lock, the driver should not be started twice, even if hotplug
+			# fires as soon as hotplugging is allowed in initscript's boot()
 			if ! /etc/init.d/nut-server start "$ups"; then
 				log_error "Failed to start '$ups' processing '$ACTION' for '$DEVNAME'" "libhid-ups" nut-usb-hotplug
 				return 0
@@ -252,7 +255,7 @@ perform_libhid_action() {
 	# PRODUCT comes from the calling hotplug event, and
 	# is of the form vendorid/productid/other
 	# The code below uses shell parameter expansion to split out
-	# vendorid as pvendid and  productid as pprodid
+	# vendorid as pvendid and productid as pprodid
 
 	# We disable the check for possible misspelling as the variables names
 	# are similar, but PRODUCT, pvendid, and pprodid are correct.
diff --git a/net/nut/files/nut-serial.hotplug b/net/nut/files/nut-serial.hotplug
index 6cceb10dd..50c0314ae 100644
--- a/net/nut/files/nut-serial.hotplug
+++ b/net/nut/files/nut-serial.hotplug
@@ -194,6 +194,8 @@ if [ "$ACTION" = "add" ] && [ -n "$DEVNAME" ]; then
 	# ttyUSB* or ttyAMA* or ttyACM* or ttyGS*
 	case "$DEVNAME" in
 	ttyUSB* | ttyAMA* | ttyACM* | ttyGS*)
+		# As we are at the top-level of the hotplug event, this only aborts this
+		# hotplug event, not hotplug events for other devices
 		nut_on_hotplug_add || exit 1
 		;;
 	esac
diff --git a/net/nut/files/nut-server.init b/net/nut/files/nut-server.init
index b33e8f51c..3dfdbf066 100644
--- a/net/nut/files/nut-server.init
+++ b/net/nut/files/nut-server.init
@@ -103,6 +103,10 @@ basescript=$(readlink "$initscript")
 has_running_driver() {
 	local instances instance
 
+	# have_driver_instance and have_upsd_instance are 'pseudo-globals' -
+	# they are local to the _caller_ and visible/modifiable in this
+	# function in order to get the value back to the caller.
+
 	instances="$(list_running_instances "nut-server")"
 	[ -n "$instances" ] || return 0
 	set -f
@@ -244,14 +248,24 @@ stop_no_longer_configured_instances() {
 	local instance instances
 
 	# Stop any driver instances which are no longer configured
+	# This can occur when the configuration is changed and the service
+	# is restarted or reloaded, as this script is not notified of what has
+	# changed if the configuration changes; the script will simply
+	# generate a new configuration in that event.
 	# We can only reliably do this for instances managed by procd
 	instances="$(list_running_instances "nut-server")"
 	[ -n "$instances" ] || return 0
 	set -f
+	# Check that all instances are associated with a configured driver or
+	# the upsd daemon
 	for instance in $instances; do
+		# upsd should be stopped last, if it is stopped at all
 		if [ "$instance" = "upsd" ]; then
 			continue
 		fi
+		# Set to true if any instance was running, whether stopped here, or left
+		# running. have_driver_instance (set in has_running_driver) lets us know
+		# if any driver is still running.
 		had_running_instance="true"
 		config_get driver "$instance" driver
 		# Only stop not configured but running instances
@@ -271,7 +285,8 @@ stop_no_longer_configured_instances() {
 
 	# If we have no UPS instances we must stop upsd or it will crash
 	# The "nut-server" service remains active and will 'see' configuration
-	# changes and execute reload_service when they are detected
+	# changes and execute reload_service when they are detected, but avoid
+	# signalling upsd if it is not running ('had_running_instance' != "true")
 	if [ "$have_upsd_instance" = "true" ] && [ "$have_driver_instance" = "false" ] && [ "$had_running_instance" = "true" ]; then
 		log_msg "Stopping upsd because no driver instances configured" "nut-server" "nut-server" "notice"
 		signal_instance "upsd" "upsd" "stop" "TERM" "${STATEPATH}/upsd.pid" "" "nut-server" "procd_kill" "nut-server" "upsd"
@@ -520,6 +535,9 @@ manage_service() {
 			fi
 			;;
 		esac
+		# Ensure drivers no longer present in config, but which are still running
+		# get stopped. This is required because we are not notified of what was
+		# removed when configuration is removed.
 		stop_no_longer_configured_instances
 		return $ret
 		;;