{"@attributes":{"version":"2.0"},"channel":{"title":{},"description":"A place for my random thoughts about software","link":"https:\/\/tookmund.com\/","pubDate":"Mon, 11 Nov 2024 21:01:46 +0000","lastBuildDate":"Mon, 11 Nov 2024 21:01:46 +0000","generator":"Jekyll v3.10.0","item":[{"title":"Linux's Bedtime Routine","description":"

How does Linux move from an awake machine to a hibernating one?\nHow does it then manage to restore all state?\nThese questions led me to read way too much C in trying to figure out\nhow this particular hardware\/software boundary is navigated.<\/p>\n\n

This investigation will be split into a few parts, with the first one going\nfrom invocation of hibernation to synchronizing all filesystems to disk.<\/p>\n\n

This article has been written using Linux version 6.9.9,\nthe source of which can be found in many places, but can be navigated\neasily through the Bootlin Elixir Cross-Referencer:<\/p>\n\n

https:\/\/elixir.bootlin.com\/linux\/v6.9.9\/source<\/a><\/p>\n\n

Each code snippet will begin with a link to the above giving\nthe file path and the line number of the beginning of the snippet.<\/p>\n\n

A Starting Point for Investigation: \/sys\/power\/state<\/code> and \/sys\/power\/disk<\/code><\/h2>\n\n

These two system files exist to allow debugging of hibernation<\/a>,\nand thus control the exact state used directly.\nWriting specific values to the state<\/code> file controls the exact sleep mode used\nand disk<\/code> controls the specific hibernation mode1<\/a><\/sup>.<\/p>\n\n

This is extremely handy as an entry point to understand how these systems work,\nsince we can just follow what happens when they are written to.<\/p>\n\n

Show and Store Functions<\/h3>\n

These two files are defined using the power_attr<\/code> macro:<\/p>\n\n

kernel\/power\/power.h:80<\/a><\/p>\n

#define power_attr(_name) \\\nstatic struct kobj_attribute _name##_attr = {   \\\n    .attr   = {             \\\n        .name = __stringify(_name), \\\n        .mode = 0644,           \\\n    },                  \\\n    .show   = _name##_show,         \\\n    .store  = _name##_store,        \\\n}\n<\/code><\/pre><\/div><\/div>\n\n
show<\/code> is called on reads and store<\/code> on writes.<\/p>\n\n
state_show<\/code> is a little boring for our purposes, as it just prints all the\navailable sleep states.<\/p>\n\n
kernel\/power\/main.c:657<\/a><\/p>\n
\/*\n * state - control system sleep states.\n *\n * show() returns available sleep state labels, which may be \"mem\", \"standby\",\n * \"freeze\" and \"disk\" (hibernation).\n * See Documentation\/admin-guide\/pm\/sleep-states.rst for a description of\n * what they mean.\n *\n * store() accepts one of those strings, translates it into the proper\n * enumerated value, and initiates a suspend transition.\n *\/\nstatic ssize_t state_show(struct kobject *kobj, struct kobj_attribute *attr,\n\t\t\t  char *buf)\n{\n\tchar *s = buf;\n#ifdef CONFIG_SUSPEND\n\tsuspend_state_t i;\n\n\tfor (i = PM_SUSPEND_MIN; i < PM_SUSPEND_MAX; i++)\n\t\tif (pm_states[i])\n\t\t\ts += sprintf(s,\"%s \", pm_states[i]);\n\n#endif\n\tif (hibernation_available())\n\t\ts += sprintf(s, \"disk \");\n\tif (s != buf)\n\t\t\/* convert the last space to a newline *\/\n\t\t*(s-1) = '\\n';\n\treturn (s - buf);\n}\n<\/code><\/pre><\/div><\/div>\n\n
state_store<\/code>, however, provides our entry point.\nIf the string \u201cdisk\u201d is written to the state<\/code> file, it calls hibernate()<\/code>.\nThis is our entry point.<\/p>\n\n
kernel\/power\/main.c:715<\/a><\/p>\n
static ssize_t state_store(struct kobject *kobj, struct kobj_attribute *attr,\n\t\t\t   const char *buf, size_t n)\n{\n\tsuspend_state_t state;\n\tint error;\n\n\terror = pm_autosleep_lock();\n\tif (error)\n\t\treturn error;\n\n\tif (pm_autosleep_state() > PM_SUSPEND_ON) {\n\t\terror = -EBUSY;\n\t\tgoto out;\n\t}\n\n\tstate = decode_state(buf, n);\n\tif (state < PM_SUSPEND_MAX) {\n\t\tif (state == PM_SUSPEND_MEM)\n\t\t\tstate = mem_sleep_current;\n\n\t\terror = pm_suspend(state);\n\t} else if (state == PM_SUSPEND_MAX) {\n\t\terror = hibernate();\n\t} else {\n\t\terror = -EINVAL;\n\t}\n\n out:\n\tpm_autosleep_unlock();\n\treturn error ? error : n;\n}\n<\/code><\/pre><\/div><\/div>\n\n
kernel\/power\/main.c:688<\/a><\/p>\n
static suspend_state_t decode_state(const char *buf, size_t n)\n{\n#ifdef CONFIG_SUSPEND\n\tsuspend_state_t state;\n#endif\n\tchar *p;\n\tint len;\n\n\tp = memchr(buf, '\\n', n);\n\tlen = p ? p - buf : n;\n\n\t\/* Check hibernation first. *\/\n\tif (len == 4 && str_has_prefix(buf, \"disk\"))\n\t\treturn PM_SUSPEND_MAX;\n\n#ifdef CONFIG_SUSPEND\n\tfor (state = PM_SUSPEND_MIN; state < PM_SUSPEND_MAX; state++) {\n\t\tconst char *label = pm_states[state];\n\n\t\tif (label && len == strlen(label) && !strncmp(buf, label, len))\n\t\t\treturn state;\n\t}\n#endif\n\n\treturn PM_SUSPEND_ON;\n}\n<\/code><\/pre><\/div><\/div>\n\n
Could we have figured this out just via function names?\nSure, but this way we know for sure that nothing else is happening before this\nfunction is called.<\/p>\n\n
Autosleep<\/h3>\n\n
Our first detour is into the autosleep system.\nWhen checking the state above, you may notice that\nthe kernel grabs the pm_autosleep_lock<\/code> before checking the current\nstate.<\/p>\n\n
autosleep is a mechanism originally from Android<\/a>\nthat sends the entire system to either suspend or hibernate whenever it is\nnot actively working on anything.<\/p>\n\n
This is not enabled for most desktop configurations, since it\u2019s primarily\nfor mobile systems and inverts the standard suspend and hibernate interactions.<\/p>\n\n
This system is implemented as a workqueue2<\/a><\/sup>\nthat checks the current number of wakeup events, processes and drivers that\nneed to run3<\/a><\/sup>, and if there aren\u2019t any, then the system is put\ninto the autosleep state, typically suspend. However, it could be hibernate if\nconfigured that way via \/sys\/power\/autosleep<\/code> in a similar manner to\nusing \/sys\/power\/state<\/code> to manually enable hibernation.<\/p>\n\n
kernel\/power\/main.c:841<\/a><\/p>\n
static ssize_t autosleep_store(struct kobject *kobj,\n\t\t\t       struct kobj_attribute *attr,\n\t\t\t       const char *buf, size_t n)\n{\n\tsuspend_state_t state = decode_state(buf, n);\n\tint error;\n\n\tif (state == PM_SUSPEND_ON\n\t    && strcmp(buf, \"off\") && strcmp(buf, \"off\\n\"))\n\t\treturn -EINVAL;\n\n\tif (state == PM_SUSPEND_MEM)\n\t\tstate = mem_sleep_current;\n\n\terror = pm_autosleep_set_state(state);\n\treturn error ? error : n;\n}\n\npower_attr(autosleep);\n#endif \/* CONFIG_PM_AUTOSLEEP *\/\n<\/code><\/pre><\/div><\/div>\n\n
kernel\/power\/autosleep.c:24<\/a><\/p>\n
static DEFINE_MUTEX(autosleep_lock);\nstatic struct wakeup_source *autosleep_ws;\n\nstatic void try_to_suspend(struct work_struct *work)\n{\n\tunsigned int initial_count, final_count;\n\n\tif (!pm_get_wakeup_count(&initial_count, true))\n\t\tgoto out;\n\n\tmutex_lock(&autosleep_lock);\n\n\tif (!pm_save_wakeup_count(initial_count) ||\n\t\tsystem_state != SYSTEM_RUNNING) {\n\t\tmutex_unlock(&autosleep_lock);\n\t\tgoto out;\n\t}\n\n\tif (autosleep_state == PM_SUSPEND_ON) {\n\t\tmutex_unlock(&autosleep_lock);\n\t\treturn;\n\t}\n\tif (autosleep_state >= PM_SUSPEND_MAX)\n\t\thibernate();\n\telse\n\t\tpm_suspend(autosleep_state);\n\n\tmutex_unlock(&autosleep_lock);\n\n\tif (!pm_get_wakeup_count(&final_count, false))\n\t\tgoto out;\n\n\t\/*\n\t * If the wakeup occurred for an unknown reason, wait to prevent the\n\t * system from trying to suspend and waking up in a tight loop.\n\t *\/\n\tif (final_count == initial_count)\n\t\tschedule_timeout_uninterruptible(HZ \/ 2);\n\n out:\n\tqueue_up_suspend_work();\n}\n\nstatic DECLARE_WORK(suspend_work, try_to_suspend);\n\nvoid queue_up_suspend_work(void)\n{\n\tif (autosleep_state > PM_SUSPEND_ON)\n\t\tqueue_work(autosleep_wq, &suspend_work);\n}\n<\/code><\/pre><\/div><\/div>\n\n
The Steps of Hibernation<\/h2>\n\n
Hibernation Kernel Config<\/h3>\n\n
It\u2019s important to note that most of the hibernate-specific functions below\ndo nothing unless you\u2019ve defined CONFIG_HIBERNATION<\/code> in your Kconfig4<\/a><\/sup>.\nAs an example, hibernate<\/code> itself is defined as the following if\nCONFIG_HIBERNATE<\/code> is not set.<\/p>\n\n
include\/linux\/suspend.h:407<\/a><\/p>\n
static inline int hibernate(void) { return -ENOSYS; }\n<\/code><\/pre><\/div><\/div>\n\n
Check if Hibernation is Available<\/h3>\n
We begin by confirming that we actually can perform hibernation,\nvia the hibernation_available<\/code> function.<\/p>\n\n
kernel\/power\/hibernate.c:742<\/a><\/p>\n
if (!hibernation_available()) {\n\tpm_pr_dbg(\"Hibernation not available.\\n\");\n\treturn -EPERM;\n}\n<\/code><\/pre><\/div><\/div>\n\n
kernel\/power\/hibernate.c:92<\/a><\/p>\n
bool hibernation_available(void)\n{\n\treturn nohibernate == 0 &&\n\t\t!security_locked_down(LOCKDOWN_HIBERNATION) &&\n\t\t!secretmem_active() && !cxl_mem_active();\n}\n<\/code><\/pre><\/div><\/div>\n\n
nohibernate<\/code> is controlled by the kernel command line, it\u2019s set via\neither nohibernate<\/code> or hibernate=no<\/code>.<\/p>\n\n
security_locked_down<\/code> is a hook for Linux Security Modules to prevent\nhibernation. This is used to prevent hibernating to an unencrypted storage\ndevice, as specified in the manual page\nkernel_lockdown(7)<\/code><\/a>.\nInterestingly, either level of lockdown, integrity or confidentiality,\nlocks down hibernation because with the ability to hibernate you can extract\nbascially anything from memory and even reboot into a modified kernel image.<\/p>\n\n
secretmem_active<\/code> checks whether there is any active use of\nmemfd_secret<\/code>, and if so it prevents hibernation.\nmemfd_secret<\/code> returns a file descriptor that can be mapped into a process\nbut is specifically unmapped from the kernel\u2019s memory space.\nHibernating with memory that not even the kernel is supposed to\naccess would expose that memory to whoever could access the hibernation image.\nThis particular feature of secret memory was apparently\ncontroversial<\/a>, though not as\ncontroversial as performance concerns around fragmentation when unmapping\nkernel memory\n(which did not end up being a real problem<\/a>).<\/p>\n\n
cxl_mem_active<\/code> just checks whether any CXL memory is active.\nA full explanation is provided in the\ncommit introducing this check<\/a>\nbut there\u2019s also a shortened explanation from cxl_mem_probe<\/code> that\nsets the relevant flag when initializing a CXL memory device.<\/p>\n\n
drivers\/cxl\/mem.c:186<\/a><\/p>\n
* The kernel may be operating out of CXL memory on this device,\n* there is no spec defined way to determine whether this device\n* preserves contents over suspend, and there is no simple way\n* to arrange for the suspend image to avoid CXL memory which\n* would setup a circular dependency between PCI resume and save\n* state restoration.\n<\/code><\/pre><\/div><\/div>\n\n
Check Compression<\/h3>\n\n
The next check is for whether compression support is enabled, and if so\nwhether the requested algorithm is enabled.<\/p>\n\n
kernel\/power\/hibernate.c:747<\/a><\/p>\n
\/*\n * Query for the compression algorithm support if compression is enabled.\n *\/\nif (!nocompress) {\n\tstrscpy(hib_comp_algo, hibernate_compressor, sizeof(hib_comp_algo));\n\tif (crypto_has_comp(hib_comp_algo, 0, 0) != 1) {\n\t\tpr_err(\"%s compression is not available\\n\", hib_comp_algo);\n\t\treturn -EOPNOTSUPP;\n\t}\n}\n<\/code><\/pre><\/div><\/div>\n\n
The nocompress<\/code> flag is set via the hibernate<\/code> command line parameter,\nsetting hibernate=nocompress<\/code>.<\/p>\n\n
If compression is enabled, then hibernate_compressor<\/code> is copied to\nhib_comp_algo<\/code>. This synchronizes the current requested compression\nsetting (hibernate_compressor<\/code>) with the current compression setting\n(hib_comp_algo<\/code>).<\/p>\n\n
Both values are character arrays of size CRYPTO_MAX_ALG_NAME<\/code>\n(128 in this kernel).<\/p>\n\n
kernel\/power\/hibernate.c:50<\/a><\/p>\n
static char hibernate_compressor[CRYPTO_MAX_ALG_NAME] = CONFIG_HIBERNATION_DEF_COMP;\n\n\/*\n * Compression\/decompression algorithm to be used while saving\/loading\n * image to\/from disk. This would later be used in 'kernel\/power\/swap.c'\n * to allocate comp streams.\n *\/\nchar hib_comp_algo[CRYPTO_MAX_ALG_NAME];\n<\/code><\/pre><\/div><\/div>\n\n
hibernate_compressor<\/code> defaults to lzo<\/code> if that algorithm is enabled, otherwise to lz4<\/code> if\nenabled5<\/a><\/sup>. It can be overwritten using the hibernate.compressor<\/code> setting to\neither lzo<\/code> or lz4<\/code>.<\/p>\n\n
kernel\/power\/Kconfig:95<\/a><\/p>\n
choice\n\tprompt \"Default compressor\"\n\tdefault HIBERNATION_COMP_LZO\n\tdepends on HIBERNATION\n\nconfig HIBERNATION_COMP_LZO\n\tbool \"lzo\"\n\tdepends on CRYPTO_LZO\n\nconfig HIBERNATION_COMP_LZ4\n\tbool \"lz4\"\n\tdepends on CRYPTO_LZ4\n\nendchoice\n\nconfig HIBERNATION_DEF_COMP\n\tstring\n\tdefault \"lzo\" if HIBERNATION_COMP_LZO\n\tdefault \"lz4\" if HIBERNATION_COMP_LZ4\n\thelp\n\t  Default compressor to be used for hibernation.\n<\/code><\/pre><\/div><\/div>\n\n
kernel\/power\/hibernate.c:1425<\/a><\/p>\n
static const char * const comp_alg_enabled[] = {\n#if IS_ENABLED(CONFIG_CRYPTO_LZO)\n\tCOMPRESSION_ALGO_LZO,\n#endif\n#if IS_ENABLED(CONFIG_CRYPTO_LZ4)\n\tCOMPRESSION_ALGO_LZ4,\n#endif\n};\n\nstatic int hibernate_compressor_param_set(const char *compressor,\n\t\tconst struct kernel_param *kp)\n{\n\tunsigned int sleep_flags;\n\tint index, ret;\n\n\tsleep_flags = lock_system_sleep();\n\n\tindex = sysfs_match_string(comp_alg_enabled, compressor);\n\tif (index >= 0) {\n\t\tret = param_set_copystring(comp_alg_enabled[index], kp);\n\t\tif (!ret)\n\t\t\tstrscpy(hib_comp_algo, comp_alg_enabled[index],\n\t\t\t\tsizeof(hib_comp_algo));\n\t} else {\n\t\tret = index;\n\t}\n\n\tunlock_system_sleep(sleep_flags);\n\n\tif (ret)\n\t\tpr_debug(\"Cannot set specified compressor %s\\n\",\n\t\t\t compressor);\n\n\treturn ret;\n}\nstatic const struct kernel_param_ops hibernate_compressor_param_ops = {\n\t.set    = hibernate_compressor_param_set,\n\t.get    = param_get_string,\n};\n\nstatic struct kparam_string hibernate_compressor_param_string = {\n\t.maxlen = sizeof(hibernate_compressor),\n\t.string = hibernate_compressor,\n};\n<\/code><\/pre><\/div><\/div>\n\n
We then check whether the requested algorithm is supported via crypto_has_comp<\/code>.\nIf not, we bail out of the whole operation with EOPNOTSUPP<\/code>.<\/p>\n\n
As part of crypto_has_comp<\/code> we perform any needed initialization of the\nalgorithm, loading kernel modules and running initialization code as needed6<\/a><\/sup>.<\/p>\n\n
Grab Locks<\/h3>\n\n
The next step is to grab the sleep and hibernation locks via\nlock_system_sleep<\/code> and hibernate_acquire<\/code>.<\/p>\n\n
kernel\/power\/hibernate.c:758<\/a><\/p>\n
sleep_flags = lock_system_sleep();\n\/* The snapshot device should not be opened while we're running *\/\nif (!hibernate_acquire()) {\n\terror = -EBUSY;\n\tgoto Unlock;\n}\n<\/code><\/pre><\/div><\/div>\n\n
First, lock_system_sleep<\/code> marks the current thread as not freezable, which\nwill be important later7<\/a><\/sup>. It then grabs the system_transistion_mutex<\/code>,\nwhich locks taking snapshots or modifying how they are taken,\nresuming from a hibernation image, entering any suspend state, or rebooting.<\/p>\n\n
The GFP Mask<\/h4>\n
The kernel also issues a warning if the gfp<\/code> mask is changed via either\npm_restore_gfp_mask<\/code> or pm_restrict_gfp_mask<\/code>\nwithout holding the system_transistion_mutex<\/code>.<\/p>\n\n
GFP flags tell the kernel how it is permitted to handle a request for memory.<\/p>\n\n
include\/linux\/gfp_types.h:12<\/a><\/p>\n
 * GFP flags are commonly used throughout Linux to indicate how memory\n * should be allocated.  The GFP acronym stands for get_free_pages(),\n * the underlying memory allocation function.  Not every GFP flag is\n * supported by every function which may allocate memory.\n<\/code><\/pre><\/div><\/div>\n\n
In the case of hibernation specifically we care about the IO<\/code> and FS<\/code> flags,\nwhich are reclaim operators, ways the system is permitted to attempt to free\nup memory in order to satisfy a specific request for memory.<\/p>\n\n
include\/linux\/gfp_types.h:176<\/a><\/p>\n
 * Reclaim modifiers\n * -----------------\n * Please note that all the following flags are only applicable to sleepable\n * allocations (e.g. %GFP_NOWAIT and %GFP_ATOMIC will ignore them).\n *\n * %__GFP_IO can start physical IO.\n *\n * %__GFP_FS can call down to the low-level FS. Clearing the flag avoids the\n * allocator recursing into the filesystem which might already be holding\n * locks.\n<\/code><\/pre><\/div><\/div>\n\n
gfp_allowed_mask<\/code> sets which flags are permitted to be set at the current time.<\/p>\n\n
As the comment below outlines, preventing these flags from being set\navoids situations where the kernel needs to do I\/O to allocate memory\n(e.g. read\/writing swap8<\/a><\/sup>) but the\ndevices it needs to read\/write to\/from are not currently available.<\/p>\n\n
kernel\/power\/main.c:24<\/a><\/p>\n
\/*\n * The following functions are used by the suspend\/hibernate code to temporarily\n * change gfp_allowed_mask in order to avoid using I\/O during memory allocations\n * while devices are suspended.  To avoid races with the suspend\/hibernate code,\n * they should always be called with system_transition_mutex held\n * (gfp_allowed_mask also should only be modified with system_transition_mutex\n * held, unless the suspend\/hibernate code is guaranteed not to run in parallel\n * with that modification).\n *\/\nstatic gfp_t saved_gfp_mask;\n\nvoid pm_restore_gfp_mask(void)\n{\n\tWARN_ON(!mutex_is_locked(&system_transition_mutex));\n\tif (saved_gfp_mask) {\n\t\tgfp_allowed_mask = saved_gfp_mask;\n\t\tsaved_gfp_mask = 0;\n\t}\n}\n\nvoid pm_restrict_gfp_mask(void)\n{\n\tWARN_ON(!mutex_is_locked(&system_transition_mutex));\n\tWARN_ON(saved_gfp_mask);\n\tsaved_gfp_mask = gfp_allowed_mask;\n\tgfp_allowed_mask &= ~(__GFP_IO | __GFP_FS);\n}\n<\/code><\/pre><\/div><\/div>\n\n
Sleep Flags<\/h4>\n
After grabbing the system_transition_mutex<\/code> the kernel then returns and\ncaptures the previous state of the threads flags in sleep_flags<\/code>.\nThis is used later to remove PF_NOFREEZE<\/code> if it wasn\u2019t previously set on the\ncurrent thread.<\/p>\n\n
kernel\/power\/main.c:52<\/a><\/p>\n
unsigned int lock_system_sleep(void)\n{\n\tunsigned int flags = current->flags;\n\tcurrent->flags |= PF_NOFREEZE;\n\tmutex_lock(&system_transition_mutex);\n\treturn flags;\n}\nEXPORT_SYMBOL_GPL(lock_system_sleep);\n<\/code><\/pre><\/div><\/div>\n\n
include\/linux\/sched.h:1633<\/a><\/p>\n
#define PF_NOFREEZE\t\t0x00008000\t\/* This thread should not be frozen *\/\n<\/code><\/pre><\/div><\/div>\n\n
Then we grab the hibernate-specific semaphore to ensure no one can open a\nsnapshot or resume from it while we perform hibernation.\nAdditionally this lock is used to prevent hibernate_quiet_exec<\/code>,\nwhich is used by the nvdimm<\/code> driver to active its firmware with all\nprocesses and devices frozen, ensuring it is the only thing running at that\ntime9<\/a><\/sup>.<\/p>\n\n
kernel\/power\/hibernate.c:82<\/a><\/p>\n
bool hibernate_acquire(void)\n{\n\treturn atomic_add_unless(&hibernate_atomic, -1, 0);\n}\n<\/code><\/pre><\/div><\/div>\n\n
Prepare Console<\/h3>\n
The kernel next calls pm_prepare_console<\/code>.\nThis function only does anything if CONFIG_VT_CONSOLE_SLEEP<\/code> has been set.<\/p>\n\n
This prepares the virtual terminal for a suspend state, switching away to\na console used only for the suspend state if needed.<\/p>\n\n
kernel\/power\/console.c:130<\/a><\/p>\n
void pm_prepare_console(void)\n{\n\tif (!pm_vt_switch())\n\t\treturn;\n\n\torig_fgconsole = vt_move_to_console(SUSPEND_CONSOLE, 1);\n\tif (orig_fgconsole < 0)\n\t\treturn;\n\n\torig_kmsg = vt_kmsg_redirect(SUSPEND_CONSOLE);\n\treturn;\n}\n<\/code><\/pre><\/div><\/div>\n\n
The first thing is to check whether we actually need to switch the VT<\/p>\n\n
kernel\/power\/console.c:94<\/a><\/p>\n
\/*\n * There are three cases when a VT switch on suspend\/resume are required:\n *   1) no driver has indicated a requirement one way or another, so preserve\n *      the old behavior\n *   2) console suspend is disabled, we want to see debug messages across\n *      suspend\/resume\n *   3) any registered driver indicates it needs a VT switch\n *\n * If none of these conditions is present, meaning we have at least one driver\n * that doesn't need the switch, and none that do, we can avoid it to make\n * resume look a little prettier (and suspend too, but that's usually hidden,\n * e.g. when closing the lid on a laptop).\n *\/\nstatic bool pm_vt_switch(void)\n{\n\tstruct pm_vt_switch *entry;\n\tbool ret = true;\n\n\tmutex_lock(&vt_switch_mutex);\n\tif (list_empty(&pm_vt_switch_list))\n\t\tgoto out;\n\n\tif (!console_suspend_enabled)\n\t\tgoto out;\n\n\tlist_for_each_entry(entry, &pm_vt_switch_list, head) {\n\t\tif (entry->required)\n\t\t\tgoto out;\n\t}\n\n\tret = false;\nout:\n\tmutex_unlock(&vt_switch_mutex);\n\treturn ret;\n}\n<\/code><\/pre><\/div><\/div>\n\n
There is an explanation of the conditions under which a switch is performed\nin the comment above the function, but we\u2019ll also walk through the steps here.<\/p>\n\n
Firstly we grab the vt_switch_mutex<\/code> to ensure nothing will modify the list\nwhile we\u2019re looking at it.<\/p>\n\n
We then examine the pm_vt_switch_list<\/code>.\nThis list is used to indicate the drivers that require a switch during suspend.\nThey register this requirement, or the lack thereof, via\npm_vt_switch_required<\/code>.<\/p>\n\n
kernel\/power\/console.c:31<\/a><\/p>\n
\/**\n * pm_vt_switch_required - indicate VT switch at suspend requirements\n * @dev: device\n * @required: if true, caller needs VT switch at suspend\/resume time\n *\n * The different console drivers may or may not require VT switches across\n * suspend\/resume, depending on how they handle restoring video state and\n * what may be running.\n *\n * Drivers can indicate support for switchless suspend\/resume, which can\n * save time and flicker, by using this routine and passing 'false' as\n * the argument.  If any loaded driver needs VT switching, or the\n * no_console_suspend argument has been passed on the command line, VT\n * switches will occur.\n *\/\nvoid pm_vt_switch_required(struct device *dev, bool required)\n<\/code><\/pre><\/div><\/div>\n\n
Next, we check console_suspend_enabled<\/code>. This is set to false\nby the kernel parameter no_console_suspend<\/code>, but defaults to true.<\/p>\n\n
Finally, if there are any entries in the pm_vt_switch_list<\/code>, then we\ncheck to see if any of them require a VT switch.<\/p>\n\n
Only if none of these conditions apply, then we return false.<\/p>\n\n
If a VT switch is in fact required, then we move first the currently active\nvirtual terminal\/console10<\/a><\/sup> (vt_move_to_console<\/code>)\nand then the current location of kernel messages (vt_kmsg_redirect<\/code>)\nto the SUSPEND_CONSOLE<\/code>.\nThe SUSPEND_CONSOLE<\/code> is the last entry in the list of possible\nconsoles, and appears to just be a black hole to throw away messages.<\/p>\n\n
kernel\/power\/console.c:16<\/a><\/p>\n
#define SUSPEND_CONSOLE\t(MAX_NR_CONSOLES-1)\n<\/code><\/pre><\/div><\/div>\n\n
Interestingly, these are separate functions because you can use\nTIOCL_SETKMSGREDIRECT<\/code> (an ioctl<\/code>11<\/a><\/sup>) to send kernel messages to a specific virtual terminal,\nbut by default its the same as the currently active console.<\/p>\n\n
The locations of the previously active console and the previous kernel\nmessages location are stored in orig_fgconsole<\/code> and orig_kmsg<\/code>, to\nrestore the state of the console and kernel messages after the machine wakes\nup again.\nInterestingly, this means orig_fgconsole<\/code> also ends up storing any errors,\nso has to be checked to ensure it\u2019s not less than zero before we try to do\nanything with the kernel messages on both suspend and resume.<\/p>\n\n
drivers\/tty\/vt\/vt_ioctl.c:1268<\/a><\/p>\n
\/* Perform a kernel triggered VT switch for suspend\/resume *\/\n\nstatic int disable_vt_switch;\n\nint vt_move_to_console(unsigned int vt, int alloc)\n{\n\tint prev;\n\n\tconsole_lock();\n\t\/* Graphics mode - up to X *\/\n\tif (disable_vt_switch) {\n\t\tconsole_unlock();\n\t\treturn 0;\n\t}\n\tprev = fg_console;\n\n\tif (alloc && vc_allocate(vt)) {\n\t\t\/* we can't have a free VC for now. Too bad,\n\t\t * we don't want to mess the screen for now. *\/\n\t\tconsole_unlock();\n\t\treturn -ENOSPC;\n\t}\n\n\tif (set_console(vt)) {\n\t\t\/*\n\t\t * We're unable to switch to the SUSPEND_CONSOLE.\n\t\t * Let the calling function know so it can decide\n\t\t * what to do.\n\t\t *\/\n\t\tconsole_unlock();\n\t\treturn -EIO;\n\t}\n\tconsole_unlock();\n\tif (vt_waitactive(vt + 1)) {\n\t\tpr_debug(\"Suspend: Can't switch VCs.\");\n\t\treturn -EINTR;\n\t}\n\treturn prev;\n}\n<\/code><\/pre><\/div><\/div>\n\n
Unlike most other locking functions we\u2019ve seen so far, console_lock<\/code>\nneeds to be careful to ensure nothing else is panicking and needs to\ndump to the console before grabbing the semaphore for the console\nand setting a couple flags.<\/p>\n\n
Panics<\/h4>\n
Panics are tracked via an atomic integer set to the id of the processor\ncurrently panicking.<\/p>\n\n
kernel\/printk\/printk.c:2649<\/a><\/p>\n
\/**\n * console_lock - block the console subsystem from printing\n *\n * Acquires a lock which guarantees that no consoles will\n * be in or enter their write() callback.\n *\n * Can sleep, returns nothing.\n *\/\nvoid console_lock(void)\n{\n\tmight_sleep();\n\n\t\/* On panic, the console_lock must be left to the panic cpu. *\/\n\twhile (other_cpu_in_panic())\n\t\tmsleep(1000);\n\n\tdown_console_sem();\n\tconsole_locked = 1;\n\tconsole_may_schedule = 1;\n}\nEXPORT_SYMBOL(console_lock);\n<\/code><\/pre><\/div><\/div>\n\n
kernel\/printk\/printk.c:362<\/a><\/p>\n
\/*\n * Return true if a panic is in progress on a remote CPU.\n *\n * On true, the local CPU should immediately release any printing resources\n * that may be needed by the panic CPU.\n *\/\nbool other_cpu_in_panic(void)\n{\n\treturn (panic_in_progress() && !this_cpu_in_panic());\n}\n<\/code><\/pre><\/div><\/div>\n\n
kernel\/printk\/printk.c:345<\/a><\/p>\n
static bool panic_in_progress(void)\n{\n\treturn unlikely(atomic_read(&panic_cpu) != PANIC_CPU_INVALID);\n}\n<\/code><\/pre><\/div><\/div>\n\n
kernel\/printk\/printk.c:350<\/a><\/p>\n
\/* Return true if a panic is in progress on the current CPU. *\/\nbool this_cpu_in_panic(void)\n{\n\t\/*\n\t * We can use raw_smp_processor_id() here because it is impossible for\n\t * the task to be migrated to the panic_cpu, or away from it. If\n\t * panic_cpu has already been set, and we're not currently executing on\n\t * that CPU, then we never will be.\n\t *\/\n\treturn unlikely(atomic_read(&panic_cpu) == raw_smp_processor_id());\n}\n<\/code><\/pre><\/div><\/div>\n\n
console_locked<\/code> is a debug value, used to indicate that the lock should be\nheld, and our first indication that this whole virtual terminal system is\nmore complex than might initially be expected.<\/p>\n\n
kernel\/printk\/printk.c:373<\/a><\/p>\n
\/*\n * This is used for debugging the mess that is the VT code by\n * keeping track if we have the console semaphore held. It's\n * definitely not the perfect debug tool (we don't know if _WE_\n * hold it and are racing, but it helps tracking those weird code\n * paths in the console code where we end up in places I want\n * locked without the console semaphore held).\n *\/\nstatic int console_locked;\n<\/code><\/pre><\/div><\/div>\n\n
console_may_schedule<\/code> is used to see if we are permitted to sleep\nand schedule other work while we hold this lock.\nAs we\u2019ll see later, the virtual terminal subsystem is not re-entrant,\nso there\u2019s all sorts of hacks in here to ensure we don\u2019t leave important\ncode sections that can\u2019t be safely resumed.<\/p>\n\n
Disable VT Switch<\/h4>\n
As the comment below lays out, when another program is handling graphical\ndisplay anyway, there\u2019s no need to do any of this, so the kernel provides\na switch to turn the whole thing off.\nInterestingly, this appears to only be used by three drivers,\nso the specific hardware support required must not be particularly common.<\/p>\n
drivers\/gpu\/drm\/omapdrm\/dss\ndrivers\/video\/fbdev\/geode\ndrivers\/video\/fbdev\/omap2\n<\/code><\/pre><\/div><\/div>\n\n
drivers\/tty\/vt\/vt_ioctl.c:1308<\/a><\/p>\n
\/*\n * Normally during a suspend, we allocate a new console and switch to it.\n * When we resume, we switch back to the original console.  This switch\n * can be slow, so on systems where the framebuffer can handle restoration\n * of video registers anyways, there's little point in doing the console\n * switch.  This function allows you to disable it by passing it '0'.\n *\/\nvoid pm_set_vt_switch(int do_switch)\n{\n\tconsole_lock();\n\tdisable_vt_switch = !do_switch;\n\tconsole_unlock();\n}\nEXPORT_SYMBOL(pm_set_vt_switch);\n<\/code><\/pre><\/div><\/div>\n\n
The rest of the vt_switch_console<\/code> function is pretty normal,\nhowever, simply allocating space if needed to create the requested\nvirtual terminal\nand then setting the current virtual terminal via set_console<\/code>.<\/p>\n\n
Virtual Terminal Set Console<\/h4>\n
With set_console<\/code>, we begin (as if we haven\u2019t been already) to enter the\nmadness that is the virtual terminal subsystem.\nAs mentioned previously, modifications to its state must be made very\ncarefully, as other stuff happening at the same time could create complete\nmesses.<\/p>\n\n
All this to say, calling set_console<\/code> does not actually perform any\nwork to change the state of the current console.\nInstead it indicates what changes it wants and then schedules that work.<\/p>\n\n
drivers\/tty\/vt\/vt.c:3153<\/a><\/p>\n
int set_console(int nr)\n{\n\tstruct vc_data *vc = vc_cons[fg_console].d;\n\n\tif (!vc_cons_allocated(nr) || vt_dont_switch ||\n\t\t(vc->vt_mode.mode == VT_AUTO && vc->vc_mode == KD_GRAPHICS)) {\n\n\t\t\/*\n\t\t * Console switch will fail in console_callback() or\n\t\t * change_console() so there is no point scheduling\n\t\t * the callback\n\t\t *\n\t\t * Existing set_console() users don't check the return\n\t\t * value so this shouldn't break anything\n\t\t *\/\n\t\treturn -EINVAL;\n\t}\n\n\twant_console = nr;\n\tschedule_console_callback();\n\n\treturn 0;\n}\n<\/code><\/pre><\/div><\/div>\n\n
The check for vc->vc_mode == KD_GRAPHICS<\/code> is where most end-user graphical\ndesktops will bail out of this change, as they\u2019re in graphics mode and don\u2019t\nneed to switch away to the suspend console.<\/p>\n\n
vt_dont_switch<\/code> is a flag used by the ioctl<\/code>s11<\/a><\/sup> VT_LOCKSWITCH<\/code> and\nVT_UNLOCKSWITCH<\/code> to prevent the system from switching virtual terminal\ndevices when the user has explicitly locked it.<\/p>\n\n
VT_AUTO<\/code> is a flag indicating that automatic virtual terminal switching is enabled12<\/a><\/sup>,\nand thus deliberate switching to a suspend terminal is not required.<\/p>\n\n
However, if you do run your machine from a virtual terminal, then we\nindicate to the system that we want to change to the requested virtual terminal\nvia the want_console<\/code> variable\nand schedule a callback via schedule_console_callback<\/code>.<\/p>\n\n
drivers\/tty\/vt\/vt.c:315<\/a><\/p>\n
void schedule_console_callback(void)\n{\n\tschedule_work(&console_work);\n}\n<\/code><\/pre><\/div><\/div>\n\n
console_work<\/code> is a workqueue2<\/a><\/sup> that will execute the given task asynchronously.<\/p>\n\n
Console Callback<\/h4>\n
drivers\/tty\/vt\/vt.c:3109<\/a><\/p>\n
\/*\n * This is the console switching callback.\n *\n * Doing console switching in a process context allows\n * us to do the switches asynchronously (needed when we want\n * to switch due to a keyboard interrupt).  Synchronization\n * with other console code and prevention of re-entrancy is\n * ensured with console_lock.\n *\/\nstatic void console_callback(struct work_struct *ignored)\n{\n\tconsole_lock();\n\n\tif (want_console >= 0) {\n\t\tif (want_console != fg_console &&\n\t\t    vc_cons_allocated(want_console)) {\n\t\t\thide_cursor(vc_cons[fg_console].d);\n\t\t\tchange_console(vc_cons[want_console].d);\n\t\t\t\/* we only changed when the console had already\n\t\t\t   been allocated - a new console is not created\n\t\t\t   in an interrupt routine *\/\n\t\t}\n\t\twant_console = -1;\n\t}\n...\n<\/code><\/pre><\/div><\/div>\n\n
console_callback<\/code> first looks to see if there is a console change wanted\nvia want_console<\/code> and then changes to it if it\u2019s not the current console and\nhas been allocated already.\nWe do first remove any cursor state with hide_cursor<\/code>.<\/p>\n\n
drivers\/tty\/vt\/vt.c:841<\/a><\/p>\n
static void hide_cursor(struct vc_data *vc)\n{\n\tif (vc_is_sel(vc))\n\t\tclear_selection();\n\n\tvc->vc_sw->con_cursor(vc, false);\n\thide_softcursor(vc);\n}\n<\/code><\/pre><\/div><\/div>\n\n
A full dive into the tty<\/code> driver is a task for another time, but this\nshould give a general sense of how this system interacts with hibernation.<\/p>\n\n
Notify Power Management Call Chain<\/h3>\n
kernel\/power\/hibernate.c:767<\/a><\/p>\n
pm_notifier_call_chain_robust(PM_HIBERNATION_PREPARE, PM_POST_HIBERNATION)\n<\/code><\/pre><\/div><\/div>\n\n
This will call a chain of power management callbacks, passing first\nPM_HIBERNATION_PREPARE<\/code> and then PM_POST_HIBERNATION<\/code> on startup or\non error with another callback.<\/p>\n\n
kernel\/power\/main.c:98<\/a><\/p>\n
int pm_notifier_call_chain_robust(unsigned long val_up, unsigned long val_down)\n{\n\tint ret;\n\n\tret = blocking_notifier_call_chain_robust(&pm_chain_head, val_up, val_down, NULL);\n\n\treturn notifier_to_errno(ret);\n}\n<\/code><\/pre><\/div><\/div>\n
The power management notifier is a blocking notifier chain, which means it\nhas the following properties.<\/p>\n\n
include\/linux\/notifier.h:23<\/a><\/p>\n
 *\tBlocking notifier chains: Chain callbacks run in process context.\n *\t\tCallouts are allowed to block.\n<\/code><\/pre><\/div><\/div>\n
The callback chain is a linked list with each entry containing a priority\nand a function to call. The function technically takes in a data value,\nbut it is always NULL<\/code> for the power management chain.<\/p>\n\n
include\/linux\/notifier.h:49<\/a><\/p>\n
struct notifier_block;\n\ntypedef\tint (*notifier_fn_t)(struct notifier_block *nb,\n\t\t\tunsigned long action, void *data);\n\nstruct notifier_block {\n\tnotifier_fn_t notifier_call;\n\tstruct notifier_block __rcu *next;\n\tint priority;\n};\n<\/code><\/pre><\/div><\/div>\n\n
The head of the linked list is protected by a read-write semaphore.<\/p>\n\n
include\/linux\/notifier.h:65<\/a><\/p>\n
struct blocking_notifier_head {\n\tstruct rw_semaphore rwsem;\n\tstruct notifier_block __rcu *head;\n};\n<\/code><\/pre><\/div><\/div>\n\n
Because it is prioritized, appending to the list requires walking it until\nan item with lower13<\/a><\/sup> priority is found to insert the current item before.<\/p>\n\n
kernel\/notifier.c:252<\/a><\/p>\n
\/*\n *\tBlocking notifier chain routines.  All access to the chain is\n *\tsynchronized by an rwsem.\n *\/\n\nstatic int __blocking_notifier_chain_register(struct blocking_notifier_head *nh,\n\t\t\t\t\t      struct notifier_block *n,\n\t\t\t\t\t      bool unique_priority)\n{\n\tint ret;\n\n\t\/*\n\t * This code gets used during boot-up, when task switching is\n\t * not yet working and interrupts must remain disabled.  At\n\t * such times we must not call down_write().\n\t *\/\n\tif (unlikely(system_state == SYSTEM_BOOTING))\n\t\treturn notifier_chain_register(&nh->head, n, unique_priority);\n\n\tdown_write(&nh->rwsem);\n\tret = notifier_chain_register(&nh->head, n, unique_priority);\n\tup_write(&nh->rwsem);\n\treturn ret;\n}\n<\/code><\/pre><\/div><\/div>\n\n
kernel\/notifier.c:20<\/a><\/p>\n
\/*\n *\tNotifier chain core routines.  The exported routines below\n *\tare layered on top of these, with appropriate locking added.\n *\/\n\nstatic int notifier_chain_register(struct notifier_block **nl,\n\t\t\t\t   struct notifier_block *n,\n\t\t\t\t   bool unique_priority)\n{\n\twhile ((*nl) != NULL) {\n\t\tif (unlikely((*nl) == n)) {\n\t\t\tWARN(1, \"notifier callback %ps already registered\",\n\t\t\t     n->notifier_call);\n\t\t\treturn -EEXIST;\n\t\t}\n\t\tif (n->priority > (*nl)->priority)\n\t\t\tbreak;\n\t\tif (n->priority == (*nl)->priority && unique_priority)\n\t\t\treturn -EBUSY;\n\t\tnl = &((*nl)->next);\n\t}\n\tn->next = *nl;\n\trcu_assign_pointer(*nl, n);\n\ttrace_notifier_register((void *)n->notifier_call);\n\treturn 0;\n}\n<\/code><\/pre><\/div><\/div>\n\n
Each callback can return one of a series of options.<\/p>\n\n
include\/linux\/notifier.h:18<\/a><\/p>\n
#define NOTIFY_DONE\t\t0x0000\t\t\/* Don't care *\/\n#define NOTIFY_OK\t\t0x0001\t\t\/* Suits me *\/\n#define NOTIFY_STOP_MASK\t0x8000\t\t\/* Don't call further *\/\n#define NOTIFY_BAD\t\t(NOTIFY_STOP_MASK|0x0002)\n\t\t\t\t\t\t\/* Bad\/Veto action *\/\n<\/code><\/pre><\/div><\/div>\n\n
When notifying the chain, if a function returns STOP<\/code> or BAD<\/code> then\nthe previous parts of the chain are called again with PM_POST_HIBERNATION<\/code>14<\/a><\/sup>\nand an error is returned.<\/p>\n\n
kernel\/notifier.c:107<\/a><\/p>\n
\/**\n * notifier_call_chain_robust - Inform the registered notifiers about an event\n *                              and rollback on error.\n * @nl:\t\tPointer to head of the blocking notifier chain\n * @val_up:\tValue passed unmodified to the notifier function\n * @val_down:\tValue passed unmodified to the notifier function when recovering\n *              from an error on @val_up\n * @v:\t\tPointer passed unmodified to the notifier function\n *\n * NOTE:\tIt is important the @nl chain doesn't change between the two\n *\t\tinvocations of notifier_call_chain() such that we visit the\n *\t\texact same notifier callbacks; this rules out any RCU usage.\n *\n * Return:\tthe return value of the @val_up call.\n *\/\nstatic int notifier_call_chain_robust(struct notifier_block **nl,\n\t\t\t\t     unsigned long val_up, unsigned long val_down,\n\t\t\t\t     void *v)\n{\n\tint ret, nr = 0;\n\n\tret = notifier_call_chain(nl, val_up, v, -1, &nr);\n\tif (ret & NOTIFY_STOP_MASK)\n\t\tnotifier_call_chain(nl, val_down, v, nr-1, NULL);\n\n\treturn ret;\n}\n<\/code><\/pre><\/div><\/div>\n\n
Each of these callbacks tends to be quite driver-specific, so we\u2019ll cease\ndiscussion of this here.<\/p>\n\n
Sync Filesystems<\/h3>\n
The next step is to ensure all filesystems have been synchronized to disk.<\/p>\n\n
This is performed via a simple helper function that times how long the full\nsynchronize operation, ksys_sync<\/code> takes.<\/p>\n\n
kernel\/power\/main.c:69<\/a><\/p>\n
void ksys_sync_helper(void)\n{\n\tktime_t start;\n\tlong elapsed_msecs;\n\n\tstart = ktime_get();\n\tksys_sync();\n\telapsed_msecs = ktime_to_ms(ktime_sub(ktime_get(), start));\n\tpr_info(\"Filesystems sync: %ld.%03ld seconds\\n\",\n\t\telapsed_msecs \/ MSEC_PER_SEC, elapsed_msecs % MSEC_PER_SEC);\n}\nEXPORT_SYMBOL_GPL(ksys_sync_helper);\n<\/code><\/pre><\/div><\/div>\n\n
ksys_sync<\/code> wakes and instructs a set of flusher threads to write out\nevery filesystem, first their inodes15<\/a><\/sup>, then the full filesystem, and\nthen finally all block devices, to ensure all pages are written out\nto disk.<\/p>\n\n
fs\/sync.c:87<\/a><\/p>\n
\/*\n * Sync everything. We start by waking flusher threads so that most of\n * writeback runs on all devices in parallel. Then we sync all inodes reliably\n * which effectively also waits for all flusher threads to finish doing\n * writeback. At this point all data is on disk so metadata should be stable\n * and we tell filesystems to sync their metadata via ->sync_fs() calls.\n * Finally, we writeout all block devices because some filesystems (e.g. ext2)\n * just write metadata (such as inodes or bitmaps) to block device page cache\n * and do not sync it on their own in ->sync_fs().\n *\/\nvoid ksys_sync(void)\n{\n\tint nowait = 0, wait = 1;\n\n\twakeup_flusher_threads(WB_REASON_SYNC);\n\titerate_supers(sync_inodes_one_sb, NULL);\n\titerate_supers(sync_fs_one_sb, &nowait);\n\titerate_supers(sync_fs_one_sb, &wait);\n\tsync_bdevs(false);\n\tsync_bdevs(true);\n\tif (unlikely(laptop_mode))\n\t\tlaptop_sync_completion();\n}\n<\/code><\/pre><\/div><\/div>\n\n
It follows an interesting pattern of using iterate_supers<\/code> to run both\nsync_inodes_one_sb<\/code> and then sync_fs_one_sb<\/code> on each known filesystem16<\/a><\/sup>.\nIt also calls both sync_fs_one_sb<\/code> and sync_bdevs<\/code> twice, first without waiting\nfor any operations to complete and then again waiting for completion17<\/a><\/sup>.<\/p>\n\n
When laptop_mode<\/code> is enabled the system runs additional filesystem synchronization\noperations after the specified delay without any writes.<\/p>\n\n
mm\/page-writeback.c:111<\/a><\/p>\n
\/*\n * Flag that puts the machine in \"laptop mode\". Doubles as a timeout in jiffies:\n * a full sync is triggered after this time elapses without any disk activity.\n *\/\nint laptop_mode;\n\nEXPORT_SYMBOL(laptop_mode);\n<\/code><\/pre><\/div><\/div>\n\n
However, when running a filesystem synchronization operation, the system will\nadd an additional timer to schedule more writes after the laptop_mode<\/code> delay.\nWe don\u2019t want the state of the system to change at all while performing\nhibernation, so we cancel those timers.<\/p>\n\n
mm\/page-writeback.c:2198<\/a><\/p>\n
\/*\n * We're in laptop mode and we've just synced. The sync's writes will have\n * caused another writeback to be scheduled by laptop_io_completion.\n * Nothing needs to be written back anymore, so we unschedule the writeback.\n *\/\nvoid laptop_sync_completion(void)\n{\n\tstruct backing_dev_info *bdi;\n\n\trcu_read_lock();\n\n\tlist_for_each_entry_rcu(bdi, &bdi_list, bdi_list)\n\t\tdel_timer(&bdi->laptop_mode_wb_timer);\n\n\trcu_read_unlock();\n}\n<\/code><\/pre><\/div><\/div>\n\n
As a side note, the ksys_sync<\/code> function is simply called when the\nsystem call sync<\/code> is used.<\/p>\n\n
fs\/sync.c:111<\/a><\/p>\n
SYSCALL_DEFINE0(sync)\n{\n\tksys_sync();\n\treturn 0;\n}\n<\/code><\/pre><\/div><\/div>\n\n
The End of Preparation<\/h2>\n
With that the system has finished preparations for hibernation.\nThis is a somewhat arbitrary cutoff, but next the system will begin\na full freeze of userspace to then dump memory out to an image and finally\nto perform hibernation. All this will be covered in future articles!<\/p>\n
\n  
    \n    
  1. \n      
    Hibernation modes are outside of scope for this article, see the previous article<\/a> for a high-level description of the different types of hibernation.\u00a0↩<\/a><\/p>\n    <\/li>\n    
  2. \n      
    Workqueues are a mechanism for running asynchronous tasks. A full description of them is a task for another time, but the kernel documentation on them is available here: https:\/\/www.kernel.org\/doc\/html\/v6.9\/core-api\/workqueue.html<\/a>\u00a0↩<\/a>\u00a0↩2<\/sup><\/a><\/p>\n    <\/li>\n    
  3. \n      
    This is a bit of an oversimplification, but since this isn\u2019t the main focus of this article this description has been kept to a higher level.\u00a0↩<\/a><\/p>\n    <\/li>\n    
  4. \n      
    Kconfig is Linux\u2019s build configuration system that sets many different macros to enable\/disable various features.\u00a0↩<\/a><\/p>\n    <\/li>\n    
  5. \n      
    Kconfig defaults to the first default found<\/a>\u00a0↩<\/a><\/p>\n    <\/li>\n    
  6. \n      
    Including checking whether the algorithm is larval? Which appears to indicate that it requires additional setup, but is an interesting choice of name for such a state.\u00a0↩<\/a><\/p>\n    <\/li>\n    
  7. \n      
    Specifically when we get to process freezing, which we\u2019ll get to in the next article in this series.\u00a0↩<\/a><\/p>\n    <\/li>\n    
  8. \n      
    Swap space is outside the scope of this article, but in short it is a buffer on disk that the kernel uses to store memory not current in use to free up space for other things. See Swap Management<\/a> for more details.\u00a0↩<\/a><\/p>\n    <\/li>\n    
  9. \n      
    The code for this is lengthy and tangential, thus it has not been included here. If you\u2019re curious about the details of this, see kernel\/power\/hibernate.c:858<\/a> for the details of hibernate_quiet_exec<\/code>, and drivers\/nvdimm\/core.c:451<\/a> for how it is used in nvdimm<\/code>.\u00a0↩<\/a><\/p>\n    <\/li>\n    
  10. \n      
    Annoyingly this code appears to use the terms \u201cconsole\u201d and \u201cvirtual terminal\u201d interchangeably.\u00a0↩<\/a><\/p>\n    <\/li>\n    
  11. \n      
    ioctl<\/code>s are special device-specific I\/O operations that permit performing actions outside of the standard file interactions of read\/write\/seek\/etc.\u00a0↩<\/a>\u00a0↩2<\/sup><\/a><\/p>\n    <\/li>\n    
  12. \n      
    I\u2019m not entirely clear on how this flag works, this subsystem is particularly complex.\u00a0↩<\/a><\/p>\n    <\/li>\n    
  13. \n      
    In this case a higher number is higher priority.\u00a0↩<\/a><\/p>\n    <\/li>\n    
  14. \n      
    Or whatever the caller passes as val_down<\/code>, but in this case we\u2019re specifically looking at how this is used in hibernation.\u00a0↩<\/a><\/p>\n    <\/li>\n    
  15. \n      
    An inode refers to a particular file or directory within the filesystem. See Wikipedia<\/a> for more details.\u00a0↩<\/a><\/p>\n    <\/li>\n    
  16. \n      
    Each active filesystem is registed with the kernel through a structure known as a superblock, which contains references to all the inodes contained within the filesystem, as well as function pointers to perform the various required operations, like sync.\u00a0↩<\/a><\/p>\n    <\/li>\n    
  17. \n      
    I\u2019m including minimal code in this section, as I\u2019m not looking to deep dive into the filesystem code at this time.\u00a0↩<\/a><\/p>\n    <\/li>\n  <\/ol>\n<\/div>\n","pubDate":"Sun, 08 Sep 2024 00:00:00 +0000","link":"https:\/\/tookmund.com\/2024\/09\/hibernation-preparation","guid":"https:\/\/tookmund.com\/2024\/09\/hibernation-preparation","category":"hibernate"},{"title":"What to Do When You Forget Your Root Password","description":"
    Forgetting your root password would initially seem like a problem requiring\na full re-install, one that you can\u2019t easily recover from without wiping\neverything away.<\/p>\n\n
    Forgetting your user password can of course be solved by changing it as root,\nas in the following, which changes the password for user jacob<\/code>:<\/p>\n
    # passwd jacob\n<\/code><\/pre><\/div><\/div>\n
    but only the root<\/code> user can change their own password,\nso you need to somehow get root<\/code> access in order to do so.<\/p>\n\n
    Changing Root\u2019s Password with Sudo<\/h2>\n
    This one is probably obvious, but if you have a user with the ability to use\nsudo<\/code>, then you can change root<\/code>\u2019s password without access to the root<\/code>\naccount by running:<\/p>\n
    $ sudo passwd\n<\/code><\/pre><\/div><\/div>\n
    which will reset the password for the root<\/code> account without requiring the\nexisting password.<\/p>\n\n
    Boot Directly to a Shell<\/h2>\n\n
    Getting root<\/code> access to any Linux machine you have physical access to\nis surprisingly simple.\nYou can just boot the machine directly into a root<\/code> shell without any access\ncontrol, i.e. passwords.<\/p>\n\n
    Why You Should Always Encrypt Your Storage1<\/a><\/sup><\/h3>\n\n
    To boot directly to a shell you need to append the following text to\nthe kernel command line<\/a>:<\/p>\n
    init=\/bin\/sh\n<\/code><\/pre><\/div><\/div>\n
    (You could use pretty much any program here, but you\u2019re putting your system into a weird state doing this, and so I\u2019d recommend the simplest approach.)<\/p>\n\n
    GRUB<\/h3>\n\n
    GRUB will allow you to edit boot parameters on startup using the e<\/code>\nkey. You\u2019ll then be presented with a editor2<\/a><\/sup> that you can\nuse to change the kernel command line by appending to the linux<\/code> line.<\/p>\n\n
    E.g. If your editor looks like this:<\/p>\n
            load_video\n        insmod gzio\n        if [ x$grub_platform = xxen ]; then insmod xzio; insmod lzopio; fi\n        insmod part_gpt\n        insmod ext2\n        search --no-floppy --fs-uuid --set=root abcd1234-5678-0910-1112-abcd12345678\n        echo    'Loading Linux 6.1.0-21-amd64 ...'\n        linux   \/boot\/vmlinuz-6.1.0-21-amd64 root=UUID=abcd1234-5678-0910-1112-abcd12345678 ro  quiet\n        echo    'Loading initial ramdisk ...'\n        initrd  \/boot\/initrd.img-6.1.0-21-amd64\n<\/code><\/pre><\/div><\/div>\n
    Then you would add init=\/bin\/sh<\/code> like so:<\/p>\n
            load_video\n        insmod gzio\n        if [ x$grub_platform = xxen ]; then insmod xzio; insmod lzopio; fi\n        insmod part_gpt\n        insmod ext2\n        search --no-floppy --fs-uuid --set=root abcd1234-5678-0910-1112-abcd12345678\n        echo    'Loading Linux 6.1.0-21-amd64 ...'\n        linux   \/boot\/vmlinuz-6.1.0-21-amd64 root=UUID=abcd1234-5678-0910-1112-abcd12345678 ro  quiet init=\/bin\/sh\n        echo    'Loading initial ramdisk ...'\n        initrd  \/boot\/initrd.img-6.1.0-21-amd64\n<\/code><\/pre><\/div><\/div>\n\n
    Once you\u2019ve edited it you can start your machine with Ctrl+x<\/code>, as you can\nsee from the prompt text under the editor.<\/p>\n\n
    Raspberry Pi cmdline.txt<\/code><\/h3>\n
    On a Raspberry Pi you\u2019ll want to append the above to only line of the\ncmdline.txt<\/code> file on the boot partition of the SD card.\nThis is the first partition of the disk, the one that is FAT32<\/code>.<\/p>\n\n
    You\u2019ll need to do this on another machine, since if you had root<\/code> access\nto edit cmdline.txt<\/code> you could also just change your password.<\/p>\n\n
    As it is a FAT32<\/code> partition on an SD card, it should be editable on any other\nmachine that supports SD cards.<\/p>\n\n
    E.g. If your cmdline.txt<\/code> looks like this<\/p>\n
    console=serial0,115200 console=tty1 root=PARTUUID=fb33757d-02 rootfstype=ext4 fsck.repair=yes rootwait quiet\n<\/code><\/pre><\/div><\/div>\n
    Then you would add init=\/bin\/sh<\/code> like so:<\/p>\n
    console=serial0,115200 console=tty1 root=PARTUUID=fb33757d-02 rootfstype=ext4 fsck.repair=yes rootwait quiet init=\/bin\/sh\n<\/code><\/pre><\/div><\/div>\n\n
    Mount Read \/ Write<\/h2>\n\n
    Since you\u2019re replacing the init process<\/a>\nof the machine with a shell, no other processes will be running.<\/p>\n\n
    Also, your root filesystem will be mounted read-only,\nas init<\/code> is expected to remount it read-write as needed.<\/p>\n
    # mount -o remount,rw \/\n<\/code><\/pre><\/div><\/div>\n\n
    Change Root Password<\/h2>\n\n
    Once you\u2019ve remounted the root filesystem, all that\u2019s needed is to\nrun the passwd<\/code> command.<\/p>\n
    # passwd\n<\/code><\/pre><\/div><\/div>\n
    Since you\u2019re running the command as root<\/code> you won\u2019t need to provide your\nexisting password, and will only need to type a new password twice.<\/p>\n\n
    Now of course you simply need to remember that password in order to\nensure you don\u2019t need to do this again.<\/p>\n\n
    Reboot Safely<\/h2>\n\n
    You now cannot follow the standard reboot process here, as you\u2019re only running\none process.<\/p>\n\n
    Therefore it\u2019s important to put your root filesystem back into read-only before\npowering off your machine:<\/p>\n
    # mount -o remount,ro \/\n<\/code><\/pre><\/div><\/div>\n\n
    Once you\u2019ve done that you just need to hold down the power button until the\nmachine completely powers off or pull the plug.<\/p>\n\n
    And then you\u2019re done! Boot the computer again and you\u2019ll have everything\nworking as normal, with a root<\/code> password you remember.<\/p>\n
    \n  
      \n    
    1. \n      
      Not that this is the only reason, anyone with physical access to your machine could also boot it into another operating system they control, or just remove your storage device and put it into another computer, or probably other things I\u2019m not thinking of now. You should always encrypt your devices.\u00a0↩<\/a><\/p>\n    <\/li>\n    
    2. \n      
      The editor uses emacs-like keybindings. The manual<\/a> includes a list of all the options available.\u00a0↩<\/a><\/p>\n    <\/li>\n  <\/ol>\n<\/div>\n","pubDate":"Sun, 02 Jun 2024 00:00:00 +0000","link":"https:\/\/tookmund.com\/2024\/06\/linux-forgot-password","guid":"https:\/\/tookmund.com\/2024\/06\/linux-forgot-password","category":["raspberry pi","linux","root","password"]},{"title":"Regular Reboots","description":"
      Uptime is often considered a measure of system reliability,\nan indication that the running software is stable and can be counted on.<\/p>\n\n
      However, this hides the insidious build-up of state throughout the system as\nit runs, the slow drift from the expected to the strange.<\/p>\n\n
      As Nolan Lawson highlights in an excellent post entitled\nProgrammers are bad at managing state<\/a>,\nstate is the most challenging part of programming.\nIt\u2019s why \u201cdid you try turning it off and on again\u201d is a classic tech support\nresponse to any problem.<\/p>\n\n
      You: uptime

      Me: Every machine gets rebooted at 1AM to clear the slate for maintenance, and at 3:30AM to push through any pending updates.<\/p>—       @SwiftOnSecurity, December 27, 2020<\/a><\/blockquote>\n\n
      In addition to the problem of state, installing regular updates periodically\nrequires a reboot, even if the rest of the process is automated through a\ntool like unattended-upgrades<\/a>.<\/p>\n\n
      For my personal homelab, I manage a handful of different machines running\nvarious services.<\/p>\n\n
      I used to just schedule a day to update and reboot all of them, but that\ngot very tedious very quickly.<\/p>\n\n
      I then moved the reboot to a cronjob,\nand then recently to a systemd timer and service.<\/p>\n\n
      I figure that laying out my path to better management of this might help\nothers, and will almost certainly lead to someone telling me a better way\nto do this.<\/p>\n\n
      UPDATE: Turns out there\u2019s another option for better systemd cron integration.\nSee systemd-cron<\/code><\/a> below.<\/p>\n\n
      Ultimately, uptime only measures the duration since you last proved you can turn the machine on and have it boot.<\/p>— @SwiftOnSecurity, May 7, 2016<\/a><\/blockquote>\n\n
      Stage One: Reboot Cron<\/h2>\n\n
      The first, and easiest approach, is a simple cron job.\nJust adding the following line to \/var\/spool\/cron\/crontabs\/root<\/code>1<\/a><\/sup>\nis enough to get your machine to reboot once a month2<\/a><\/sup> on the 6th at 8:00 AM3<\/a><\/sup>:<\/p>\n
      0 8 6 * * reboot\n<\/code><\/pre><\/div><\/div>\n\n
      I had this configured for many years and it works well.\nBut you have no indication as to whether it succeeds except for checking\nyour uptime regularly yourself.<\/p>\n\n
      Stage Two: Reboot systemd Timer<\/h2>\n\n
      The next evolution of this approach for me was to use a systemd timer.\nI created a regular-reboot.timer<\/code> with the following contents:<\/p>\n
      [Unit]\nDescription=Reboot on a Regular Basis\n\n[Timer]\nUnit=regular-reboot.service\nOnBootSec=1month\n\n[Install]\nWantedBy=timers.target\n<\/code><\/pre><\/div><\/div>\n\n
      This timer will trigger the regular-reboot.service<\/code> systemd unit\nwhen the system reaches one month of uptime.<\/p>\n\n
      I\u2019ve seen some guides to creating timer units recommend adding\na Wants=regular-reboot.service<\/code> to the [Unit]<\/code> section,\nbut this has the consequence of running that service every time it starts the\ntimer. In this case that will just reboot your system on startup which is\nnot what you want.<\/p>\n\n
      Care needs to be taken to use the OnBootSec<\/code> directive instead of\nOnCalendar<\/code> or any of the other time specifications, as your system could\nreboot, discover its still within the expected window and reboot again.\nWith OnBootSec<\/code> your system will not have that problem.\nTechnically, this same problem could have occurred with the cronjob approach,\nbut in practice it never did, as the systems took long enough to come back\nup that they were no longer within the expected window for the job.<\/p>\n\n
      I then added the regular-reboot.service<\/code>:<\/p>\n
      [Unit]\nDescription=Reboot on a Regular Basis\nWants=regular-reboot.timer\n\n[Service]\nType=oneshot\nExecStart=shutdown -r 02:45\n<\/code><\/pre><\/div><\/div>\n\n
      You\u2019ll note that this service is actually scheduling a specific reboot time\nvia the shutdown command instead of just immediately rebooting.\nThis is a bit of a hack needed because I can\u2019t control when the timer\nruns exactly when using OnBootSec<\/code>.\nThis way different systems have different reboot times so that everything\ndoesn\u2019t just reboot and fail all at once. Were something to fail to come\nback up I would have some time to fix it, as each machine has a few hours\nbetween scheduled reboots.<\/p>\n\n
      One you have both files in place, you\u2019ll simply need to reload configuration\nand then enable and start the timer unit:<\/p>\n
      systemctl daemon-reload\nsystemctl enable --now regular-reboot.timer\n<\/code><\/pre><\/div><\/div>\n\n
      You can then check when it will fire next:<\/p>\n
      # systemctl status regular-reboot.timer\n\u25cf regular-reboot.timer - Reboot on a Regular Basis\n     Loaded: loaded (\/etc\/systemd\/system\/regular-reboot.timer; enabled; preset: enabled)\n     Active: active (waiting) since Wed 2024-03-13 01:54:52 EDT; 1 week 4 days ago\n    Trigger: Fri 2024-04-12 12:24:42 EDT; 2 weeks 4 days left\n   Triggers: \u25cf regular-reboot.service\n\nMar 13 01:54:52 dorfl systemd[1]: Started regular-reboot.timer - Reboot on a Regular Basis.\n<\/code><\/pre><\/div><\/div>\n\n
      Sidenote: Replacing all Cron Jobs with systemd Timers<\/h3>\n
      More generally, I\u2019ve now replaced all cronjobs on my personal systems with\nsystemd timer units, mostly because I can now actually track failures via\nprometheus-node-exporter<\/code>. There are plenty of ways to hack in cron support\nto the node exporter, but just moving to systemd units provides both\nsupport for tracking failure and logging,\nboth of which make system administration much easier when things inevitably\ngo wrong.<\/p>\n\n
      systemd-cron<\/code><\/h4>\n
      An alternative to converting everything by hand, if you happen to have\na lot of cronjobs is\nsystemd-cron<\/code><\/a>.\nIt will make each crontab and \/etc\/cron.*<\/code> directory into automatic\nservice and timer units.<\/p>\n\n
      Thanks to Alexandre Detiste for letting me know about this project.\nI have few enough cron jobs that I\u2019ve already converted, but\nfor anyone looking at a large number of jobs to convert\nyou\u2019ll want to check it out!<\/p>\n\n
      Stage Three: Monitor that it\u2019s working<\/h2>\n\n
      The final step here is confirm that these units actually work, beyond just\nfiring regularly.<\/p>\n\n
      I now have the following rule in my prometheus-alertmanager<\/code> rules:<\/p>\n
        - alert: UptimeTooHigh\n    expr: (time() - node_boot_time_seconds{job=\"node\"}) \/ 86400 > 35\n    annotations:\n      summary: \"Instance {{ $labels.instance }} Has Been Up Too Long!\"\n      description: \"Instance {{ $labels.instance }} Has Been Up Too Long!\"\n<\/code><\/pre><\/div><\/div>\n\n
      This will trigger an alert anytime that I have a machine up for more than 35\ndays. This actually helped me track down one machine that I had forgotten to\nset up this new unit on4<\/a><\/sup>.<\/p>\n\n
      Not everything needs to scale<\/h2>\n
      \"Is<\/p>\n\n
      One of the most common fallacies programmers fall into is that we will jump\nto automating a solution before we stop and figure out how much time it would even save.<\/p>\n\n
      In taking a slow improvement route to solve this problem for myself,\nI\u2019ve managed not to invest too much time5<\/a><\/sup> in worrying about this\nbut also achieved a meaningful improvement beyond my first approach of doing it\nall by hand.<\/p>\n\n
      \n  
        \n    
      1. \n      
        You could also add a line to \/etc\/crontab<\/code> or drop a script into \/etc\/cron.monthly<\/code> depending on your system.\u00a0↩<\/a><\/p>\n    <\/li>\n    
      2. \n      
        Why once a month? Mostly to avoid regular disruptions, but still be reasonably timely on updates.\u00a0↩<\/a><\/p>\n    <\/li>\n    
      3. \n      
        If you\u2019re looking to understand the cron time format I recommend crontab guru<\/a>.\u00a0↩<\/a><\/p>\n    <\/li>\n    
      4. \n      
        In the long term I really should set up something like ansible to automatically push fleetwide changes like this but with fewer machines than fingers this seems like overkill.\u00a0↩<\/a><\/p>\n    <\/li>\n    
      5. \n      
        Of course by now writing about it, I\u2019ve probably doubled the amount of time I\u2019ve spent thinking about this topic but oh well\u2026\u00a0↩<\/a><\/p>\n    <\/li>\n  <\/ol>\n<\/div>\n","pubDate":"Sun, 24 Mar 2024 00:00:00 +0000","link":"https:\/\/tookmund.com\/2024\/03\/regular-reboot","guid":"https:\/\/tookmund.com\/2024\/03\/regular-reboot","category":["sysadmin","systemd","cron","reboot","state"]},{"title":"AAC and Debian","description":"
        Currently, in a default installation of Debian with the GNOME desktop,\nBluetooth headphones that require the AAC codec1<\/a><\/sup> cannot be used.\nAs the Debian wiki outlines<\/a>,\nusing the AAC codec over Bluetooth, while technically supported by\nPipeWire, is explicitly disabled in Debian at this time.\nThis is because the fdk-aac<\/code> library needed to enable this support is currently\nin the non-free<\/code> component of the repository, meaning that PipeWire, which\nis in the main<\/code> component, cannot depend on it.<\/p>\n\n
        How to Fix it Yourself<\/h1>\n\n
        If what you, like me, need is simply for Bluetooth Audio to work with AAC\nin Debian\u2019s default desktop environment2<\/a><\/sup>,\nthen you\u2019ll need to rebuild the pipewire<\/code> package to include the\nAAC codec. While the current version in Debian main<\/code> has been built with AAC\ndeliberately disabled, it is trivial to enable if you can install a version\nof the fdk-aac<\/code> library.<\/p>\n\n
        I preface this with the usual caveats when it comes to patent\nand licensing controversies. I am not a lawyer, building this package and\/or\nusing it could get you into legal trouble.<\/strong><\/p>\n\n
        These instructions have only been tested on an up-to-date copy of Debian 12.<\/p>\n\n
          \n  
        1. Install pipewire<\/code>\u2019s build dependencies\n    
          sudo apt install build-essential devscripts\nsudo apt build-dep pipewire\n<\/code><\/pre><\/div>    <\/div>\n  <\/li>\n  
        2. Install libfdk-aac-dev<\/code>\n    
          sudo apt install libfdk-aac-dev\n<\/code><\/pre><\/div>    <\/div>\n    
          If the above doesn\u2019t work you\u2019ll likely need to enable non-free and try again<\/p>\n    
          sudo sed -i 's\/main\/main non-free\/g' \/etc\/apt\/sources.list\nsudo apt update\n<\/code><\/pre><\/div>    <\/div>\n    
          Alternatively, if you wish to ensure you are maximally license-compliant and\npatent un-infringing3<\/a><\/sup>,\nyou can instead build fdk-aac-free<\/code> which includes only those components\nof AAC that are known to be patent-free3<\/a><\/sup>.\nThis is what should eventually end up in Debian to resolve this problem\n(see below).<\/p>\n    
          sudo apt install git-buildpackage\nmkdir fdk-aac-source\ncd fdk-aac-source\ngit clone https:\/\/salsa.debian.org\/multimedia-team\/fdk-aac\ncd fdk-aac\ngbp buildpackage\nsudo dpkg -i ..\/libfdk-aac2_*deb ..\/libfdk-aac-dev_*deb\n<\/code><\/pre><\/div>    <\/div>\n  <\/li>\n  
        3. Get the pipewire<\/code> source code\n    
          mkdir pipewire-source\ncd pipewire-source\napt source pipewire\n<\/code><\/pre><\/div>    <\/div>\n    
          This will create a bunch of files within the pipewire-source<\/code> directory,\nbut you\u2019ll only need the pipewire-<version><\/code> folder, this contains all the\nfiles you\u2019ll need to build the package, with all the debian-specific patches\nalready applied.\nNote that you don\u2019t want to run the apt source<\/code> command as root, as it will\nthen create files that your regular user cannot edit.<\/p>\n  <\/li>\n  
        4. Fix the dependencies and build options\nTo fix up the build scripts to use the fdk-aac library,\nyou need to save the following as pipewire-source\/aac.patch<\/code>\n    
          --- debian\/control.orig\n+++ debian\/control\n@@ -40,8 +40,8 @@\n             modemmanager-dev,\n             pkg-config,\n             python3-docutils,\n-               systemd [linux-any]\n-Build-Conflicts: libfdk-aac-dev\n+               systemd [linux-any],\n+               libfdk-aac-dev\n Standards-Version: 4.6.2\n Vcs-Browser: https:\/\/salsa.debian.org\/utopia-team\/pipewire\n Vcs-Git: https:\/\/salsa.debian.org\/utopia-team\/pipewire.git\n--- debian\/rules.orig\n+++ debian\/rules\n@@ -37,7 +37,7 @@\n \t\t-Dauto_features=enabled \\\n \t\t-Davahi=enabled \\\n \t\t-Dbluez5-backend-native-mm=enabled \\\n-\t\t-Dbluez5-codec-aac=disabled \\\n+\t\t-Dbluez5-codec-aac=enabled \\\n \t\t-Dbluez5-codec-aptx=enabled \\\n \t\t-Dbluez5-codec-lc3=enabled \\\n \t\t-Dbluez5-codec-lc3plus=disabled \\\n<\/code><\/pre><\/div>    <\/div>\n    
          Then you\u2019ll need to run patch<\/code> from within the pipewire-<version><\/code> folder\ncreated by apt source<\/code>:<\/p>\n    
          patch -p0 < ..\/aac.patch\n<\/code><\/pre><\/div>    <\/div>\n  <\/li>\n  
        5. Build pipewire<\/code>\n    
          cd pipewire-*\ndebuild\n<\/code><\/pre><\/div>    <\/div>\n    
          Note that you will likely see an error from debsign<\/code> at the end of this process,\nthis is harmless, you simply don\u2019t have a GPG key set up to sign your\nnewly-built package4<\/a><\/sup>. Packages don\u2019t need to be signed to be installed,\nand debsign uses a somewhat non-standard signing process that dpkg does not\ncheck anyway.<\/p>\n  <\/li>\n<\/ol>\n\n
            \n  
          1. Install libspa-0.2-bluetooth<\/code>\n    
            sudo dpkg -i libspa-0.2-bluetooth_*.deb\n<\/code><\/pre><\/div>    <\/div>\n  <\/li>\n  
          2. Restart PipeWire and\/or Reboot\n    
            sudo reboot\n<\/code><\/pre><\/div>    <\/div>\n    
            Theoretically there\u2019s a set of services to restart here that would\nget pipewire to pick up the new library, probably just pipewire itself.\nBut it\u2019s just as easy to restart and ensure everything is using the correct\nlibrary.<\/p>\n  <\/li>\n<\/ol>\n\n
            Why<\/h1>\n\n
            This is a slightly unusual situation, as the fdk-aac<\/code> library is licensed\nunder what\neven the GNU project<\/a>\nacknowledges is a free software license.\nHowever, this license<\/a>\nexplicitly informs the user that they need to acquire\na patent license to use this software5<\/a><\/sup>:<\/p>\n\n
            \n  
            3.    NO PATENT LICENSE<\/p>\n\n  
            NO EXPRESS OR IMPLIED LICENSES TO ANY PATENT CLAIMS, including without\nlimitation the patents of Fraunhofer, ARE GRANTED BY THIS SOFTWARE LICENSE.\nFraunhofer provides no warranty of patent non-infringement with respect to this\nsoftware.\nYou may use this FDK AAC Codec software or modifications thereto only for\npurposes that are authorized by appropriate patent licenses.<\/p>\n<\/blockquote>\n\n
            To quote the GNU project:<\/p>\n
            \n  
            Because of this, and because the license author is a known patent aggressor,\nwe encourage you to be careful about using or redistributing software under\nthis license: you should first consider whether the licensor might aim to\nlure you into patent infringement.<\/p>\n<\/blockquote>\n\n
            AAC is covered by a number of patents, which expire at some point in the 2030s6<\/a><\/sup>.\nAs such the current version of the library is potentially legally dubious to ship with\nany other software, as it could be considered patent-infringing3<\/a><\/sup>.<\/p>\n\n
            Fedora\u2019s solution<\/h2>\n\n
            Since 2017, Fedora has included a modified version of the library\nas fdk-aac-free, see the announcement<\/a> and the bugzilla bug requesting review<\/a>.<\/p>\n\n
            This version of the library includes only the AAC LC profile, which is believed\nto be entirely patent-free3<\/a><\/sup>.<\/p>\n\n
            Based on this, there is an open bug report in Debian requesting that the\nfdk-aac<\/code> package be moved to the main component<\/a>\nand that the\npipwire<\/code> package be updated to build against it<\/a>.<\/p>\n\n
            The Debian NEW queue<\/h2>\n\n
            To resolve these bugs, a version of fdk-aac-free<\/code> has been uploaded to Debian\nby Jeremy Bicha.\nHowever, to make it into Debian proper, it must first pass through the\nftpmaster\u2019s NEW queue<\/a>.\nThe current version of fdk-aac-free<\/a>\nhas been in the NEW queue since July 2023.<\/p>\n\n
            Based on conversations in some of the bugs above, it\u2019s been there since at least 20227<\/a><\/sup>.<\/p>\n\n
            I hope this helps anyone stuck with AAC to get their hardware working for them\nwhile we wait for the package to eventually make it through the NEW queue.<\/p>\n\n
            Discuss on Hacker News<\/a><\/p>\n
            \n  
              \n    
            1. \n      
              Such as, for example, any Apple AirPods, which only support AAC AFAICT.\u00a0↩<\/a><\/p>\n    <\/li>\n    
            2. \n      
              Which, as of Debian 12 is GNOME 3 under Wayland with PipeWire.\u00a0↩<\/a><\/p>\n    <\/li>\n    
            3. \n      
              I\u2019m not a lawyer, I don\u2019t know what kinds of infringement might or might not be possible here, do your own research, etc.\u00a0↩<\/a>\u00a0↩2<\/sup><\/a>\u00a0↩3<\/sup><\/a>\u00a0↩4<\/sup><\/a><\/p>\n    <\/li>\n    
            4. \n      
              And if you DO have a key setup with debsign<\/code> you almost certainly don\u2019t need these instructions.\u00a0↩<\/a><\/p>\n    <\/li>\n    
            5. \n      
              This was originally phrased as \u201cexplicitly does not grant any patent rights.\u201d It was pointed out on Hacker News<\/a> that this is not exactly what it says, as it also includes a specific note that you\u2019ll need to acquire your own patent license. I\u2019ve now quoted the relevant section of the license for clarity.\u00a0↩<\/a><\/p>\n    <\/li>\n    
            6. \n      
              Wikipedia claims the \u201cbase\u201d patents expire in 2031, with the extensions expiring in 2038, but its source for these claims<\/a> is some guy\u2019s spreadsheet in a forum. The same discussion also brings up Wikipedia\u2019s claim and casts some doubt on it, so I\u2019m not entirely sure what\u2019s correct here, but I didn\u2019t feel like doing a patent deep-dive today. If someone can provide a clear answer that would be much appreciated.\u00a0↩<\/a><\/p>\n    <\/li>\n    
            7. \n      
              According to Jeremy B\u00edcha: https:\/\/bugs.debian.org\/cgi-bin\/bugreport.cgi?bug=1021370#17\u00a0↩<\/a><\/p>\n    <\/li>\n  <\/ol>\n<\/div>\n","pubDate":"Sun, 25 Feb 2024 00:00:00 +0000","link":"https:\/\/tookmund.com\/2024\/02\/aac-and-debian","guid":"https:\/\/tookmund.com\/2024\/02\/aac-and-debian","category":["debian","bluetooth","patents"]},{"title":"Fixing My Shell","description":"
              For an embarassingly long time, my shell has unnecessarily tried to\ninitialize a console font in every kind of interactive terminal.<\/p>\n\n
              This leaves the following error message in my terminal:<\/p>\n
              Couldn't get a file descriptor referring to the console.\n<\/code><\/pre><\/div><\/div>\n\n
              It even shows up twice when running tmux!<\/p>\n\n
              Clearly I\u2019ve done something horrible to my configuration,\nand now I\u2019ve got to clean it up.<\/p>\n\n
              How does Shell Initialization Work?<\/h2>\n\n
              The precise files a shell reads at start-up is somewhat complex, and defined\nby this excellent chart 1<\/a><\/sup>:<\/p>\n\n
              \"Shell<\/p>\n\n
              For the purposes of what I\u2019m trying to fix, there are two paths that matter.<\/p>\n