^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) =====================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) Documentation for userland software suspend interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) =====================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) (C) 2006 Rafael J. Wysocki <rjw@sisk.pl>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) First, the warnings at the beginning of swsusp.txt still apply.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) Second, you should read the FAQ in swsusp.txt _now_ if you have not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) done it already.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) Now, to use the userland interface for software suspend you need special
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) utilities that will read/write the system memory snapshot from/to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) kernel. Such utilities are available, for example, from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) <http://suspend.sourceforge.net>. You may want to have a look at them if you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) are going to develop your own suspend/resume utilities.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) The interface consists of a character device providing the open(),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) release(), read(), and write() operations as well as several ioctl()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) commands defined in include/linux/suspend_ioctls.h . The major and minor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) numbers of the device are, respectively, 10 and 231, and they can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) be read from /sys/class/misc/snapshot/dev.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) The device can be open either for reading or for writing. If open for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) reading, it is considered to be in the suspend mode. Otherwise it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) assumed to be in the resume mode. The device cannot be open for simultaneous
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) reading and writing. It is also impossible to have the device open more than
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) once at a time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) Even opening the device has side effects. Data structures are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) allocated, and PM_HIBERNATION_PREPARE / PM_RESTORE_PREPARE chains are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) called.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) The ioctl() commands recognized by the device are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) SNAPSHOT_FREEZE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) freeze user space processes (the current process is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) not frozen); this is required for SNAPSHOT_CREATE_IMAGE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) and SNAPSHOT_ATOMIC_RESTORE to succeed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) SNAPSHOT_UNFREEZE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) thaw user space processes frozen by SNAPSHOT_FREEZE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) SNAPSHOT_CREATE_IMAGE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) create a snapshot of the system memory; the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) last argument of ioctl() should be a pointer to an int variable,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) the value of which will indicate whether the call returned after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) creating the snapshot (1) or after restoring the system memory state
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) from it (0) (after resume the system finds itself finishing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) SNAPSHOT_CREATE_IMAGE ioctl() again); after the snapshot
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) has been created the read() operation can be used to transfer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) it out of the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) SNAPSHOT_ATOMIC_RESTORE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) restore the system memory state from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) uploaded snapshot image; before calling it you should transfer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) the system memory snapshot back to the kernel using the write()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) operation; this call will not succeed if the snapshot
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) image is not available to the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) SNAPSHOT_FREE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) free memory allocated for the snapshot image
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) SNAPSHOT_PREF_IMAGE_SIZE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) set the preferred maximum size of the image
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) (the kernel will do its best to ensure the image size will not exceed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) this number, but if it turns out to be impossible, the kernel will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) create the smallest image possible)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) SNAPSHOT_GET_IMAGE_SIZE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) return the actual size of the hibernation image
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) (the last argument should be a pointer to a loff_t variable that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) will contain the result if the call is successful)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) SNAPSHOT_AVAIL_SWAP_SIZE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) return the amount of available swap in bytes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) (the last argument should be a pointer to a loff_t variable that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) will contain the result if the call is successful)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) SNAPSHOT_ALLOC_SWAP_PAGE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) allocate a swap page from the resume partition
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) (the last argument should be a pointer to a loff_t variable that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) will contain the swap page offset if the call is successful)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) SNAPSHOT_FREE_SWAP_PAGES
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) free all swap pages allocated by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) SNAPSHOT_ALLOC_SWAP_PAGE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) SNAPSHOT_SET_SWAP_AREA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) set the resume partition and the offset (in <PAGE_SIZE>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) units) from the beginning of the partition at which the swap header is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) located (the last ioctl() argument should point to a struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) resume_swap_area, as defined in kernel/power/suspend_ioctls.h,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) containing the resume device specification and the offset); for swap
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) partitions the offset is always 0, but it is different from zero for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) swap files (see Documentation/power/swsusp-and-swap-files.rst for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) details).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) SNAPSHOT_PLATFORM_SUPPORT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) enable/disable the hibernation platform support,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) depending on the argument value (enable, if the argument is nonzero)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) SNAPSHOT_POWER_OFF
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) make the kernel transition the system to the hibernation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) state (eg. ACPI S4) using the platform (eg. ACPI) driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) SNAPSHOT_S2RAM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) suspend to RAM; using this call causes the kernel to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) immediately enter the suspend-to-RAM state, so this call must always
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) be preceded by the SNAPSHOT_FREEZE call and it is also necessary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) to use the SNAPSHOT_UNFREEZE call after the system wakes up. This call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) is needed to implement the suspend-to-both mechanism in which the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) suspend image is first created, as though the system had been suspended
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) to disk, and then the system is suspended to RAM (this makes it possible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) to resume the system from RAM if there's enough battery power or restore
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) its state on the basis of the saved suspend image otherwise)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) The device's read() operation can be used to transfer the snapshot image from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) the kernel. It has the following limitations:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) - you cannot read() more than one virtual memory page at a time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) - read()s across page boundaries are impossible (ie. if you read() 1/2 of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) a page in the previous call, you will only be able to read()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) **at most** 1/2 of the page in the next call)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) The device's write() operation is used for uploading the system memory snapshot
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) into the kernel. It has the same limitations as the read() operation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) The release() operation frees all memory allocated for the snapshot image
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) and all swap pages allocated with SNAPSHOT_ALLOC_SWAP_PAGE (if any).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) Thus it is not necessary to use either SNAPSHOT_FREE or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) SNAPSHOT_FREE_SWAP_PAGES before closing the device (in fact it will also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) unfreeze user space processes frozen by SNAPSHOT_UNFREEZE if they are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) still frozen when the device is being closed).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) Currently it is assumed that the userland utilities reading/writing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) snapshot image from/to the kernel will use a swap partition, called the resume
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) partition, or a swap file as storage space (if a swap file is used, the resume
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) partition is the partition that holds this file). However, this is not really
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) required, as they can use, for example, a special (blank) suspend partition or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) a file on a partition that is unmounted before SNAPSHOT_CREATE_IMAGE and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) mounted afterwards.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) These utilities MUST NOT make any assumptions regarding the ordering of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) data within the snapshot image. The contents of the image are entirely owned
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) by the kernel and its structure may be changed in future kernel releases.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) The snapshot image MUST be written to the kernel unaltered (ie. all of the image
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) data, metadata and header MUST be written in _exactly_ the same amount, form
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) and order in which they have been read). Otherwise, the behavior of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) resumed system may be totally unpredictable.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) While executing SNAPSHOT_ATOMIC_RESTORE the kernel checks if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) structure of the snapshot image is consistent with the information stored
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) in the image header. If any inconsistencies are detected,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) SNAPSHOT_ATOMIC_RESTORE will not succeed. Still, this is not a fool-proof
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) mechanism and the userland utilities using the interface SHOULD use additional
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) means, such as checksums, to ensure the integrity of the snapshot image.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) The suspending and resuming utilities MUST lock themselves in memory,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) preferably using mlockall(), before calling SNAPSHOT_FREEZE.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) The suspending utility MUST check the value stored by SNAPSHOT_CREATE_IMAGE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) in the memory location pointed to by the last argument of ioctl() and proceed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) in accordance with it:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) 1. If the value is 1 (ie. the system memory snapshot has just been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) created and the system is ready for saving it):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) (a) The suspending utility MUST NOT close the snapshot device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) _unless_ the whole suspend procedure is to be cancelled, in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) which case, if the snapshot image has already been saved, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) suspending utility SHOULD destroy it, preferably by zapping
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) its header. If the suspend is not to be cancelled, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) system MUST be powered off or rebooted after the snapshot
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) image has been saved.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) (b) The suspending utility SHOULD NOT attempt to perform any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) file system operations (including reads) on the file systems
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) that were mounted before SNAPSHOT_CREATE_IMAGE has been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) called. However, it MAY mount a file system that was not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) mounted at that time and perform some operations on it (eg.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) use it for saving the image).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) 2. If the value is 0 (ie. the system state has just been restored from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) the snapshot image), the suspending utility MUST close the snapshot
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) device. Afterwards it will be treated as a regular userland process,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) so it need not exit.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) The resuming utility SHOULD NOT attempt to mount any file systems that could
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) be mounted before suspend and SHOULD NOT attempt to perform any operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) involving such file systems.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) For details, please refer to the source code.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags