[side note: So not only that my INBOX is a mess after the summer. I also lost some emails apparently. I'm really sorry about that. ] CCing Nicolai too. > 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 > https://www.kernel.org/doc/html/latest/core-api/index.html but obviously not > that extensive. Right now we have only a Table of Contents tree without any > commentary. > > 2. Rearrange and refactor sections: > > livepatch.rst > Keep just about everything > Add a history section to explain ksplice, kgraft, kpatch for the > uninitiated? > Add a section on source based vs. binary diff livepatch creation, > this may be worth its own top-level section > > Livepatch API > Basic API > Callbacks > 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?) Yes, we rely on kallsyms_lookup_name() pretty much right now and once we hit the problem with the next kernel version upgrade, we'll have to fix it. > Eventually this could contain klp-convert howto if it ever gets > merged. > > Compiler considerations > TBD > > 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. It does not create the guide, but it looks like a good basis. I agree with Josh here. It might be difficult at the beginning, but the outcome could be great even for a newbie and I think we should aim for that. > 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. True. We discuss the need to properly document our internal process every once in a while and there is always something more important to deal with, but it is high time to finally start with that. Miroslav
