PMF(9)

📦 version 11.0, in nixpkgs unstable

PMF(9) 💖✨

okay so bestie, this page is from the Kernel Developer's Manual, and it's literally the lore drop for PMF — the power management and inter-driver messaging framework. It's giving kernel-driver group-chat energy: drivers register, suspend, resume, pass little messages to each other, and the system tries not to fall apart. No cap. 🫶

💖 NAME 💖

PMF, pmf_device_register, pmf_device_register1, pmf_device_deregister, pmf_device_suspend, pmf_device_resume, pmf_device_recursive_suspend, pmf_device_recursive_resume, pmf_device_resume_subtree, pmf_class_network_register, pmf_class_input_register, pmf_class_display_register, pmf_system_suspend, pmf_system_resume, pmf_system_shutdown, pmf_event_register, pmf_event_deregister, pmf_event_inject, pmf_set_platform, pmf_get_platform — power management and inter-driver messaging framework.

tiny note, bestie: the NAME list says pmf_device_resume_subtree, while the SYNOPSIS and FUNCTIONS say pmf_device_subtree_resume. I'm keeping both exactly as written — not me fixing kernel manpage typos 💅.

🔌 SYNOPSIS 🔌

#include <sys/device.h>

bool
pmf_device_register(device_t dev,
    bool (*suspend)(device_t dev, const pmf_qual_t *qual),
    bool (*resume)(device_t dev, const pmf_qual_t *qual));

bool
pmf_device_register1(device_t dev,
    bool (*suspend)(device_t dev, const pmf_qual_t *qual),
    bool (*resume)(device_t dev, const pmf_qual_t *qual),
    bool (*shutdown)(device_t dev, int how));

void
pmf_device_deregister(device_t dev);

bool
pmf_device_suspend(device_t dev, const pmf_qual_t *qual);

bool
pmf_device_resume(device_t dev, const pmf_qual_t *qual);

bool
pmf_device_recursive_suspend(device_t dev, const pmf_qual_t *qual);

bool
pmf_device_recursive_resume(device_t dev, const pmf_qual_t *qual);

bool
pmf_device_subtree_resume(device_t dev, const pmf_qual_t *qual);

void
pmf_class_network_register(device_t dev, struct ifnet *ifp);

bool
pmf_class_input_register(device_t dev);

bool
pmf_class_display_register(device_t dev);

bool
pmf_system_suspend(const pmf_qual_t *qual);

bool
pmf_system_resume(const pmf_qual_t *qual);

void
pmf_system_shutdown(int);

bool
pmf_event_register(device_t dev, pmf_generic_event_t ev,
    void (*handler)(device_t dev), bool global);

void
pmf_event_deregister(device_t dev, pmf_generic_event_t ev,
    void (*handler)(device_t dev), bool global);

bool
pmf_event_inject(device_t dev, pmf_generic_event_t ev);

bool
pmf_set_platform(const char *key, const char *value);

const char *
pmf_get_platform(const char *key);

💫 DESCRIPTION 💫

The machine-independent PMF framework is the support system for power management and inter-driver messaging for device drivers. That's the whole vibe: it handles the power-state glow-ups and lets drivers pass messages without sliding into each other's DMs. ✨

🧬 DATA TYPES 🧬

Drivers for devices implementing PMF may make use of these data types:

  • pmf_qual_t — an opaque aggregate of qualifications on a PMF suspend or resume call. It's opaque, so please don't peek, bestie. 🙈
  • pmf_generic_event_t — a device driver can register as a listener for specific events, or inject events into the message queue. The following message types are defined:
    • PMFE_DISPLAY_ON
    • PMFE_DISPLAY_REDUCED
    • PMFE_DISPLAY_STANDBY
    • PMFE_DISPLAY_SUSPEND
    • PMFE_DISPLAY_OFF
    • PMFE_DISPLAY_BRIGHTNESS_UP
    • PMFE_DISPLAY_BRIGHTNESS_DOWN
    • PMFE_AUDIO_VOLUME_UP
    • PMFE_AUDIO_VOLUME_DOWN
    • PMFE_AUDIO_VOLUME_TOGGLE
    • PMFE_CHASSIS_LID_CLOSE
    • PMFE_CHASSIS_LID_OPEN

🛠️ FUNCTIONS 🛠️

pmf_device_register(dev, suspend, resume)

