rtas_call(9)

💅 rtas_call 💅

Okay bestie, welcome to the manual page for rtas_call — it's from the Kernel API Manual and it's literally about invoking RTAS firmware functions. Buckle up, this one's a whole journey. 🎀

---

✨ NAME ✨

rtas_call — Invoke an RTAS firmware function. That's it. That's the vibe. 💖

---

🌸 SYNOPSIS 🌸

int rtas_call (int token , int nargs , int nret , int *outputs , ... );

---

🦋 ARGUMENTS 🦋

• token — Identifies the function being invoked. Like a little ID card for your firmware call. 👑
• nargs — Number of input parameters. Note: this does not include token. Don't count it twice, bestie. 🙈
• nret — Number of output parameters, including the call status. Yes, the status counts. She's part of the group. 💅
• outputs — Array of nret output words. Your results live here. 🍓
• ... — List of nargs input parameters. All the extra little guys you're passing in. ✨

---

💜 DESCRIPTION 💜

So what does this actually do? It invokes the RTAS function indicated by token, which — plot twist — the caller should obtain via rtas_function_token. Don't just make up a token, okay? 😭

The nargs and nret arguments must match the number of input and output parameters specified for the RTAS function. No cap, if they don't match, things get messy. 🫶

Here's the important tea: rtas_call returns RTAS status codes, not conventional Linux errno values. So callers must translate any failure to an appropriate errno in syscall context. Most callers of RTAS functions that can return -2 or 990x should use rtas_busy_delay to correctly handle those statuses before calling again. Iconic of rtas_busy_delay honestly. 🌈

The return value descriptions are adapted from 7.2.8 [RTAS] Return Codes of the PAPR and CHRP specifications. Giving credit where it's due, periodt. 👑

---

🔥 CONTEXT 🔥

Process context preferably, interrupt context if necessary. Acquires an internal spinlock and may perform GFP_ATOMIC slab allocation in error path. Unsafe for NMI context. So like… not NMI-safe, bestie. Be careful. 💀

---

⭐ RETURN ⭐

Okay this is the whole menu of what you might get back. Stay with me:

• 0 — RTAS function call succeeded. Slay! 🎉
• -1 — RTAS function encountered a hardware or platform error, or the token is invalid, or the function is restricted by kernel policy. Rude. 😤
• -2 — The specs say: "A necessary hardware device was busy, and the requested function could not be performed. The operation should be retried at a later time." But ngl, this is misleading, at least with respect to current RTAS implementations. What it usually means in practice is that the function could not be completed while meeting RTAS's deadline for returning control to the OS (250us for PAPR/PowerVM, typically), but the call may be immediately reattempted to resume work on it. So like, try again right away, it's fine. 🔁
• -3 — Parameter error. You passed something cursed. 🙈
• -7 — Unexpected state change. Plot twist nobody asked for. 😭
• 9000...9899 — Vendor-specific success codes. Yay, success but make it mysterious. ✨
• 9900...9905 — Advisory extended delay. Caller should try again after ~10^x ms has elapsed, where x is the last digit of the status [0-5]. Again going beyond the PAPR text, 990x on PowerVM indicates contention for RTAS-internal resources. Other RTAS call sequences in progress should be allowed to complete before reattempting the call. So like, wait your turn. 💅
• -9000 — Multi-level isolation error. Sounds dramatic, is dramatic. 💀
• -9999...-9004 — Vendor-specific error codes. The mystery errors. 🕵️
• Additional negative values — Function-specific error. Boo. 👎
• Additional positive values — Function-specific success. Yay! 🎀

---

🌈 SEE ALSO 🌈

Kernel file ./arch/powerpc/kernel/rtas.c and all her friends: struct rtas_function(9), rtas_function_token(9), rtas_call_unlocked(9), rtas_busy_delay_time(9), rtas_busy_delay(9), rtas_ibm_suspend_me(9), rtas_activate_firmware(9), get_pseries_errorlog(9). Go read them, they're literally so good. 🫶📚

---

Anyways bestie, that's the whole manual. This page lives in ./arch/powerpc/kernel, dated October 2026 — like, future vibes but make it kernel documentation. Stay safe out there in interrupt context, and remember: translate your errnos. Periodt. 💖✨🎀