Re: [PATCH v2] livepatch: Add some basic LivePatch documentation

[Chris J Arges]

On Wed, Apr 27, 2016 at 10:08:08PM +0200, Jiri Kosina wrote:
> On Tue, 26 Apr 2016, Chris J Arges wrote:
> 
> [ ... snip ... ]
> > > +  + Kretprobes using the ftrace framework conflict with the patched
> > 
> >  +  + Kretprobes using the ftrace framework conflicts with the patched
> 
> Chris,
> 
> I've incorporated all your feedback except for this one; are you really 
> sure about it? 'kretprobes' is plural form in this sentence, so what's the 
> rationale for your proposed change?
> 
> Thanks,
> 
> -- 
> Jiri Kosina
> SUSE Labs
>

You are correct here; the subject and verb need to agree. Thanks!
--chris

Re: [PATCH v2] livepatch: Add some basic LivePatch documentation

[Chris J Arges]

On Wed, Apr 27, 2016 at 10:08:08PM +0200, Jiri Kosina wrote:
> On Tue, 26 Apr 2016, Chris J Arges wrote:
> 
> [ ... snip ... ]
> > > +  + Kretprobes using the ftrace framework conflict with the patched
> > 
> >  +  + Kretprobes using the ftrace framework conflicts with the patched
> 
> Chris,
> 
> I've incorporated all your feedback except for this one; are you really 
> sure about it? 'kretprobes' is plural form in this sentence, so what's the 
> rationale for your proposed change?
> 
> Thanks,
> 
> -- 
> Jiri Kosina
> SUSE Labs
>

You are correct here; the subject and verb need to agree. Thanks!
--chris

Re: [PATCH v2] livepatch: Add some basic LivePatch documentation

[Balbir Singh]

On 28/04/16 06:08, Jiri Kosina wrote:
> On Wed, 27 Apr 2016, Jiri Kosina wrote:
> 
>> I've incorporated most of the feedback (*) and pushed out to 
>> livepatching.git#for-4.7/livepatching-doc so everybody please send any 
>> followup documentation patches on top of that branch.
> 
> (*) Balbir, some of your comments were a bit too vague; if you could turn 
> them into actual patch on top of what's currently in git, that'd be 
> helpful
> 

Hi, Jiri

Thanks! I'll try to do that -- I'll add it on my TODO list.

Balbir Singh.

Re: [PATCH v2] livepatch: Add some basic LivePatch documentation

[Balbir Singh]

On 28/04/16 06:08, Jiri Kosina wrote:
> On Wed, 27 Apr 2016, Jiri Kosina wrote:
> 
>> I've incorporated most of the feedback (*) and pushed out to 
>> livepatching.git#for-4.7/livepatching-doc so everybody please send any 
>> followup documentation patches on top of that branch.
> 
> (*) Balbir, some of your comments were a bit too vague; if you could turn 
> them into actual patch on top of what's currently in git, that'd be 
> helpful
> 

Hi, Jiri

Thanks! I'll try to do that -- I'll add it on my TODO list.

Balbir Singh.

Re: [PATCH v2] livepatch: Add some basic LivePatch documentation

[Jiri Kosina]

On Tue, 26 Apr 2016, Chris J Arges wrote:

[ ... snip ... ]
> > +  + Kretprobes using the ftrace framework conflict with the patched
> 
>  +  + Kretprobes using the ftrace framework conflicts with the patched

Chris,

I've incorporated all your feedback except for this one; are you really 
sure about it? 'kretprobes' is plural form in this sentence, so what's the 
rationale for your proposed change?

Thanks,

-- 
Jiri Kosina
SUSE Labs

Re: [PATCH v2] livepatch: Add some basic LivePatch documentation

[Jiri Kosina]

On Tue, 26 Apr 2016, Chris J Arges wrote:

[ ... snip ... ]
> > +  + Kretprobes using the ftrace framework conflict with the patched
> 
>  +  + Kretprobes using the ftrace framework conflicts with the patched

Chris,

I've incorporated all your feedback except for this one; are you really 
sure about it? 'kretprobes' is plural form in this sentence, so what's the 
rationale for your proposed change?

Thanks,

-- 
Jiri Kosina
SUSE Labs

Re: [PATCH v2] livepatch: Add some basic LivePatch documentation

[Jiri Kosina]

On Wed, 27 Apr 2016, Jiri Kosina wrote:

> I've incorporated most of the feedback (*) and pushed out to 
> livepatching.git#for-4.7/livepatching-doc so everybody please send any 
> followup documentation patches on top of that branch.

(*) Balbir, some of your comments were a bit too vague; if you could turn 
them into actual patch on top of what's currently in git, that'd be 
helpful

-- 
Jiri Kosina
SUSE Labs

