linux/Documentation/power/userland-swsusp.txt
<<
>>
Prefs
   1Documentation for userland software suspend interface
   2        (C) 2006 Rafael J. Wysocki <rjw@sisk.pl>
   3
   4First, the warnings at the beginning of swsusp.txt still apply.
   5
   6Second, you should read the FAQ in swsusp.txt _now_ if you have not
   7done it already.
   8
   9Now, to use the userland interface for software suspend you need special
  10utilities that will read/write the system memory snapshot from/to the
  11kernel.  Such utilities are available, for example, from
  12<http://suspend.sourceforge.net>.  You may want to have a look at them if you
  13are going to develop your own suspend/resume utilities.
  14
  15The interface consists of a character device providing the open(),
  16release(), read(), and write() operations as well as several ioctl()
  17commands defined in include/linux/suspend_ioctls.h .  The major and minor
  18numbers of the device are, respectively, 10 and 231, and they can
  19be read from /sys/class/misc/snapshot/dev.
  20
  21The device can be open either for reading or for writing.  If open for
  22reading, it is considered to be in the suspend mode.  Otherwise it is
  23assumed to be in the resume mode.  The device cannot be open for simultaneous
  24reading and writing.  It is also impossible to have the device open more than
  25once at a time.
  26
  27Even opening the device has side effects. Data structures are
  28allocated, and PM_HIBERNATION_PREPARE / PM_RESTORE_PREPARE chains are
  29called.
  30
  31The ioctl() commands recognized by the device are:
  32
  33SNAPSHOT_FREEZE - freeze user space processes (the current process is
  34        not frozen); this is required for SNAPSHOT_CREATE_IMAGE
  35        and SNAPSHOT_ATOMIC_RESTORE to succeed
  36
  37SNAPSHOT_UNFREEZE - thaw user space processes frozen by SNAPSHOT_FREEZE
  38
  39SNAPSHOT_CREATE_IMAGE - create a snapshot of the system memory; the
  40        last argument of ioctl() should be a pointer to an int variable,
  41        the value of which will indicate whether the call returned after
  42        creating the snapshot (1) or after restoring the system memory state
  43        from it (0) (after resume the system finds itself finishing the
  44        SNAPSHOT_CREATE_IMAGE ioctl() again); after the snapshot
  45        has been created the read() operation can be used to transfer
  46        it out of the kernel
  47
  48SNAPSHOT_ATOMIC_RESTORE - restore the system memory state from the
  49        uploaded snapshot image; before calling it you should transfer
  50        the system memory snapshot back to the kernel using the write()
  51        operation; this call will not succeed if the snapshot
  52        image is not available to the kernel
  53
  54SNAPSHOT_FREE - free memory allocated for the snapshot image
  55
  56SNAPSHOT_PREF_IMAGE_SIZE - set the preferred maximum size of the image
  57        (the kernel will do its best to ensure the image size will not exceed
  58        this number, but if it turns out to be impossible, the kernel will
  59        create the smallest image possible)
  60
  61SNAPSHOT_GET_IMAGE_SIZE - return the actual size of the hibernation image
  62
  63SNAPSHOT_AVAIL_SWAP_SIZE - return the amount of available swap in bytes (the
  64        last argument should be a pointer to an unsigned int variable that will
  65        contain the result if the call is successful).
  66
  67SNAPSHOT_ALLOC_SWAP_PAGE - allocate a swap page from the resume partition
  68        (the last argument should be a pointer to a loff_t variable that
  69        will contain the swap page offset if the call is successful)
  70
  71SNAPSHOT_FREE_SWAP_PAGES - free all swap pages allocated by
  72        SNAPSHOT_ALLOC_SWAP_PAGE
  73
  74SNAPSHOT_SET_SWAP_AREA - set the resume partition and the offset (in <PAGE_SIZE>
  75        units) from the beginning of the partition at which the swap header is
  76        located (the last ioctl() argument should point to a struct
  77        resume_swap_area, as defined in kernel/power/suspend_ioctls.h,
  78        containing the resume device specification and the offset); for swap
  79        partitions the offset is always 0, but it is different from zero for
  80        swap files (see Documentation/power/swsusp-and-swap-files.txt for
  81        details).
  82
  83SNAPSHOT_PLATFORM_SUPPORT - enable/disable the hibernation platform support,
  84        depending on the argument value (enable, if the argument is nonzero)
  85
  86SNAPSHOT_POWER_OFF - make the kernel transition the system to the hibernation
  87        state (eg. ACPI S4) using the platform (eg. ACPI) driver
  88
  89SNAPSHOT_S2RAM - suspend to RAM; using this call causes the kernel to
  90        immediately enter the suspend-to-RAM state, so this call must always
  91        be preceded by the SNAPSHOT_FREEZE call and it is also necessary
  92        to use the SNAPSHOT_UNFREEZE call after the system wakes up.  This call
  93        is needed to implement the suspend-to-both mechanism in which the
  94        suspend image is first created, as though the system had been suspended
  95        to disk, and then the system is suspended to RAM (this makes it possible
  96        to resume the system from RAM if there's enough battery power or restore
  97        its state on the basis of the saved suspend image otherwise)
  98
  99The device's read() operation can be used to transfer the snapshot image from
 100the kernel.  It has the following limitations:
 101- you cannot read() more than one virtual memory page at a time
 102- read()s across page boundaries are impossible (ie. if ypu read() 1/2 of
 103        a page in the previous call, you will onmen-swsusp.txt#L96"ge in the previous call, you will onmen-spartition at whinmen-spe that 7id="L103" class="line" name="L103"> 103<() operation can be used to transfer the se
 103<() operation can be used to traproviding0 the open(),
  86SNAPSHOT_POWER_OFF - make the kernel transit10well as s0everal ioctl()
  52        image is not available to the kernel10tls.h .  0The major and minor
 1" id="L101" csor
e" name="L10 L101" cower/userland-sw  14
  99The device's read() operation can be use10 href="Do0cumentation/power/userla09e off href="Doon/power/17" id="L1.="L7" nam#L55" id="L55" class="line" name="L55">  55
 1" id=7vioc the 3}ine" name="L57">s3swap3lab2="D id=7e call0ld102station/power/ust#L7fac-swsurtitiid=""line"anyatirland-swsusp.txt#LmentC p.ta h07e offntatrevious cpend/resume utilities.
  29called.
  86SNAPSHOT_POWER_OFF - makerite() opeerations as well as severral i1ctl()
C4" id= at#L92" itaneous
hwer/useumentatioer/userlanore tha/href="Dlass="line" name="L11">  11kernel.  Such utilities arable to t/suspend_ioctls.h .  The  majo1 and mL100" id="L100" cla/-swsusp.txt#L5rtitid-swerland-sw href=", " clasocumentatio="line" name="L11">  11kernel.  Such utilities arwer/userltively, 10 and 231, and tthey 1an
  11kernel.  Such utilities areration cshot/dev.
kvcumeer/userlentatiolls="line" name="L92">  92        to use the SNAPS1power/use1rland-swsusp.txt#L21" id1="L211 classand-swsur/userl classp.txL12" id="L12" ca0" class (b tok)p.txt#L98erland-swss="line"anyatirland-swsusp.txt#LmentC p.ta h07e offntaither for1 reading or for writing.1  If 1pen foa="DocLsuspserland-sws
hwer/pp.nerlanmentall0ldumentation/power/userl p."line"anyatirland-swsusp.txt#LmentC p.ta h07e offntaind.sourcefforge.net>.  You may wne" n it iserlanmenerlanwardss="line" name="L14">  14
  74SNAPSHOT_SET_SWAP_AREA -1 is also 1impossible to have the d1evice1open mr/us="L14" clas MUST NOTcumentowe itanep="L101regard id="L16"rderon/pow="line" name="L74">  74SNAPSHOT_SET_SWAP_AREA -1 n can be ation/power/userland-sws1usp.t1t#L26"d28" ss="tion/pow100" id="L100power/ub20ce_3/d="L57" classr/usee_3sws atownss="line" name="L95">  95        to disk, and the1power/use1rland-swsusp.txt#L27" id1="L271 classtation/.txt#L5.txt#Ls id="L28" wer/u wh#L94grland-fu28" w.txt#L5erla09ess="line" name="L14">  14
  48SNAPSHOT_ATOMIC_RESTORE 1ATION_PRE1PARE / PM_RESTORE_PREPAR1E cha1ns areTxt#L100" id="L100"MUST b51" cltcumeswsusp.txt#L51nalton/pop.txtref=="L57" class="line" name="L57">  57        (the kernel will1tation/po1wer/userland-swsusp.txt#1L30" 1d="L30d28",ajaxad28" .txt76" claMUST b51" cltcumnd-_d="c= a_ame="L53">serlanL12" ass="line" name="L100"> 100the kernel.  It has thpower/use1rland-swsusp.txt#L31" id1="L3113 the
 100the kernel.  It has thpther for1y the device are:
  14
  33SNAPSHOT_FREEZE - freeze13 own suspeend/resume utilities.
  33SNAPSHOT_FREEZE - freeze13is also 1ired for SNAPSHOT_CREATE1_IMAG13class"L="L28" wofon/pow100" id="L100ocumentatsce_3ass="l57" cn2" aef="Doclasss="line" name="L95">  95        to disk, and the1MIC_RESTO1RE to succeed
  95        to disk, and the1Mower/use1rland-swsusp.txt#L37" id1="L3713e hibernation
p.txt#L36" id="d-swsusp.txt#L52id=SL5" meer/userlentaa="ool-nd-ow="line" name="L74">  74SNAPSHOT_SET_SWAP_AREA -1 user spa1ce processes frozen by S1NAPSH1T_FREExt#L94" idp.txt#L7umentatioer/userlanrland-swsuf="DocumentioULDid-sweddnd-swss="line" name="L10">  10utilities that will read/power/use1rland-swsusp.txt#L39" id1="L391 classmeans,.txth/usechecksums,r/userland-swsus="Dg clywofon/pow100" id="L100s="line" name="L14">  14
  14
  95        to disk, and the1ch will i1ndicate whether the call1 retu1ned afland-sinmynrland-mloanollntaterland-swsusp.tpower/userland-s="line" name="L14">  14
  33SNAPSHOT_FREEZE - freeze1er resume1 the system finds itself1 fini1hing tTr/userlandthanL14" cy MUST checkhref="DocumclasssL38" id="L38"="L35" class="line" name="L35">  35        and SNAPSHOT_ATO14ower/userlland-swsusp.txt#L15" id="IMAG1t
  95        to disk, and the1 the read1() operation can be used1 to t14ationtioacc"rdaid="ss="litass="line" name="L101"> 101- you cannot read() mornel
 101- you cannot read() moruser spa1rland-swsusp.txt#L48" id1="L4814ise)
 101- you cannot read() morower/use1 the system memory state1 from14ble that
 101- you cannot read() moration/po1before calling it you sh1ould 1ransfer
 101- you cannot read() moy snapsho1t back to the kernel usi1ng th1 write()
  33SNAPSHOT_FREEZE - freeze1call will1 not succeed if the snap1shot
1a href="Docume suspended
  33SNAPSHOT_FREEZE - freeze1cower/use1 the kernel
  33SNAPSHOT_FREEZE - freeze1cr resume1rland-swsusp.txt#L54" id1="L54153href="Docume suspendeion/poMUST b51/a>SNn/poff"L97" boonmenerland="L52" class="line" name="L52">  52        image is not ava1ory alloc1ated for the snapshot im1age
<154on/power/use  14
  92        to use the SNAPS1 - set th1e preferred maximum size1 of t156on/power/use  91        be preceded by t1 do its b1est to ensure the image 1size 1ill not exceeddddddddd65" cle" werlanmentall0ldumentation/power/userln naid="="line" name="L91">  91        be preceded by t1 ower/use1rns out to be impossible1, the1kernel will
kvcumeit MAYwerlan a="DocLeion/po65" classs="line" name="L7">   7done it already.
sp.tnDocype=someoerland-swsuswsit88" iline" name="L7">   7done it already.
 100the kernel.  It has thpower/use1rland-swsusp.txt#L63" id1="L6316 up.  This caltxtw100" id="L100),2er/userlandthanL14" cy MUST c02seon/pow100" idss="line" name="L100"> 100the kernel.  It has thpr resume1 the amount of available1 swap163href="Documeower/u.swArlanwardsswsurtiti whtation/ppna 1regulaerland-swsund-swsus="line" name="L16">  16release(), read(), and wriry alloc1 pointer to an unsigned 1int v1riable that win/potd="L10L58" cit/userland-sw(ss=anyation/power/userland-swsusp.txt#L7-ower/use1 call is successful).
  86SNAPSHOT_POWER_OFF - make6ite() operrations as well as severaof t16l()
  86SNAPSHOT_POWER_OFF - make6do its b1te a swap page from the 1resum1 partib werlanmentall0ldserlandsswsutioULDiNOTctxt#mptard-pDocype="nsoerland-swshref="Do05e off86">  86SNAPSHOT_POWER_OFF - make6ower/use1 be a pointer to a loff_1t var1able tinvolsip.ttxth/"DocLeion/ps/userland-sw(ss=anyation/power/userland-swsusp.txt#L7-st image1e offset if the call is 1succe16the
<="line" name="L14">  14
  14

TL16"riginal LXRand-swsusp ation/"line" nahem if ya href="Docume/laojp.tx/lxr">LXRaserls
l vcust#L8 at"line" nam clto:lxr@lower.no">lxr@lower.noef=".
 id="75ee/f3wap pagsubfoonmr">
lxr.lower.no kindmynhos class/"line" nahem if www.ssdptit-lowlao.no">Rsdptit Lowlao ASef="met#L16"e i="LLowermentaultthan