README

   1
   2 This directory contains a prototype proof-of-concept system
   3 for managing suspend in Linux.
   4 Thus SUSpend MANager (previously called lsusd: Linux SUSpend Daemon)
   5
   6 It contains:
   7
   8  susman:
   9     The composite daemon.  This runs as three processes representing
  10     lsusd, lsused, and wakealarmd as described below.
  11
  12  lsusd:
  13     The main daemon.  It is written to run a tight loop and blocks as
  14      required.  It obeys the wakeup_count protocol to get race-free
  15      suspend and allows clients to register to find out about
  16      suspend and to block it either briefly or longer term.
  17     It uses files in /run/suspend for all communication.
  18
  19     File are:
  20
  21       disabled:  This file always exists.  If any process holds a
  22         shared flock(), suspend will not happen.  If a process reads
  23         from this file the current suspend attempt will abort.  For
  24         this to work, '/var' needs to be mounted with "-o strictatime".
  25       immediate:  If this file exists and an exclusive lock is held on
  26         it, lsusd will try to suspend whenever possible.
  27       request:  If this is created, then lsusd will try to suspend
  28         once, and will remove the file when suspend completes or aborts.
  29       watching:  This is normally empty.  Any process wanting to know
  30         about suspend should take a shared flock and check the file is
  31         still empty, and should watch for modification.
  32         When suspend is imminent, lsusd creates 'watching-next', writes
  33         a byte to 'watching' and waits for an exclusive lock on 'watching'.
  34         Clients should move their lock to 'watching-next' when ready for
  35         suspend.
  36         When suspend completes, another byte (or 2) is written to
  37         'watching', and 'watching-next' is renamed over it.  Clients can
  38         use either of these to know that resume has happened.
  39
  40       watching-next: The file that will be 'watching' in the next awake cycle.
  41
  42     lsusd does not try to be event-loop based because:
  43       - /sys/power/wakeup_count is not pollable.  This could probably be
  44         'fixed' but I want code to work with today's kernel.  It will probably
  45         only block 100msec at most, but that might be too long???
  46       - I cannot get an event notification when a lock is removed from a
  47         file. :-(  And I think locks are an excellent light-weight
  48         mechanism for blocking suspend.
  49
  50   lsused:
  51       This is an event-loop based daemon that can therefore easily handle
  52       socket connections and client protocols which need prompt
  53       response.  It communicates with lsusd and provides extra
  54       services to clients.
  55
  56       lsused (which needs a better name) listens on the socket
  57             /run/suspend/registration
  58       A client may connect and send a list of file descriptors.
  59       When a suspend is immanent, if any file descriptor is readable,
  60       lsused will send a 'S' message to the client and await an 'R' reply
  61       (S == suspend, R == ready).  When all replies are in, lsused will
  62       allow the suspend to complete.  When it does (or aborts), it will send
  63       'A' (awake) to those clients to which it sent 'S'.
  64
  65       This allows a client to get a chance to handle any wakeup events,
  66       but not to be woken unnecessarily on every suspend.
  67
  68    wakealarmd:
  69       This allows clients to register on the socket
  70              /run/suspend/wakealarm
  71       They write a timestamp in seconds since epoch, and will receive
  72       a 'Now' message when that time arrives.
  73       Between the time the connection is made and the time a "seconds"
  74       number is written, suspend will be blocked.
  75       Also between the time that "Now" is sent and when the socket is
  76       closed, suspend is also blocked.
  77
  78    request_suspend:
  79       A simple tool to create the 'request' file and then wait for it
  80       to be removed.
  81
  82    libsus.a:  A library of client-side interfaces.
  83       suspend_open, suspend_block, suspend_allow, suspend_close,
  84         suspend_abort:
  85            easy interface to blocking suspend
  86       suspend_watch, suspend_unwatch:
  87            For use in libevent programs to get notifications of
  88            suspend and resume via the 'watching' file.
  89       wake_set, wake_destory:
  90            create a libevent event for an fd which is protected from
  91            suspend. Whenever it is readable, suspend will not be entered.
  92       wakealarm_set, wakealarm_destroy:
  93            create a libevent event for a particular time which will
  94            trigger even if system is suspend, and will protect against
  95            suspend while event is happening.
  96
  97
  98    block_test watch_test event_test alarm_test
  99         simple test programs for the above interfaces.
 100
 101
 102     suspend.py  dnotify.py:
 103        Sample code for detecting suspend/resume from python
 104     block.sh test_block.sh:
 105        Sample code for disabling suspend from shell.
 106
 107 All code is available under GPLv2+.  However if you ask for a different
 108 license I am unlikely to refuse (at least with the early prototype).
 109
 110 Patches and comments are welcome, but please also feel free to include
 111 any of this in some more complete framework.