Re: [PATCH v2] livepatch: Add some basic LivePatch documentation

[Jiri Kosina]

On Wed, 27 Apr 2016, Jiri Kosina wrote:

> I've incorporated most of the feedback (*) and pushed out to 
> livepatching.git#for-4.7/livepatching-doc so everybody please send any 
> followup documentation patches on top of that branch.

(*) Balbir, some of your comments were a bit too vague; if you could turn 
them into actual patch on top of what's currently in git, that'd be 
helpful

-- 
Jiri Kosina
SUSE Labs

Re: [PATCH v2] livepatch: Add some basic LivePatch documentation

[Jiri Kosina]

On Mon, 25 Apr 2016, Petr Mladek wrote:

> LivePatch framework deserves some documentation, definitely.
> This is an attempt to provide some basic info. I hope that
> it will be useful for both LivePatch producers and also
> potential developers of the framework itself.
> 
> Signed-off-by: Petr Mladek 

Good stuff, thanks.

I've incorporated most of the feedback (*) and pushed out to 
livepatching.git#for-4.7/livepatching-doc so everybody please send any 
followup documentation patches on top of that branch.

-- 
Jiri Kosina
SUSE Labs

Re: [PATCH v2] livepatch: Add some basic LivePatch documentation

[Jiri Kosina]

On Mon, 25 Apr 2016, Petr Mladek wrote:

> LivePatch framework deserves some documentation, definitely.
> This is an attempt to provide some basic info. I hope that
> it will be useful for both LivePatch producers and also
> potential developers of the framework itself.
> 
> Signed-off-by: Petr Mladek 

Good stuff, thanks.

I've incorporated most of the feedback (*) and pushed out to 
livepatching.git#for-4.7/livepatching-doc so everybody please send any 
followup documentation patches on top of that branch.

-- 
Jiri Kosina
SUSE Labs

Re: [PATCH v2] livepatch: Add some basic LivePatch documentation

[Miroslav Benes]

On Tue, 26 Apr 2016, Balbir Singh wrote:

> > +  + Anything inlined into __schedule() can not be patched.
> > +
> > +The switch_to macro is inlined into __schedule(). It switches the
> > +context between two processes in the middle of the macro. It does
> > +not save RIP in x86_64 version (contrary to 32-bit version). Instead,
> > +the currently used __schedule()/switch_to() handles both processes.
> > +
> > +Now, let's have two different tasks. One calls the original
> > +__schedule(), its registers are stored in a defined order and it
> > +goes to sleep in the switch_to macro and some other task is restored
> > +using the original __schedule(). Then there is the second task which
> > +calls patched__schedule(), it goes to sleep there and the first task
> > +is picked by the patched__schedule(). Its RSP is restored and now
> > +the registers should be restored as well. But the order is different
> > +in the new patched__schedule(), so...
> > +
> > +There is a work in progress to remove this limitation.
> > +
> 
> I am afraid the example requires more clarification. I don't quite get the 
> order is different

Different order is not inevitable but perfectly possible (even probable). 
GCC may simply generate different object code for patched__schedule() than 
it did for __schedule(). The problem is when the prologue and epilogue are 
different.

Miroslav

Re: [PATCH v2] livepatch: Add some basic LivePatch documentation

[Miroslav Benes]

On Tue, 26 Apr 2016, Balbir Singh wrote:

> > +  + Anything inlined into __schedule() can not be patched.
> > +
> > +The switch_to macro is inlined into __schedule(). It switches the
> > +context between two processes in the middle of the macro. It does
> > +not save RIP in x86_64 version (contrary to 32-bit version). Instead,
> > +the currently used __schedule()/switch_to() handles both processes.
> > +
> > +Now, let's have two different tasks. One calls the original
> > +__schedule(), its registers are stored in a defined order and it
> > +goes to sleep in the switch_to macro and some other task is restored
> > +using the original __schedule(). Then there is the second task which
> > +calls patched__schedule(), it goes to sleep there and the first task
> > +is picked by the patched__schedule(). Its RSP is restored and now
> > +the registers should be restored as well. But the order is different
> > +in the new patched__schedule(), so...
> > +
> > +There is a work in progress to remove this limitation.
> > +
> 
> I am afraid the example requires more clarification. I don't quite get the 
> order is different

Different order is not inevitable but perfectly possible (even probable). 
GCC may simply generate different object code for patched__schedule() than 
it did for __schedule(). The problem is when the prologue and epilogue are 
different.

Miroslav

Re: [PATCH v2] livepatch: Add some basic LivePatch documentation

[Josh Poimboeuf]

On Mon, Apr 25, 2016 at 05:14:35PM +0200, Petr Mladek wrote:
> LivePatch framework deserves some documentation, definitely.
> This is an attempt to provide some basic info. I hope that
> it will be useful for both LivePatch producers and also
> potential developers of the framework itself.
> 
> Signed-off-by: Petr Mladek 

