of_parse_phandle_with_args(9)

📦 version 7.3.1, in nixpkgs unstable

💅 of_parse_phandle_with_args(9) — from the Kernel API Manual, bestie 🎀

okay so we're doing kernel device-tree stuff today and honestly? it's giving main character energy ✨ stay with me, this one's actually so good once it clicks.

🌸 NAME 🌸

of_parse_phandle_with_args — find a node pointed by a phandle in a list 🔍💖

✨ SYNOPSIS ✨

int of_parse_phandle_with_args (const struct device_node *np , const
       char *list_name , const char *cells_name , int index , struct
       of_phandle_args *out_args );

like, five args, one int back, no cap 🫶

🦋 ARGUMENTS 🦋

  • np — pointer to a device tree node containing a list. this is the node you're snooping through, the one that's holding the list 👀
  • list_name — property name that contains a list. literally just tell it which property to look at, bestie 💅
  • cells_name — property name that specifies phandles' arguments count. it's the property that says how many arg cells each phandle gets 🧮
  • index — index of a phandle to parse out. which one in the list you want, zero-indexed obviously 🙈
  • out_args — optional pointer to output arguments structure (will be filled). optional!! but if you pass it, it will get filled, that's the whole vibe ⭐

🔥 DESCRIPTION 🔥

so this function is useful to parse lists of phandles and their arguments. that's the whole job, and it ate 💀✨

it returns 0 on success and fills out_args, and on error it returns the appropriate errno value. simple as that, fr fr.

⚠️ important one, do not skip this: the caller is responsible to call of_node_put on the returned out_args->np pointer. like, that's on you, bestie. don't leave that node hanging 😭🔒

here's the example, and yes it's iconic:

 phandle1: node1 {
     #list-cells = <2>;
 };

 phandle2: node2 {
     #list-cells = <1>;
 };

 node3 {
     list = <phandle1 1 2 phandle2 3>;
 };

so node1 says its phandles carry 2 argument cells (#list-cells = <2>;), and node2 says its carry 1 (#list-cells = <1>;). then node3 has the actual list property: <phandle1 1 2 phandle2 3>. see how phandle1 grabs two values (1 2) and phandle2 grabs one (3)? that's the whole system working exactly as intended 👑

so to get a device_node of the node2 node you may call this:

of_parse_phandle_with_args(node3, "list", "#list-cells", 1, args);

index 1 → node2. periodt 💜

💖 SEE ALSO 💖

kernel file ./include/linux/of.h, plus the whole friend group:

🌈 and that's the page!! shipped straight out of ./include/linux, dated October 2026, in the Kernel API Manual. go read the source, call of_node_put, and slay 💅🎀🦋
📦 where this page comes from