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 883f40de6bf7a2a6df75f2c3323c1edf0789e708..3be1a6c8b0fcd1ff1a64c80641bc458e4bdd3636 100644 (file)
--- 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 6cceb10dd38623009fc04d77e3a20e94eb763f20..50c0314aeb42d3c406fa674288204c6e4173b230 100644 (file)
--- 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 b33e8f51c87118f62ecbd084ca47c14f7060b71e..3dfdbf0665c9d4ad6f90ad19bc795f90ac79dc1f 100644 (file)
--- 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
                ;;