My only comment is s/LivePatch/livepatch/ here and in the subject.
Otherwise it looks great to me.  Really nice work!

-- 
Josh

Re: [PATCH v2] livepatch: Add some basic LivePatch documentation

[Josh Poimboeuf]

On Mon, Apr 25, 2016 at 05:14:35PM +0200, Petr Mladek wrote:
> LivePatch framework deserves some documentation, definitely.
> This is an attempt to provide some basic info. I hope that
> it will be useful for both LivePatch producers and also
> potential developers of the framework itself.
> 
> Signed-off-by: Petr Mladek 

My only comment is s/LivePatch/livepatch/ here and in the subject.
Otherwise it looks great to me.  Really nice work!

-- 
Josh

Re: [PATCH v2] livepatch: Add some basic LivePatch documentation

[Chris J Arges]

On Mon, Apr 25, 2016 at 05:14:35PM +0200, Petr Mladek wrote:
> LivePatch framework deserves some documentation, definitely.
> This is an attempt to provide some basic info. I hope that
> it will be useful for both LivePatch producers and also
> potential developers of the framework itself.
> 
> Signed-off-by: Petr Mladek 
> ---
> 
> This version incorporates feedback from all people who
> commented on v1. Thanks a lot for it.
> 
> Sometimes I copy the suggested text. Sometimes,
> I used my own invention. The text has grown from 277 to
> 400 lines. I wish I had a lighter pen. Anyway, please
> see what I hammered together.
> 
> Changes against v1:
> 
> + switched the order of the section 4 and 5
> + tiny changes in sections 1,2,6
> + heavily updated sections 3,4,5,7
>

Suggestions for rewording and grammar fixes are inline. This is very useful!
--chris

 
>  Documentation/livepatch/livepatch.txt | 400 
> ++
>  MAINTAINERS   |   1 +
>  2 files changed, 401 insertions(+)
>  create mode 100644 Documentation/livepatch/livepatch.txt
> 
> diff --git a/Documentation/livepatch/livepatch.txt 
> b/Documentation/livepatch/livepatch.txt
> new file mode 100644
> index ..7c4777e3170c
> --- /dev/null
> +++ b/Documentation/livepatch/livepatch.txt
> @@ -0,0 +1,400 @@
> +=
> +Livepatch
> +=
> +
> +This document outlines basic information about kernel livepatching.
> +
> +Table of Contents:
> +
> +1. Motivation
> +2. Kprobes, Ftrace, Livepatching
> +3. Consistency model
> +4. Livepatch module
> +   4.1. New functions
> +   4.2. Metadata
> +   4.3. Livepatch module handling
> +5. Livepatch life-cycle
> +   5.1. Registration
> +   5.2. Enabling
> +   5.3. Disabling
> +   5.4. Unregistration
> +6. Sysfs
> +7. Limitations
> +
> +
> +1. Motivation
> +=
> +
> +There are situations when people are really reluctant to reboot a system.
> +It might be because the computer is in the middle of a complex scientific
> +computation. Or the system is busy handling customer requests in the high
> +season.
> +
> +On the other hand, people also want to keep the system stable and secure.
> +This is where livepatch infrastructure comes handy. It allows selected
> +function calls to be redirected to a fixed implementation without
> +requiring a system reboot.
> +

There are many situations where users are reluctant to reboot a system. It may
be because their system is performing complex scientific computations or under
heavy load during peak usage. In addition to keeping systems up and running,
users want to also have a stable and secure system. Livepatching gives users
both by allowing for function calls to be redirected; thus, fixing critical
functions without a system reboot.

> +
> +2. Kprobes, Ftrace, Livepatching
> +
> +
> +There are multiple mechanisms in the Linux kernel that are directly related
> +to redirection of code execution; namely: kernel probes, function tracing,
> +and livepatching:
> +
> +  + The kernel probes are the most generic way. The code can be redirected
> +by putting an interrupt instruction instead of any instruction.
> +

I would drop 'way'. Just 'most generic'.

> +  + The function tracer calls the code from a predefined location that is
> +close the function entry. The location is generated by the compiler,
> +see -pg gcc option.
> +

  + The function tracer calls the code from a predefined location that is
close to the function entry point. This location is generated by the
compiler using the '-pg' gcc option.

> +  + Livepatching typically needs to redirect the code at the very beginning
> +of the function entry before the function parameters or the stack
> +are anyhow muffled.
> +

..or the stack are in anyway modified.

> +All three approaches need to modify the existing code at runtime. Therefore
> +they need to be aware of each other and do not step over each other's toes.

..+they need to be aware of each other and not step over each other's toes.

