main: Add some documentation
Some tricks like defaulting the source and sink file descriptors to
stdin and stdout aren't necessarily obvious, so add some commentary and
justifications throughout.
Signed-off-by: Andrew Jeffery <andrew@aj.id.au>
Change-Id: I515f36857a7056aa589ecbb09c46372ec4d3976d
diff --git a/main.c b/main.c
index 1f00ada..871da1d 100644
--- a/main.c
+++ b/main.c
@@ -1,6 +1,21 @@
// SPDX-License-Identifier: Apache-2.0
// Copyright (C) 2021 IBM Corp.
+/*
+ * debug-trigger listens for an external signal that the BMC is in some way unresponsive. When the
+ * signal is received it triggers a crash to collect debug data and reboots the system in the hope
+ * that it will recover.
+ *
+ * Usage: debug-trigger [SOURCE] [SINK]
+ *
+ * Examples:
+ * debug-trigger
+ * Set the source as stdin and the sink as stdout. Useful for testing.
+ *
+ * debug-trigger /dev/serio_raw0 /proc/sysrq-trigger
+ * Open /dev/serio_raw0 as the source and /proc/sysrq-trigger as the sink.
+ */
+
#include <err.h>
#include <fcntl.h>
#include <getopt.h>
@@ -81,6 +96,7 @@
int source;
int sink;
+ /* Option processing. Currently nothing implemented, but allows us to use optind */
while (1) {
static struct option long_options[] = {
{0, 0, 0, 0},
@@ -92,12 +108,22 @@
break;
}
+ /*
+ * The default behaviour sets the source as stdin and the sink as stdout. This allows
+ * trivial testing on the command-line with just a keyboard and without crashing the system.
+ */
source = 0;
sink = 1;
+ /* Handle the source argument, if any */
if (optind < argc) {
char devpath[PATH_MAX];
+ /*
+ * To make our lives easy with udev we take the basename of the source argument and
+ * look for it in /dev. This allows us to use %p (the devpath specifier) in the udev
+ * rule to pass the device of interest to the systemd unit.
+ */
strncpy(devpath, argv[optind], sizeof(devpath));
devpath[PATH_MAX - 1] = '\0';
devid = basename(devpath);
@@ -112,16 +138,23 @@
optind++;
}
+ /* Handle the sink argument, if any */
if (optind < argc) {
+ /*
+ * Just open the sink path directly. If we ever need different behaviour then we
+ * patch this bit when we know what we need.
+ */
if ((sink = open(argv[optind], O_WRONLY)) == -1)
err(EXIT_FAILURE, "Failed to open %s", argv[optind]);
optind++;
}
+ /* Check we're done with the command-line */
if (optind < argc)
err(EXIT_FAILURE, "Found %d unexpected arguments", argc - optind);
+ /* Trigger the actions on the sink when we receive an event from the source */
if (process(source, sink) < 0)
errx(EXIT_FAILURE, "Failure while processing command stream");