device_link_add(9)

📦 version 7.3.1, in nixpkgs unstable

okay bestie, welcome to the <pink>Kernel API Manual</pink> page for device_link_add(9) ✨ this one's all about setting up a relationship between two devices, and honestly it's giving matchmaker energy 🫶

🌸 NAME 🌸

device_link_add — Create a link between two devices. literally just pairing them up 💅

✨ SYNOPSIS ✨

struct device_link * device_link_add (struct device *consumer , struct
       struct device *supplier , u32 flags );

no cap, that's the whole signature — three args, one pointer back 🎀

🦋 ARGUMENTS 🦋

  • consumer — the consumer end of the link, aka the one doing the consuming 🍓
  • supplier — the supplier end of the link, aka the one providing 👑
  • flags — the link flags, this is where all the personality lives ⭐

🌈 RETURN 🌈

On success you get a device_link struct handed right back to you 💖 but on error, or if the flag settings are invalid, you get NULL. sad but true 😭 NULL is the vibe check fail.

💜 DESCRIPTION 💜

okay so first thing, and this is important: the caller is responsible for the proper synchronization of the link creation with runtime PM. that's on you, bestie, nobody's coming to save you 🙈

First up: setting the DL_FLAG_PM_RUNTIME flag will cause the runtime PM framework to take the link into account. ✨

Second: if the DL_FLAG_RPM_ACTIVE flag is set in addition to it, the supplier devices will be forced into the active meta state and reference-counted upon the creation of the link. 🔥 And listen — if DL_FLAG_PM_RUNTIME is not set, then DL_FLAG_RPM_ACTIVE will be ignored. like, fully ignored, it just doesn't get a turn 💀

If DL_FLAG_STATELESS is set in flags, the caller of this function is expected to release the link returned by it directly with the help of either device_link_del or device_link_remove. 👑

If that flag is not set, however, the caller of this function is handing the management of the link over to the driver core entirely, and its return value can only be used to check whether or not the link is present. In that case, the DL_FLAG_AUTOREMOVE_CONSUMER and DL_FLAG_AUTOREMOVE_SUPPLIER device link flags can be used to indicate to the driver core when the link can be safely deleted. 🎀

Namely — setting one of them in flags indicates to the driver core that the link is not going to be used (by the given caller of this function) after unbinding the consumer or supplier driver, respectively, from its device, so the link can be deleted at that point.

And if none of them is set, the link will be maintained until one of the devices pointed to by it (either the consumer or the supplier) is unregistered. fr fr, it just hangs around. 🦋

Also! If DL_FLAG_STATELESS, DL_FLAG_AUTOREMOVE_CONSUMER and DL_FLAG_AUTOREMOVE_SUPPLIER are not set in flags (that is, a persistent managed device link is being added), the DL_FLAG_AUTOPROBE_CONSUMER flag can be used to request the driver core to automatically probe for a consumer driver after successfully binding a driver to the supplier device. that's the good stuff ✨

⚠️ the invalid combo, pay attention bestie — the combination of DL_FLAG_STATELESS and one of DL_FLAG_AUTOREMOVE_CONSUMER, DL_FLAG_AUTOREMOVE_SUPPLIER, or DL_FLAG_AUTOPROBE_CONSUMER set in flags at the same time is invalid and will cause NULL to be returned upfront. 😭

However — and this is the plot twist — if a device link between the given consumer and supplier pair exists already when this function is called for them, the existing link will be returned regardless of its current type and status (the link's flags may be modified then). 👀 The caller of this function is then expected to treat the link as though it has just been created, so (in particular) if DL_FLAG_STATELESS was passed in flags, the link needs to be released explicitly when not needed any more (as stated above). don't forget it, i'm begging 🫶

A side effect of the link creation is re-ordering of dpm_list and the devices_kset list by moving the consumer device and all devices depending on it to the ends of these lists (that does not happen to devices that have not been registered when this function is called). 🌸 like, they get moved to the back of the line, respectfully.

The supplier device is required to be registered when this function is called and NULL will be returned if that is not the case. 🚨 The consumer device need not be registered, however. main character supplier energy only 💅

🔥 SEE ALSO 🔥

so many friends, so many cross-references, i'm obsessed with how thorough this is 🧚

Kernel file ./drivers/base/core.c:

and that's the whole page, bestie 💜 this one came from ./drivers/base and it's dated October 2026 — so go forth, link those devices, and don't forget to release your DL_FLAG_STATELESS links 🎀✨

📦 where this page comes from