> +Most of these problems are solved by using the dynamic ftrace framework as
> +a base. A Kprobe is registered as a ftrace handler when the function entry
> +is probed, see CONFIG_KPROBES_ON_FTRACE. Also an alternative function from
> +a live patch is called with help of a custom ftrace handler. But there are

+a live patch is called with the help of a custom ftrace handler. But there are

> +some limitations, see below.
> +
> +
> +3. Consistency model
> +
> +
> +Functions are there for a reason. They take some input parameters, get or
> +release locks, read, process, and even write some data in a defined way,
> +have return values. In other words, each function has a defined semantic.
> +
> +Many fixes do not change the semantic of the modified functions. For
> +example, they add a NULL pointer or a boundary check, fix a race by adding
> +a missing memory barrier, or add 

Re: [PATCH v2] livepatch: Add some basic LivePatch documentation

[Chris J Arges]

On Mon, Apr 25, 2016 at 05:14:35PM +0200, Petr Mladek wrote:
> LivePatch framework deserves some documentation, definitely.
> This is an attempt to provide some basic info. I hope that
> it will be useful for both LivePatch producers and also
> potential developers of the framework itself.
> 
> Signed-off-by: Petr Mladek 
> ---
> 
> This version incorporates feedback from all people who
> commented on v1. Thanks a lot for it.
> 
> Sometimes I copy the suggested text. Sometimes,
> I used my own invention. The text has grown from 277 to
> 400 lines. I wish I had a lighter pen. Anyway, please
> see what I hammered together.
> 
> Changes against v1:
> 
> + switched the order of the section 4 and 5
> + tiny changes in sections 1,2,6
> + heavily updated sections 3,4,5,7
>

Suggestions for rewording and grammar fixes are inline. This is very useful!
--chris

 
>  Documentation/livepatch/livepatch.txt | 400 
> ++
>  MAINTAINERS   |   1 +
>  2 files changed, 401 insertions(+)
>  create mode 100644 Documentation/livepatch/livepatch.txt
> 
> diff --git a/Documentation/livepatch/livepatch.txt 
> b/Documentation/livepatch/livepatch.txt
> new file mode 100644
> index ..7c4777e3170c
> --- /dev/null
> +++ b/Documentation/livepatch/livepatch.txt
> @@ -0,0 +1,400 @@
> +=
> +Livepatch
> +=
> +
> +This document outlines basic information about kernel livepatching.
> +
> +Table of Contents:
> +
> +1. Motivation
> +2. Kprobes, Ftrace, Livepatching
> +3. Consistency model
> +4. Livepatch module
> +   4.1. New functions
> +   4.2. Metadata
> +   4.3. Livepatch module handling
> +5. Livepatch life-cycle
> +   5.1. Registration
> +   5.2. Enabling
> +   5.3. Disabling
> +   5.4. Unregistration
> +6. Sysfs
> +7. Limitations
> +
> +
> +1. Motivation
> +=
> +
> +There are situations when people are really reluctant to reboot a system.
> +It might be because the computer is in the middle of a complex scientific
> +computation. Or the system is busy handling customer requests in the high
> +season.
> +
> +On the other hand, people also want to keep the system stable and secure.
> +This is where livepatch infrastructure comes handy. It allows selected
> +function calls to be redirected to a fixed implementation without
> +requiring a system reboot.
> +

There are many situations where users are reluctant to reboot a system. It may
be because their system is performing complex scientific computations or under
heavy load during peak usage. In addition to keeping systems up and running,
users want to also have a stable and secure system. Livepatching gives users
both by allowing for function calls to be redirected; thus, fixing critical
functions without a system reboot.

> +
> +2. Kprobes, Ftrace, Livepatching
> +
> +
> +There are multiple mechanisms in the Linux kernel that are directly related
> +to redirection of code execution; namely: kernel probes, function tracing,
> +and livepatching:
> +
> +  + The kernel probes are the most generic way. The code can be redirected
> +by putting an interrupt instruction instead of any instruction.
> +

I would drop 'way'. Just 'most generic'.

> +  + The function tracer calls the code from a predefined location that is
> +close the function entry. The location is generated by the compiler,
> +see -pg gcc option.
> +

  + The function tracer calls the code from a predefined location that is
close to the function entry point. This location is generated by the
compiler using the '-pg' gcc option.

> +  + Livepatching typically needs to redirect the code at the very beginning
> +of the function entry before the function parameters or the stack
> +are anyhow muffled.
> +

..or the stack are in anyway modified.

> +All three approaches need to modify the existing code at runtime. Therefore
> +they need to be aware of each other and do not step over each other's toes.

..+they need to be aware of each other and not step over each other's toes.

