From cd305fd7ec361d745d0c5e46ba181feaca1dcc39 Mon Sep 17 00:00:00 2001
From: Joe Lawrence <joe.lawrence@redhat.com>
Date: Thu, 5 Dec 2019 14:48:29 -0500
Subject: [PATCH] patch-author-guide: add sibling call info

kpatch-build doesn't support GCC's sibling call optimizations in patched
functions to avoid potentially dangerous generated code.  Explain the
error message that may result and link to the commit which provided
detailed explanation of why we disabled support for this in kpatch.

Signed-off-by: Joe Lawrence <joe.lawrence@redhat.com>
---
 doc/patch-author-guide.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/doc/patch-author-guide.md b/doc/patch-author-guide.md
index 992cc2a..7fca801 100644
--- a/doc/patch-author-guide.md
+++ b/doc/patch-author-guide.md
@@ -687,3 +687,26 @@ if (static_key_enabled(&true_key))
 if (static_key_enabled(&false_key))
 if (likely(static_key_enabled(&key)))
 ```
+
+Sibling calls
+-------------
+
+GCC may generate sibling calls that are incompatible with kpatch, resulting in
+an error like: `ERROR("Found an unsupported sibling call at foo()+0x123.  Add __attribute__((optimize("-fno-optimize-sibling-calls"))) to foo() definition."`
+
+For example, if function A() calls function B() at the end of A() and both
+return similar data-types, GCC may deem them "sibling calls" and apply a tail
+call optimization in which A() restores the stack to is callee state before
+setting up B()'s arguments and jumping to B().
+
+This may be an issue for kpatches on PowerPC which modify only A() or B() and
+the function call crosses a kernel module boundary: the sibling call
+optimization has changed expected calling conventions and (un)patched code may
+not be similarly modified.
+
+Commit [8b952bd77130](https://github.com/dynup/kpatch/commit/8b952bd77130)
+("create-diff-object/ppc64le: Don't allow sibling calls") contains an
+excellent example and description of this problem with annotated disassembly.
+
+Adding `__attribute__((optimize("-fno-optimize-sibling-calls")))` instructs
+GCC to turn off the optimization for the given function.