archive mirror
 help / color / mirror / Atom feed
From: Joe Lawrence <>
To: Petr Mladek <>, Josh Poimboeuf <>
Subject: refactoring livepatch documentation was Re: [PATCH 1/2] docs/livepatch: Add new compiler considerations doc
Date: Mon, 10 Aug 2020 15:46:46 -0400	[thread overview]
Message-ID: <> (raw)
In-Reply-To: <20200806120336.GP24529@alley>

On 8/6/20 8:03 AM, Petr Mladek wrote:
> On Wed 2020-07-22 15:51:39, Josh Poimboeuf wrote:
>> On Wed, Jul 22, 2020 at 01:03:03PM -0400, Joe Lawrence wrote:
>>> On 7/21/20 7:04 PM, Josh Poimboeuf wrote:
>>>> On Tue, Jul 21, 2020 at 12:14:06PM -0400, Joe Lawrence wrote:
>>>>> Compiler optimizations can have serious implications on livepatching.
>>>>> Create a document that outlines common optimization patterns and safe
>>>>> ways to livepatch them.
>>>>> Signed-off-by: Joe Lawrence <>
>>>> There's a lot of good info here, but I wonder if it should be
>>>> reorganized a bit and instead called "how to create a livepatch module",
>>>> because that's really the point of it all.
>>> That would be nice.  Would you consider a stand-alone compiler-optimizations
>>> doc an incremental step towards that end?  Note that the other files
>>> (callbacks, shadow-vars, system-state) in their current form might be as
>>> confusing to the newbie.
>> It's an incremental step towards _something_.  Whether that's a cohesive
>> patch creation guide, or just a growing hodgepodge of random documents,
>> it may be too early to say :-)
> Yes, it would be nice to have a cohesive documentation. But scattered
> pieces are better than nothing.
>>>> I'm thinking a newcomer reading this might be lost.  It's not
>>>> necessarily clear that there are currently two completely different
>>>> approaches to creating a livepatch module, each with their own quirks
>>>> and benefits/drawbacks.  There is one mention of a "source-based
>>>> livepatch author" but no explanation of what that means.
>>> Yes, the initial draft was light on source-based patching since I only
>>> really tinker with it for samples/kselftests.  The doc was the result of an
>>> experienced livepatch developer and Sunday afternoon w/the compiler. I'm
>>> sure it reads as such. :)
>> Are experienced livepatch developers the intended audience?  If so I
>> question what value this document has in its current form.  Presumably
>> experienced livepatch developers would already know this stuff.
> IMHO, this document is useful even for newbies. They might at
> least get a clue about these catches. It is better than nothing.
> I do not want to discourage Joe from creating even better
> documentation. But if he does not have interest or time
> to work on it, I am happy even for this piece.

Hi Petr, Josh,

The compiler optimization pitfall document can wait for refactored 
livepatch documentation if that puts it into better context, 
particularly for newbies.  I don't mind either way.  FWIW, I don't 
profess to be an authoritative source its content -- we've dealt some of 
these issues in kpatch, so it was interesting to see how they affect 
livepatches that don't rely on binary comparison.

Toward the larger goal, I've changed the thread subject to talk about 
how we may rearrange and supplement our current documentation.  This is 
a first pass at a possible refactoring...

1. Provide a better index page to connect the other files/docs, like but obviously 
not that extensive.  Right now we have only a Table of Contents tree 
without any commentary.

2. Rearrange and refactor sections:

   Keep just about everything
   Add a history section to explain ksplice, kgraft, kpatch for the
   Add a section on source based vs. binary diff livepatch creation,
     this may be worth its own top-level section

Livepatch API
   Basic API
   Shadow variables
   Cumulative patches
   System state

KLP Relocations
   Right now this is a bit academic AFAIK kpatch is the only tool
   currently making use of them.  So maybe this document becomes a
   more general purpose doc explaining how to reference unexported
   symbols?  (ie, how does kgraft currently do it, particularly
   w/kallsyms going unexported?)

   Eventually this could contain klp-convert howto if it ever gets

Compiler considerations

I suppose this doesn't create a "Livepatching creation for dummies" 
guide, but my feeling is that there are so many potential (hidden) 
pitfalls that such guide would be dangerous.

If someone were to ask me today how to start building a livepatch, I 
would probably point them at the samples to demonstrate the basic 
concept and API, but then implore them to read through the documentation 
to understand how quickly complicated it can become.

-- Joe

  reply	other threads:[~2020-08-10 19:46 UTC|newest]

Thread overview: 13+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-07-21 16:14 [PATCH 0/2] livepatch: Add compiler optimization disclaimer/docs Joe Lawrence
2020-07-21 16:14 ` [PATCH 1/2] docs/livepatch: Add new compiler considerations doc Joe Lawrence
2020-07-21 23:04   ` Josh Poimboeuf
2020-07-22 17:03     ` Joe Lawrence
2020-07-22 20:51       ` Josh Poimboeuf
2020-08-06 12:03         ` Petr Mladek
2020-08-10 19:46           ` Joe Lawrence [this message]
2020-09-01 17:12             ` refactoring livepatch documentation was " Josh Poimboeuf
2020-09-02 14:00             ` Miroslav Benes
2020-09-02 13:45   ` Miroslav Benes
2020-07-21 16:14 ` [PATCH 2/2] samples/livepatch: Add README.rst disclaimer Joe Lawrence
2020-08-06 12:07   ` Petr Mladek
2020-09-02 13:46   ` Miroslav Benes

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:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \ \ \ \

* 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).