> +Most of these problems are solved by using the dynamic ftrace framework as
> +a base. A Kprobe is registered as a ftrace handler when the function entry
> +is probed, see CONFIG_KPROBES_ON_FTRACE. Also an alternative function from
> +a live patch is called with help of a custom ftrace handler. But there are

+a live patch is called with the help of a custom ftrace handler. But there are

> +some limitations, see below.
> +
> +
> +3. Consistency model
> +
> +
> +Functions are there for a reason. They take some input parameters, get or
> +release locks, read, process, and even write some data in a defined way,
> +have return values. In other words, each function has a defined semantic.
> +
> +Many fixes do not change the semantic of the modified functions. For
> +example, they add a NULL pointer or a boundary check, fix a race by adding
> +a missing memory barrier, or add some locking about 

Re: [PATCH v2] livepatch: Add some basic LivePatch documentation

[Balbir Singh]

Hi Petr

Very very nice documentation, some comments inline

Reviewed-by: Balbir Singh 

Balbir

On 26/04/16 01:14, Petr Mladek wrote:
> LivePatch framework deserves some documentation, definitely.
> This is an attempt to provide some basic info. I hope that
> it will be useful for both LivePatch producers and also
> potential developers of the framework itself.
> 
> Signed-off-by: Petr Mladek 
> ---
> 
> This version incorporates feedback from all people who
> commented on v1. Thanks a lot for it.
> 
> Sometimes I copy the suggested text. Sometimes,
> I used my own invention. The text has grown from 277 to
> 400 lines. I wish I had a lighter pen. Anyway, please
> see what I hammered together.
> 
> Changes against v1:
> 
> + switched the order of the section 4 and 5
> + tiny changes in sections 1,2,6
> + heavily updated sections 3,4,5,7
> 
>  Documentation/livepatch/livepatch.txt | 400 
> ++
>  MAINTAINERS   |   1 +
>  2 files changed, 401 insertions(+)
>  create mode 100644 Documentation/livepatch/livepatch.txt
> 
> diff --git a/Documentation/livepatch/livepatch.txt 
> b/Documentation/livepatch/livepatch.txt
> new file mode 100644
> index ..7c4777e3170c
> --- /dev/null
> +++ b/Documentation/livepatch/livepatch.txt
> @@ -0,0 +1,400 @@
> +=
> +Livepatch
> +=
> +
> +This document outlines basic information about kernel livepatching.
> +
> +Table of Contents:
> +
> +1. Motivation
> +2. Kprobes, Ftrace, Livepatching
> +3. Consistency model
> +4. Livepatch module
> +   4.1. New functions
> +   4.2. Metadata
> +   4.3. Livepatch module handling
> +5. Livepatch life-cycle
> +   5.1. Registration
> +   5.2. Enabling
> +   5.3. Disabling
> +   5.4. Unregistration
> +6. Sysfs
> +7. Limitations
> +
> +
> +1. Motivation
> +=
> +
> +There are situations when people are really reluctant to reboot a system.

Could we just state that

"It is usually desired in production systems to have an uptime as large as 
possible, unless
it is really necessary for things like updates (most frequently security 
updates and bug fixes)

> +It might be because the computer is in the middle of a complex scientific
> +computation. Or the system is busy handling customer requests in the high
> +season.
> +
> +On the other hand, people also want to keep the system stable and secure.
> +This is where livepatch infrastructure comes handy. It allows selected
> +function calls to be redirected to a fixed implementation without

I think a fixed implementation's meaning might not be clear, can we say
that livepatch patches or fixes potentially buggy functionality and in
some cases might enhance functionality (not recommended) without

> +requiring a system reboot.
> +
> +
> +2. Kprobes, Ftrace, Livepatching
> +
> +
> +There are multiple mechanisms in the Linux kernel that are directly related
> +to redirection of code execution; namely: kernel probes, function tracing,
> +and livepatching:
> +
> +  + The kernel probes are the most generic way. The code can be redirected
> +by putting an interrupt instruction instead of any instruction.
> +

interrupt instruction is not clear. I think you mean a breakpoint

> +  + The function tracer calls the code from a predefined location that is
> +close the function entry. The location is generated by the compiler,
> +see -pg gcc option.
> +
> +  + Livepatching typically needs to redirect the code at the very beginning
> +of the function entry before the function parameters or the stack
> +are anyhow muffled.
> +


> +All three approaches need to modify the existing code at runtime. Therefore


I think 1 and 2 are approaches, 3 is a statement about live-patching.

