From: Nathan Lynch <nathanl@linux.ibm.com>
To: linuxppc-dev@lists.ozlabs.org
Cc: tyreld@linux.ibm.com, nnac123@linux.ibm.com,
ldufour@linux.ibm.com, ajd@linux.ibm.com, npiggin@gmail.com
Subject: [PATCH 01/13] powerpc/rtas: document rtas_call()
Date: Fri, 18 Nov 2022 09:07:39 -0600 [thread overview]
Message-ID: <20221118150751.469393-2-nathanl@linux.ibm.com> (raw)
In-Reply-To: <20221118150751.469393-1-nathanl@linux.ibm.com>
rtas_call() has a complex calling convention, non-standard return
values, and many users. Add kernel-doc for it and remove the less
structured commentary from rtas.h.
Signed-off-by: Nathan Lynch <nathanl@linux.ibm.com>
---
arch/powerpc/include/asm/rtas.h | 15 ---------
arch/powerpc/kernel/rtas.c | 58 +++++++++++++++++++++++++++++++++
2 files changed, 58 insertions(+), 15 deletions(-)
diff --git a/arch/powerpc/include/asm/rtas.h b/arch/powerpc/include/asm/rtas.h
index 56319aea646e..479a95cb2770 100644
--- a/arch/powerpc/include/asm/rtas.h
+++ b/arch/powerpc/include/asm/rtas.h
@@ -33,21 +33,6 @@
#define RTAS_THREADS_ACTIVE -9005 /* Multiple processor threads active */
#define RTAS_OUTSTANDING_COPROC -9006 /* Outstanding coprocessor operations */
-/*
- * In general to call RTAS use rtas_token("string") to lookup
- * an RTAS token for the given string (e.g. "event-scan").
- * To actually perform the call use
- * ret = rtas_call(token, n_in, n_out, ...)
- * Where n_in is the number of input parameters and
- * n_out is the number of output parameters
- *
- * If the "string" is invalid on this system, RTAS_UNKNOWN_SERVICE
- * will be returned as a token. rtas_call() does look for this
- * token and error out gracefully so rtas_call(rtas_token("str"), ...)
- * may be safely used for one-shot calls to RTAS.
- *
- */
-
/* RTAS event classes */
#define RTAS_INTERNAL_ERROR 0x80000000 /* set bit 0 */
#define RTAS_EPOW_WARNING 0x40000000 /* set bit 1 */
diff --git a/arch/powerpc/kernel/rtas.c b/arch/powerpc/kernel/rtas.c
index e847f9b1c5b9..c12dd5ed5e00 100644
--- a/arch/powerpc/kernel/rtas.c
+++ b/arch/powerpc/kernel/rtas.c
@@ -467,6 +467,64 @@ void rtas_call_unlocked(struct rtas_args *args, int token, int nargs, int nret,
static int ibm_open_errinjct_token;
static int ibm_errinjct_token;
+/**
+ * rtas_call() - Invoke an RTAS firmware function.
+ * @token: Identifies the function being invoked.
+ * @nargs: Number of input parameters. Does not include token.
+ * @nret: Number of output parameters, including the call status.
+ * @outputs: Array of @nret output words.
+ * @....: List of @nargs input parameters.
+ *
+ * Invokes the RTAS function indicated by @token, which the caller
+ * should obtain via rtas_token().
+ *
+ * The @nargs and @nret arguments must match the number of input and
+ * output parameters specified for the RTAS function.
+ *
+ * rtas_call() returns RTAS status codes, not conventional Linux errno
+ * values. 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.
+ *
+ * The return value descriptions are adapted from 7.2.8 [RTAS] Return
+ * Codes of the PAPR and CHRP specifications.
+ *
+ * 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.
+ * Return:
+ * * 0 - RTAS function call succeeded.
+ * * -1 - RTAS function encountered a hardware or
+ * platform error, or the token is invalid,
+ * or the function is restricted by kernel policy.
+ * * -2 - 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." 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.
+ * * -3 - Parameter error.
+ * * -7 - Unexpected state change.
+ * * 9000...9899 - Vendor-specific success codes.
+ * * 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.
+ * * -9000 - Multi-level isolation error.
+ * * -9999...-9004 - Vendor-specific error codes.
+ * * Additional negative values - Function-specific error.
+ * * Additional positive values - Function-specific success.
+ */
int rtas_call(int token, int nargs, int nret, int *outputs, ...)
{
va_list list;
--
2.37.1
next prev parent reply other threads:[~2022-11-18 15:09 UTC|newest]
Thread overview: 49+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-11-18 15:07 [PATCH 00/13] RTAS maintenance Nathan Lynch
2022-11-18 15:07 ` Nathan Lynch [this message]
2022-11-22 2:46 ` [PATCH 01/13] powerpc/rtas: document rtas_call() Andrew Donnellan
2022-11-18 15:07 ` [PATCH 02/13] powerpc/rtasd: use correct OF API for event scan rate Nathan Lynch
2022-11-22 2:39 ` Andrew Donnellan
2022-11-18 15:07 ` [PATCH 03/13] powerpc/rtas: avoid device tree lookups in rtas_os_term() Nathan Lynch
2022-11-22 3:03 ` Andrew Donnellan
2022-11-28 18:08 ` Nathan Lynch
2022-11-28 2:29 ` Nicholas Piggin
2022-11-28 18:26 ` Nathan Lynch
2022-11-29 6:45 ` Nicholas Piggin
2022-11-29 15:37 ` Nathan Lynch
2022-11-18 15:07 ` [PATCH 04/13] powerpc/rtas: avoid scheduling " Nathan Lynch
2022-11-22 3:17 ` Andrew Donnellan
2022-11-28 2:34 ` Nicholas Piggin
2022-11-18 15:07 ` [PATCH 05/13] powerpc/pseries/eeh: use correct API for error log size Nathan Lynch
2022-11-22 3:21 ` Andrew Donnellan
2022-11-28 20:22 ` Nathan Lynch
2022-11-18 15:07 ` [PATCH 06/13] powerpc/rtas: clean up rtas_error_log_max initialization Nathan Lynch
2022-11-22 3:40 ` Andrew Donnellan
2022-11-18 15:07 ` [PATCH 07/13] powerpc/rtas: clean up includes Nathan Lynch
2022-11-22 4:45 ` Andrew Donnellan
2022-11-18 15:07 ` [PATCH 08/13] powerpc/rtas: define pr_fmt and convert printk call sites Nathan Lynch
2022-11-22 4:07 ` Andrew Donnellan
2022-11-18 15:07 ` [PATCH 09/13] powerpc/rtas: mandate RTAS syscall filtering Nathan Lynch
2022-11-22 4:20 ` Andrew Donnellan
2022-11-18 15:07 ` [PATCH 10/13] powerpc/rtas: improve function information lookups Nathan Lynch
2022-11-23 2:51 ` Andrew Donnellan
2022-11-23 19:32 ` Nick Child
2022-11-24 3:28 ` Andrew Donnellan
2022-11-28 21:19 ` Nathan Lynch
2022-11-29 0:08 ` Nathan Lynch
2022-11-29 7:23 ` Andrew Donnellan
2022-11-29 15:33 ` Nathan Lynch
2022-11-23 20:06 ` Nick Child
2022-11-28 21:57 ` Nathan Lynch
2022-11-18 15:07 ` [PATCH 11/13] powerpc/rtas: strengthen do_enter_rtas() type safety, drop inline Nathan Lynch
2022-11-23 3:23 ` Andrew Donnellan
2022-11-28 2:37 ` Nicholas Piggin
2022-11-18 15:07 ` [PATCH 12/13] powerpc/tracing: tracepoints for RTAS entry and exit Nathan Lynch
2022-11-28 2:54 ` Nicholas Piggin
2022-11-18 15:07 ` [PATCH 13/13] powerpc/rtas: place tracepoints in do_enter_rtas() Nathan Lynch
2022-11-28 3:07 ` Nicholas Piggin
2022-11-28 23:44 ` Nathan Lynch
2022-11-29 0:49 ` Michael Ellerman
2022-11-29 20:24 ` Nathan Lynch
2022-11-30 7:43 ` Michael Ellerman
2022-11-29 6:47 ` Nicholas Piggin
2022-12-08 12:40 ` [PATCH 00/13] RTAS maintenance Michael Ellerman
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20221118150751.469393-2-nathanl@linux.ibm.com \
--to=nathanl@linux.ibm.com \
--cc=ajd@linux.ibm.com \
--cc=ldufour@linux.ibm.com \
--cc=linuxppc-dev@lists.ozlabs.org \
--cc=nnac123@linux.ibm.com \
--cc=npiggin@gmail.com \
--cc=tyreld@linux.ibm.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).