Register a device with the power management framework. The suspend and resume functions are passed dev and a pmf_qual_t, and they get called when the system state changes; they should return true on success and false on failure. If either suspend or resume is NULL, then it is assumed that device state does not need to be captured and resumed on a power transition. Bus and class-level power management will still be performed.

pmf_device_register() always returns true. Callers should ignore the return value. Like, literally ignore it, bestie. 💅

pmf_device_register1(dev, suspend, resume, shutdown)

Like pmf_device_register(), but additionally registers a shutdown handler. During system shutdown, pmf_system_shutdown() calls shutdown on dev with the reboot(2) “howto” in the second argument. shutdown should return true on success and false on failure.

pmf_device_register1() always returns true. Callers should ignore the return value.

pmf_device_deregister(dev)

Deregister a device with the power management framework. Bye bestie, you're out of the framework. 👋

pmf_device_suspend(dev, qual)

Suspend a device by first calling the class suspend handler, followed by the driver suspend handler, and finally the bus suspend handler. Order matters, periodt.

pmf_device_resume(dev, qual)

Resume a device by first calling the bus resume handler, followed by the driver resume handler, and finally the class resume handler.

pmf_device_recursive_suspend(dev, qual)

As pmf_device_suspend(), but ensures that all child devices of dev are suspended.

pmf_device_recursive_resume(dev, qual)

As pmf_device_resume(), but ensures that all parent devices of dev are resumed. Yes, parent — not child — that's what the page says. 👑

pmf_device_subtree_resume(dev, qual)

As pmf_device_resume(), but ensures that all child devices of dev are resumed.

pmf_class_network_register(dev, ifp)

Register a device with the power management framework as a network-class device. That's the ifp one. 🌐

pmf_class_input_register(dev)

Register a device with the power management framework as an input-class device.

pmf_class_display_register(dev)

Register a device with the power management framework as a display-class device.

pmf_system_suspend(qual)

Suspend all attached devices. Devices are suspended by traversing the autoconfiguration tree beginning with the leaf nodes. This function will fail if any attached drivers do not support the power management framework. So yeah, no cap: unsupported drivers are a whole mood killer. 😭

pmf_system_resume(qual)

Resume all attached devices. Devices are resumed by traversing the autoconfiguration tree beginning with devices that do not have a parent. This function will fail if any attached drivers do not support the power management framework.

pmf_system_shutdown(int)

Shutdown all attached devices. Devices are shut down by traversing the autoconfiguration tree beginning with the leaf nodes. The integer argument is passed to the driver shutdown functions. It should contain the reboot(2) “howto” argument. This function ignores the presence of attached drivers that do not support the power management framework. So unlike suspend/resume, this one is lowkey unbothered by the non-PMF girlies. 💀

pmf_event_register(dev, ev, handler, global)

Register the callback handler to be called whenever an ev event is triggered. If global is true, handler accepts anonymous events from pmf_event_inject().

pmf_event_deregister(dev, ev, handler, global)

Deregister the callback previously registered with pmf_event_register().

pmf_event_inject(dev, ev)

Inject an inter-driver message into the message queue. If dev is NULL, the event is considered to be anonymous and one or more drivers may handle this event; otherwise the event is delivered directly to the callback registered by dev.

pmf_set_platform(key, value)

Insert a name-value pair into the platform information database.

pmf_get_platform(key)

Retrieve the value for key from the platform information database. Returns NULL if the key is not present.

📚 CODE REFERENCES 📚

The power management framework is implemented within the files sys/sys/pmf.h, sys/sys/device.h, sys/kern/kern_pmf.c, and sys/kern/subr_autoconf.c. Go read them if you want the director's cut. 🎬

👀 SEE ALSO 👀

🕰️ HISTORY 🕰️

The PMF framework appeared in NetBSD 5.0. It's been iconic for a minute. ⭐

💌 AUTHORS 💌

  • Jared D. McNeill <jmcneill@NetBSD.org>
  • Joerg Sonnenberger <joerg@NetBSD.org>

🐛 BUGS 🐛

okay so this is the messy part: pmf_device_register() and pmf_device_register1() never fail and should return void, but until all callers are updated to ignore the return value, they must continue to return bool: PR kern/57575: https://gnats.NetBSD.org/57575

🎀 so that's the page, bestie! source/version: Debian · date: March 9, 2024 · manual page: PMF(9) — mwah, bye! 💖

📦 where this page comes from