> +they need to be aware of each other and do not step over each other's toes.
> +Most of these problems are solved by using the dynamic ftrace framework as
> +a base. A Kprobe is registered as a ftrace handler when the function entry
> +is probed, see CONFIG_KPROBES_ON_FTRACE. Also an alternative function from
> +a live patch is called with help of a custom ftrace handler. But there are
> +some limitations, see below.
> +
> +
> +3. Consistency model
> +
> +
> +Functions are there for a reason. They take some input parameters, get or
> +release locks, read, process, and even write some data in a defined way,
> +have return values. In other words, each function has a defined semantic.
> +
> +Many fixes do not change the semantic of the modified functions. For
> +example, they add a NULL pointer or a boundary check, fix a race by adding
> +a missing memory barrier, or add some locking about a critical section.
> +Most of these changes are self contained and the function present itself
> +the same way to the rest of the system. In this case, the functions might
> +be updated independently one by one.
> +
> +But there are more complex fixes. For 

Re: [PATCH v2] livepatch: Add some basic LivePatch documentation

[Balbir Singh]

Hi Petr

Very very nice documentation, some comments inline

Reviewed-by: Balbir Singh 

Balbir

On 26/04/16 01:14, Petr Mladek wrote:
> LivePatch framework deserves some documentation, definitely.
> This is an attempt to provide some basic info. I hope that
> it will be useful for both LivePatch producers and also
> potential developers of the framework itself.
> 
> Signed-off-by: Petr Mladek 
> ---
> 
> This version incorporates feedback from all people who
> commented on v1. Thanks a lot for it.
> 
> Sometimes I copy the suggested text. Sometimes,
> I used my own invention. The text has grown from 277 to
> 400 lines. I wish I had a lighter pen. Anyway, please
> see what I hammered together.
> 
> Changes against v1:
> 
> + switched the order of the section 4 and 5
> + tiny changes in sections 1,2,6
> + heavily updated sections 3,4,5,7
> 
>  Documentation/livepatch/livepatch.txt | 400 
> ++
>  MAINTAINERS   |   1 +
>  2 files changed, 401 insertions(+)
>  create mode 100644 Documentation/livepatch/livepatch.txt
> 
> diff --git a/Documentation/livepatch/livepatch.txt 
> b/Documentation/livepatch/livepatch.txt
> new file mode 100644
> index ..7c4777e3170c
> --- /dev/null
> +++ b/Documentation/livepatch/livepatch.txt
> @@ -0,0 +1,400 @@
> +=
> +Livepatch
> +=
> +
> +This document outlines basic information about kernel livepatching.
> +
> +Table of Contents:
> +
> +1. Motivation
> +2. Kprobes, Ftrace, Livepatching
> +3. Consistency model
> +4. Livepatch module
> +   4.1. New functions
> +   4.2. Metadata
> +   4.3. Livepatch module handling
> +5. Livepatch life-cycle
> +   5.1. Registration
> +   5.2. Enabling
> +   5.3. Disabling
> +   5.4. Unregistration
> +6. Sysfs
> +7. Limitations
> +
> +
> +1. Motivation
> +=
> +
> +There are situations when people are really reluctant to reboot a system.

Could we just state that

"It is usually desired in production systems to have an uptime as large as 
possible, unless
it is really necessary for things like updates (most frequently security 
updates and bug fixes)

> +It might be because the computer is in the middle of a complex scientific
> +computation. Or the system is busy handling customer requests in the high
> +season.
> +
> +On the other hand, people also want to keep the system stable and secure.
> +This is where livepatch infrastructure comes handy. It allows selected
> +function calls to be redirected to a fixed implementation without

I think a fixed implementation's meaning might not be clear, can we say
that livepatch patches or fixes potentially buggy functionality and in
some cases might enhance functionality (not recommended) without

> +requiring a system reboot.
> +
> +
> +2. Kprobes, Ftrace, Livepatching
> +
> +
> +There are multiple mechanisms in the Linux kernel that are directly related
> +to redirection of code execution; namely: kernel probes, function tracing,
> +and livepatching:
> +
> +  + The kernel probes are the most generic way. The code can be redirected
> +by putting an interrupt instruction instead of any instruction.
> +

interrupt instruction is not clear. I think you mean a breakpoint

> +  + The function tracer calls the code from a predefined location that is
> +close the function entry. The location is generated by the compiler,
> +see -pg gcc option.
> +
> +  + Livepatching typically needs to redirect the code at the very beginning
> +of the function entry before the function parameters or the stack
> +are anyhow muffled.
> +


> +All three approaches need to modify the existing code at runtime. Therefore


I think 1 and 2 are approaches, 3 is a statement about live-patching.

