first try updating README.md

Signed-off-by: Clark Williams <clark.williams@gmail.com>

1 files changed, 46 insertions, 0 deletions

diff --git a/README.md b/README.md
index 5aad105..a5b87c9 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,47 @@
 # starvation_monitor
+
+The starvation_monitor program is a mechanism to prevent the *starvation* of operating
+system threads in a real-time Linux system. The premise is to start up
+on a *housekeeping* cpu (one that is not used for real-application
+purposes) and to periodically monitor the state of each thread in the
+system, looking for a thread that has been on a run queue (i.e. ready
+to run) for a specifed length of time without being run. This
+condition is usually hit when the thread is on the same cpu as a
+high-priority cpu-intensive task and therefore is being given no
+opportunity to run.
+
+When a thread is judged to be starving, starvation_monitor changes
+that thread to use the SCHED_DEADLINE policy and gives the thread a
+small slice of time for that cpu (specified on the command line). The
+thread then runs and when that timeslice is used, the thread is then
+returned to its original scheduling policy and starvation_monitor then
+continues to monitor thread states.
+
+## Command Line Options
+
+`Usage: starvation_monitor [-l] [-v] [-k] [-s] [-f] [-h]
+          [-c cpu-list]
+          [-p time in ns] [-r time in ns]
+          [-d time in seconds ] [-t time in seconds ]`
+
+### Logging options
+- -l/--log_only: only log information (do not boost) [false]
+- -v/--verbose: print info to the std output [false]
+- -k/--log_kmsg: print log to the kernel buffer [false]
+- -s/--log_syslog: print log to syslog [true]
+
+### Startup options
+- -f/--foreground: run in foreground [false but true when -v]
+- -P/--pidfile: write daemon pid to specified file [no pidfile]
+
+### Boosting options
+- -p/--boost_period: SCHED_DEADLINE period [ns] that the starving task will receive [1000000000]
+- -r/--boost_runtime: SCHED_DEADLINE runtime [ns] that the starving task will receive [20000]
+- -d/--boost_duration: how long [s] the starving task will run with SCHED_DEADLINE [3]
+
+### Monitoring options
+- -t/--starving_threshold: how long [s] the starving task will wait before being boosted [60]
+- -A/--aggressive_mode: dispatch one thread per run queue, even when there is no starving
+                          threads on all CPU (uses more CPU/power). [false]
+### Miscellaneous
+- -h/--help: print this menu