> +they need to be aware of each other and do not step over each other's toes.
> +Most of these problems are solved by using the dynamic ftrace framework as
> +a base. A Kprobe is registered as a ftrace handler when the function entry
> +is probed, see CONFIG_KPROBES_ON_FTRACE. Also an alternative function from
> +a live patch is called with help of a custom ftrace handler. But there are
> +some limitations, see below.
> +
> +
> +3. Consistency model
> +
> +
> +Functions are there for a reason. They take some input parameters, get or
> +release locks, read, process, and even write some data in a defined way,
> +have return values. In other words, each function has a defined semantic.
> +
> +Many fixes do not change the semantic of the modified functions. For
> +example, they add a NULL pointer or a boundary check, fix a race by adding
> +a missing memory barrier, or add some locking about a critical section.
> +Most of these changes are self contained and the function present itself
> +the same way to the rest of the system. In this case, the functions might
> +be updated independently one by one.
> +
> +But there are more complex fixes. For example, a patch might change
> +ordering 

[PATCH v2] livepatch: Add some basic LivePatch documentation

[Petr Mladek]

LivePatch framework deserves some documentation, definitely.
This is an attempt to provide some basic info. I hope that
it will be useful for both LivePatch producers and also
potential developers of the framework itself.

Signed-off-by: Petr Mladek 
---

This version incorporates feedback from all people who
commented on v1. Thanks a lot for it.

Sometimes I copy the suggested text. Sometimes,
I used my own invention. The text has grown from 277 to
400 lines. I wish I had a lighter pen. Anyway, please
see what I hammered together.

Changes against v1:

+ switched the order of the section 4 and 5
+ tiny changes in sections 1,2,6
+ heavily updated sections 3,4,5,7

 Documentation/livepatch/livepatch.txt | 400 ++
 MAINTAINERS   |   1 +
 2 files changed, 401 insertions(+)
 create mode 100644 Documentation/livepatch/livepatch.txt

diff --git a/Documentation/livepatch/livepatch.txt 
b/Documentation/livepatch/livepatch.txt
new file mode 100644
index ..7c4777e3170c
--- /dev/null
+++ b/Documentation/livepatch/livepatch.txt
@@ -0,0 +1,400 @@
+=
+Livepatch
+=
+
+This document outlines basic information about kernel livepatching.
+
+Table of Contents:
+
+1. Motivation
+2. Kprobes, Ftrace, Livepatching
+3. Consistency model
+4. Livepatch module
+   4.1. New functions
+   4.2. Metadata
+   4.3. Livepatch module handling
+5. Livepatch life-cycle
+   5.1. Registration
+   5.2. Enabling
+   5.3. Disabling
+   5.4. Unregistration
+6. Sysfs
+7. Limitations
+
+
+1. Motivation
+=
+
+There are situations when people are really reluctant to reboot a system.
+It might be because the computer is in the middle of a complex scientific
+computation. Or the system is busy handling customer requests in the high
+season.
+
+On the other hand, people also want to keep the system stable and secure.
+This is where livepatch infrastructure comes handy. It allows selected
+function calls to be redirected to a fixed implementation without
+requiring a system reboot.
+
+
+2. Kprobes, Ftrace, Livepatching
+
+
+There are multiple mechanisms in the Linux kernel that are directly related
+to redirection of code execution; namely: kernel probes, function tracing,
+and livepatching:
+
+  + The kernel probes are the most generic way. The code can be redirected
+by putting an interrupt instruction instead of any instruction.
+
+  + The function tracer calls the code from a predefined location that is
+close the function entry. The location is generated by the compiler,
+see -pg gcc option.
+
+  + Livepatching typically needs to redirect the code at the very beginning
+of the function entry before the function parameters or the stack
+are anyhow muffled.
+
+All three approaches need to modify the existing code at runtime. Therefore
+they need to be aware of each other and do not step over each other's toes.
+Most of these problems are solved by using the dynamic ftrace framework as
+a base. A Kprobe is registered as a ftrace handler when the function entry
+is probed, see CONFIG_KPROBES_ON_FTRACE. Also an alternative function from
+a live patch is called with help of a custom ftrace handler. But there are
+some limitations, see below.
+
+
+3. Consistency model
+
+
+Functions are there for a reason. They take some input parameters, get or
+release locks, read, process, and even write some data in a defined way,
+have return values. In other words, each function has a defined semantic.
+
+Many fixes do not change the semantic of the modified functions. For
+example, they add a NULL pointer or a boundary check, fix a race by adding
+a missing memory barrier, or add some locking about a critical section.
+Most of these changes are self contained and the function present itself
+the same way to the rest of the system. In this case, the functions might
+be updated independently one by one.
+
+But there are more complex fixes. For example, a patch might change
+ordering of locking in more functions at the same time. Or a patch
+might exchange meaning of some temporary structures and update
+all the relevant functions. In this case, the affected unit
+(thread, whole kernel) need to start using all new versions of
+the functions at the same time. Also the switch must happen only
+when it is safe to do so, e.g. when the affected locks are released
+or no data are stored in the modified structures at the moment.
+
+The theory about how to apply functions a safe way is rather complex.
+The aim is to define a so-called consistency model. It means to define
+conditions when the new implementation could be used so that the system
+stays consistent. The theory is not yet finished. See the discussion at
+http://thread.gmane.org/gmane.linux.kernel/1823033/focus=1828189
+
+The current consistency model is very simple. It guarantees that either
+the old or the new function is called. But 

[PATCH v2] livepatch: Add some basic LivePatch documentation

[Petr Mladek]

LivePatch framework deserves some documentation, definitely.
This is an attempt to provide some basic info. I hope that
it will be useful for both LivePatch producers and also
potential developers of the framework itself.

Signed-off-by: Petr Mladek 
---

This version incorporates feedback from all people who
commented on v1. Thanks a lot for it.

Sometimes I copy the suggested text. Sometimes,
I used my own invention. The text has grown from 277 to
400 lines. I wish I had a lighter pen. Anyway, please
see what I hammered together.

Changes against v1:

+ switched the order of the section 4 and 5
+ tiny changes in sections 1,2,6
+ heavily updated sections 3,4,5,7

 Documentation/livepatch/livepatch.txt | 400 ++
 MAINTAINERS   |   1 +
 2 files changed, 401 insertions(+)
 create mode 100644 Documentation/livepatch/livepatch.txt

diff --git a/Documentation/livepatch/livepatch.txt 
b/Documentation/livepatch/livepatch.txt
new file mode 100644
index ..7c4777e3170c
--- /dev/null
+++ b/Documentation/livepatch/livepatch.txt
@@ -0,0 +1,400 @@
+=
+Livepatch
+=
+
+This document outlines basic information about kernel livepatching.
+
+Table of Contents:
+
+1. Motivation
+2. Kprobes, Ftrace, Livepatching
+3. Consistency model
+4. Livepatch module
+   4.1. New functions
+   4.2. Metadata
+   4.3. Livepatch module handling
+5. Livepatch life-cycle
+   5.1. Registration
+   5.2. Enabling
+   5.3. Disabling
+   5.4. Unregistration
+6. Sysfs
+7. Limitations
+
+
+1. Motivation
+=
+
+There are situations when people are really reluctant to reboot a system.
+It might be because the computer is in the middle of a complex scientific
+computation. Or the system is busy handling customer requests in the high
+season.
+
+On the other hand, people also want to keep the system stable and secure.
+This is where livepatch infrastructure comes handy. It allows selected
+function calls to be redirected to a fixed implementation without
+requiring a system reboot.
+
+
+2. Kprobes, Ftrace, Livepatching
+
+
+There are multiple mechanisms in the Linux kernel that are directly related
+to redirection of code execution; namely: kernel probes, function tracing,
+and livepatching:
+
+  + The kernel probes are the most generic way. The code can be redirected
+by putting an interrupt instruction instead of any instruction.
+
+  + The function tracer calls the code from a predefined location that is
+close the function entry. The location is generated by the compiler,
+see -pg gcc option.
+
+  + Livepatching typically needs to redirect the code at the very beginning
+of the function entry before the function parameters or the stack
+are anyhow muffled.
+
+All three approaches need to modify the existing code at runtime. Therefore
+they need to be aware of each other and do not step over each other's toes.
+Most of these problems are solved by using the dynamic ftrace framework as
+a base. A Kprobe is registered as a ftrace handler when the function entry
+is probed, see CONFIG_KPROBES_ON_FTRACE. Also an alternative function from
+a live patch is called with help of a custom ftrace handler. But there are
+some limitations, see below.
+
+
+3. Consistency model
+
+
+Functions are there for a reason. They take some input parameters, get or
+release locks, read, process, and even write some data in a defined way,
+have return values. In other words, each function has a defined semantic.
+
+Many fixes do not change the semantic of the modified functions. For
+example, they add a NULL pointer or a boundary check, fix a race by adding
+a missing memory barrier, or add some locking about a critical section.
+Most of these changes are self contained and the function present itself
+the same way to the rest of the system. In this case, the functions might
+be updated independently one by one.
+
+But there are more complex fixes. For example, a patch might change
+ordering of locking in more functions at the same time. Or a patch
+might exchange meaning of some temporary structures and update
+all the relevant functions. In this case, the affected unit
+(thread, whole kernel) need to start using all new versions of
+the functions at the same time. Also the switch must happen only
+when it is safe to do so, e.g. when the affected locks are released
+or no data are stored in the modified structures at the moment.
+
+The theory about how to apply functions a safe way is rather complex.
+The aim is to define a so-called consistency model. It means to define
+conditions when the new implementation could be used so that the system
+stays consistent. The theory is not yet finished. See the discussion at
+http://thread.gmane.org/gmane.linux.kernel/1823033/focus=1828189
+
+The current consistency model is very simple. It guarantees that either
+the old or the new function is called. But various functions