Re: [PATCH] Documentation: kdump: describe jumping to dump-capture kernel

[Dave Young]

Hi,
On 02/13/18 at 04:22pm, Gioh Kim wrote:
> Jumping between the system kernel and the dump-capture kernel
> has been supported for long time but there is no description
> how to use it. This patch adds the description how to use kexec tool
> to jump to the dump-capture kernel and jump back to the system kernel.

I do not think this should belong to kdump documentation.  There are a
lot of choices after a vmcore saving, one can reboot, halt, even go
ahead with real root filesystem init path.  We do not need to document
all these in kdump.txt.

Since it is a general use case not only for kdump, add more info in
kexec man page would be better.

> 
> Signed-off-by: Gioh Kim 
> ---
>  Documentation/kdump/kdump.txt | 38 ++
>  1 file changed, 38 insertions(+)
> 
> diff --git a/Documentation/kdump/kdump.txt b/Documentation/kdump/kdump.txt
> index 51814450a7f8..35b71fef5d88 100644
> --- a/Documentation/kdump/kdump.txt
> +++ b/Documentation/kdump/kdump.txt
> @@ -460,6 +460,44 @@ and the system will boot into the dump-capture kernel.
>  For testing purposes, you can trigger a crash by using "ALT-SysRq-c",
>  "echo c > /proc/sysrq-trigger" or write a module to force the panic.
>  
> +Jump between the System kernel and the Dump-capture kernel
> +===
> +
> +Without system crash, the system can jump to the dump-capture kernel.
> +
> +1) Enable "jump between system kernel and dump-capture kernel" support under
> +   "Processor type and features"
> +
> +   CONFIG_KEXEC_JUMP=y
> +
> +2) Load the dump-capture kernel with --load-preserve-context and mem-max
> +   options as following.
> +
> +   kexec -l  \
> +   --initrd= --args-linux \
> +   --append="root= " \
> +   --load-preserve-context \
> +   --mem-max=
> +
> +3) Jump to the loaded kernel
> +
> +   kexec -e
> +
> +Now the system is running with the dump-capture kernel. You can jump back
> +to the system kernel.
> +
> +1) Find kexec_jump_back_entry address in kernel booting parameters in
> +   /proc/cmdline. That is the address for kexec to jump to. For example:
> +   kexec_jump_back_entry=0x000810d2
> +
> +2) Following command sets the jump-back address for kexec.
> +
> +   kexec --load-jump-back-helper --entry=0x810d2
> +
> +3) Jump to the system kernel
> +
> +   kexec -e
> +
>  Write Out the Dump File
>  ===
>  
> -- 
> 2.11.0
> 

Thanks
Dave
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch 1/2] mm, page_alloc: extend kernelcore and movablecore for percent

[Andrew Morton]

On Tue, 13 Feb 2018 15:55:11 -0800 (PST) David Rientjes  
wrote:

> > 
> > Is this fine-grained enough?  We've had percentage-based tunables in
> > the past, and 10 years later when systems are vastly larger, 1% is too
> > much.
> > 
> 
> They still have the (current) ability to define the exact amount of bytes 
> down to page sized granularity, whereas 1% would yield 40GB on a 4TB 
> system.  I'm not sure that people will want any finer-grained control if 
> defining the proportion of the system for kernelcore.  They do have the 
> ability with the existing interface, though, if they want to be that 
> precise.
> 
> (This is a cop out for not implementing some fractional percentage parser, 
>  although that would be possible as a more complete solution.)

And the interface which you've proposed can be seamlessly extended to
accept 0.07%, so not a problem.

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch -mm] mm, page_alloc: extend kernelcore and movablecore for percent fix

[Mike Kravetz]

On 02/13/2018 05:00 PM, David Rientjes wrote:
> Specify that movablecore= can use a percent value.
> 
> Remove comment about hugetlb pages not being movable per Mike.
> 
> Cc: Mike Kravetz 
> Signed-off-by: David Rientjes 

Thanks!  FWIW,
Reviewed-by: Mike Kravetz 
And, that is for all of patch 1.
-- 
Mike Kravetz

> ---
>  .../admin-guide/kernel-parameters.txt | 22 +--
>  1 file changed, 11 insertions(+), 11 deletions(-)
> 
> diff --git a/Documentation/admin-guide/kernel-parameters.txt 
> b/Documentation/admin-guide/kernel-parameters.txt
> --- a/Documentation/admin-guide/kernel-parameters.txt
> +++ b/Documentation/admin-guide/kernel-parameters.txt
> @@ -1837,10 +1837,9 @@
>  
>   ZONE_MOVABLE is used for the allocation of pages that
>   may be reclaimed or moved by the page migration
> - subsystem.  This means that HugeTLB pages may not be
> - allocated from this zone.  Note that allocations like
> - PTEs-from-HighMem still use the HighMem zone if it
> - exists, and the Normal zone if it does not.
> + subsystem.  Note that allocations like PTEs-from-HighMem
> + still use the HighMem zone if it exists, and the Normal
> + zone if it does not.
>  
>   It is possible to specify the exact amount of memory in
>   the form of "nn[KMGTPE]", a percentage of total system
> @@ -2353,13 +2352,14 @@
>   mousedev.yres=  [MOUSE] Vertical screen resolution, used for devices
>   reporting absolute coordinates, such as tablets
>  
> - movablecore=nn[KMG] [KNL,X86,IA-64,PPC] This parameter
> - is similar to kernelcore except it specifies the
> - amount of memory used for migratable allocations.
> - If both kernelcore and movablecore is specified,
> - then kernelcore will be at *least* the specified
> - value but may be more. If movablecore on its own
> - is specified, the administrator must be careful
> + movablecore=[KNL,X86,IA-64,PPC]
> + Format: nn[KMGTPE] | nn%
> + This parameter is the complement to kernelcore=, it
> + specifies the amount of memory used for migratable
> + allocations.  If both kernelcore and movablecore is
> + specified, then kernelcore will be at *least* the
> + specified value but may be more.  If movablecore on its
> + own is specified, the administrator must be careful
>   that the amount of memory usable for all allocations
>   is not too small.
>  
> 
> --
> To unsubscribe, send a message with 'unsubscribe linux-mm' in
> the body to majord...@kvack.org.  For more info on Linux MM,
> see: http://www.linux-mm.org/ .
> Don't email: mailto:"d...@kvack.org;> em...@kvack.org 
> 
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[patch -mm] mm, page_alloc: extend kernelcore and movablecore for percent fix

[David Rientjes]

Specify that movablecore= can use a percent value.

Remove comment about hugetlb pages not being movable per Mike.

Cc: Mike Kravetz 
Signed-off-by: David Rientjes 
---
 .../admin-guide/kernel-parameters.txt | 22 +--
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/Documentation/admin-guide/kernel-parameters.txt 
b/Documentation/admin-guide/kernel-parameters.txt
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -1837,10 +1837,9 @@
 
ZONE_MOVABLE is used for the allocation of pages that
may be reclaimed or moved by the page migration
-   subsystem.  This means that HugeTLB pages may not be
-   allocated from this zone.  Note that allocations like
-   PTEs-from-HighMem still use the HighMem zone if it
-   exists, and the Normal zone if it does not.
+   subsystem.  Note that allocations like PTEs-from-HighMem
+   still use the HighMem zone if it exists, and the Normal
+   zone if it does not.
 
It is possible to specify the exact amount of memory in
the form of "nn[KMGTPE]", a percentage of total system
@@ -2353,13 +2352,14 @@
mousedev.yres=  [MOUSE] Vertical screen resolution, used for devices
reporting absolute coordinates, such as tablets
 
-   movablecore=nn[KMG] [KNL,X86,IA-64,PPC] This parameter
-   is similar to kernelcore except it specifies the
-   amount of memory used for migratable allocations.
-   If both kernelcore and movablecore is specified,
-   then kernelcore will be at *least* the specified
-   value but may be more. If movablecore on its own
-   is specified, the administrator must be careful
+   movablecore=[KNL,X86,IA-64,PPC]
+   Format: nn[KMGTPE] | nn%
+   This parameter is the complement to kernelcore=, it
+   specifies the amount of memory used for migratable
+   allocations.  If both kernelcore and movablecore is
+   specified, then kernelcore will be at *least* the
+   specified value but may be more.  If movablecore on its
+   own is specified, the administrator must be careful
that the amount of memory usable for all allocations
is not too small.
 
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch 1/2] mm, page_alloc: extend kernelcore and movablecore for percent

[David Rientjes]

On Tue, 13 Feb 2018, Mike Kravetz wrote:

> > diff --git a/Documentation/admin-guide/kernel-parameters.txt 
> > b/Documentation/admin-guide/kernel-parameters.txt
> > --- a/Documentation/admin-guide/kernel-parameters.txt
> > +++ b/Documentation/admin-guide/kernel-parameters.txt
> > @@ -1825,30 +1825,30 @@
> > keepinitrd  [HW,ARM]
> >  
> > kernelcore= [KNL,X86,IA-64,PPC]
> > -   Format: nn[KMGTPE] | "mirror"
> > -   This parameter
> > -   specifies the amount of memory usable by the kernel
> > -   for non-movable allocations.  The requested amount is
> > -   spread evenly throughout all nodes in the system. The
> > -   remaining memory in each node is used for Movable
> > -   pages. In the event, a node is too small to have both
> > -   kernelcore and Movable pages, kernelcore pages will
> > -   take priority and other nodes will have a larger number
> > -   of Movable pages.  The Movable zone is used for the
> > -   allocation of pages that may be reclaimed or moved
> > -   by the page migration subsystem.  This means that
> > -   HugeTLB pages may not be allocated from this zone.
> > -   Note that allocations like PTEs-from-HighMem still
> > -   use the HighMem zone if it exists, and the Normal
> > -   zone if it does not.
> > -
> > -   Instead of specifying the amount of memory (nn[KMGTPE]),
> > -   you can specify "mirror" option. In case "mirror"
> > +   Format: nn[KMGTPE] | nn% | "mirror"
> > +   This parameter specifies the amount of memory usable by
> > +   the kernel for non-movable allocations.  The requested
> > +   amount is spread evenly throughout all nodes in the
> > +   system as ZONE_NORMAL.  The remaining memory is used for
> > +   movable memory in its own zone, ZONE_MOVABLE.  In the
> > +   event, a node is too small to have both ZONE_NORMAL and
> > +   ZONE_MOVABLE, kernelcore memory will take priority and
> > +   other nodes will have a larger ZONE_MOVABLE.
> > +
> > +   ZONE_MOVABLE is used for the allocation of pages that
> > +   may be reclaimed or moved by the page migration
> > +   subsystem.  This means that HugeTLB pages may not be
> > +   allocated from this zone.  Note that allocations like
> > +   PTEs-from-HighMem still use the HighMem zone if it
> > +   exists, and the Normal zone if it does not.
> 
> I know you are just updating the documentation for the new ability to
> specify a percentage.  However, while looking at this I noticed that
> the existing description is out of date.  HugeTLB pages CAN be treated
> as movable and allocated from ZONE_MOVABLE.
> 
> If you have to respin, could you drop that line while making this change?
> 

Hi Mike,

It's merged in -mm, so perhaps no respin is necessary.  I think a general 
cleanup to this area regarding your work with hugetlb pages would be good.

> > +
> > +   It is possible to specify the exact amount of memory in
> > +   the form of "nn[KMGTPE]", a percentage of total system
> > +   memory in the form of "nn%", or "mirror".  If "mirror"
> > option is specified, mirrored (reliable) memory is used
> > for non-movable allocations and remaining memory is used
> > -   for Movable pages. nn[KMGTPE] and "mirror" are 
> > exclusive,
> > -   so you can NOT specify nn[KMGTPE] and "mirror" at the 
> > same
> > -   time.
> > +   for Movable pages.  "nn[KMGTPE]", "nn%", and "mirror"
> > +   are exclusive, so you cannot specify multiple forms.
> >  
> > kgdbdbgp=   [KGDB,HW] kgdb over EHCI usb debug port.
> > Format: [,poll interval]
> 
> Don't you need to make the same type percentage changes for 'movablecore='?
> 

The majority of the movablecore= documentation simply refers to the 
kernelcore= option as its complement, I'm not sure that we need to go 
in-depth into what the percentage specifiers mean for both options.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch 1/2] mm, page_alloc: extend kernelcore and movablecore for percent

[Mike Kravetz]

On 02/12/2018 04:24 PM, David Rientjes wrote:
> Both kernelcore= and movablecore= can be used to define the amount of
> ZONE_NORMAL and ZONE_MOVABLE on a system, respectively.  This requires
> the system memory capacity to be known when specifying the command line,
> however.
> 
> This introduces the ability to define both kernelcore= and movablecore=
> as a percentage of total system memory.  This is convenient for systems
> software that wants to define the amount of ZONE_MOVABLE, for example, as
> a proportion of a system's memory rather than a hardcoded byte value.
> 
> To define the percentage, the final character of the parameter should be
> a '%'.
> 
> Signed-off-by: David Rientjes 
> ---
>  Documentation/admin-guide/kernel-parameters.txt | 44 
> -
>  mm/page_alloc.c | 43 +++-
>  2 files changed, 57 insertions(+), 30 deletions(-)
> 
> diff --git a/Documentation/admin-guide/kernel-parameters.txt 
> b/Documentation/admin-guide/kernel-parameters.txt
> --- a/Documentation/admin-guide/kernel-parameters.txt
> +++ b/Documentation/admin-guide/kernel-parameters.txt
> @@ -1825,30 +1825,30 @@
>   keepinitrd  [HW,ARM]
>  
>   kernelcore= [KNL,X86,IA-64,PPC]
> - Format: nn[KMGTPE] | "mirror"
> - This parameter
> - specifies the amount of memory usable by the kernel
> - for non-movable allocations.  The requested amount is
> - spread evenly throughout all nodes in the system. The
> - remaining memory in each node is used for Movable
> - pages. In the event, a node is too small to have both
> - kernelcore and Movable pages, kernelcore pages will
> - take priority and other nodes will have a larger number
> - of Movable pages.  The Movable zone is used for the
> - allocation of pages that may be reclaimed or moved
> - by the page migration subsystem.  This means that
> - HugeTLB pages may not be allocated from this zone.
> - Note that allocations like PTEs-from-HighMem still
> - use the HighMem zone if it exists, and the Normal
> - zone if it does not.
> -
> - Instead of specifying the amount of memory (nn[KMGTPE]),
> - you can specify "mirror" option. In case "mirror"
> + Format: nn[KMGTPE] | nn% | "mirror"
> + This parameter specifies the amount of memory usable by
> + the kernel for non-movable allocations.  The requested
> + amount is spread evenly throughout all nodes in the
> + system as ZONE_NORMAL.  The remaining memory is used for
> + movable memory in its own zone, ZONE_MOVABLE.  In the
> + event, a node is too small to have both ZONE_NORMAL and
> + ZONE_MOVABLE, kernelcore memory will take priority and
> + other nodes will have a larger ZONE_MOVABLE.
> +
> + ZONE_MOVABLE is used for the allocation of pages that
> + may be reclaimed or moved by the page migration
> + subsystem.  This means that HugeTLB pages may not be
> + allocated from this zone.  Note that allocations like
> + PTEs-from-HighMem still use the HighMem zone if it
> + exists, and the Normal zone if it does not.

I know you are just updating the documentation for the new ability to
specify a percentage.  However, while looking at this I noticed that
the existing description is out of date.  HugeTLB pages CAN be treated
as movable and allocated from ZONE_MOVABLE.

If you have to respin, could you drop that line while making this change?

> +
> + It is possible to specify the exact amount of memory in
> + the form of "nn[KMGTPE]", a percentage of total system
> + memory in the form of "nn%", or "mirror".  If "mirror"
>   option is specified, mirrored (reliable) memory is used
>   for non-movable allocations and remaining memory is used
> - for Movable pages. nn[KMGTPE] and "mirror" are 
> exclusive,
> - so you can NOT specify nn[KMGTPE] and "mirror" at the 
> same
> - time.
> + for Movable pages.  "nn[KMGTPE]", "nn%", and "mirror"
> + are exclusive, so you cannot specify multiple forms.
>  
>   kgdbdbgp=   [KGDB,HW] kgdb over EHCI usb debug port.
>   Format: [,poll interval]

Don't you need to make the same type percentage changes for 

Re: [patch 1/2] mm, page_alloc: extend kernelcore and movablecore for percent

[David Rientjes]

On Tue, 13 Feb 2018, Andrew Morton wrote:

> > Both kernelcore= and movablecore= can be used to define the amount of
> > ZONE_NORMAL and ZONE_MOVABLE on a system, respectively.  This requires
> > the system memory capacity to be known when specifying the command line,
> > however.
> > 
> > This introduces the ability to define both kernelcore= and movablecore=
> > as a percentage of total system memory.  This is convenient for systems
> > software that wants to define the amount of ZONE_MOVABLE, for example, as
> > a proportion of a system's memory rather than a hardcoded byte value.
> > 
> > To define the percentage, the final character of the parameter should be
> > a '%'.
> 
> Is this fine-grained enough?  We've had percentage-based tunables in
> the past, and 10 years later when systems are vastly larger, 1% is too
> much.
> 

They still have the (current) ability to define the exact amount of bytes 
down to page sized granularity, whereas 1% would yield 40GB on a 4TB 
system.  I'm not sure that people will want any finer-grained control if 
defining the proportion of the system for kernelcore.  They do have the 
ability with the existing interface, though, if they want to be that 
precise.

(This is a cop out for not implementing some fractional percentage parser, 
 although that would be possible as a more complete solution.)
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch 1/2] mm, page_alloc: extend kernelcore and movablecore for percent

[Andrew Morton]

On Mon, 12 Feb 2018 16:24:25 -0800 (PST) David Rientjes  
wrote:

> Both kernelcore= and movablecore= can be used to define the amount of
> ZONE_NORMAL and ZONE_MOVABLE on a system, respectively.  This requires
> the system memory capacity to be known when specifying the command line,
> however.
> 
> This introduces the ability to define both kernelcore= and movablecore=
> as a percentage of total system memory.  This is convenient for systems
> software that wants to define the amount of ZONE_MOVABLE, for example, as
> a proportion of a system's memory rather than a hardcoded byte value.
> 
> To define the percentage, the final character of the parameter should be
> a '%'.

Is this fine-grained enough?  We've had percentage-based tunables in
the past, and 10 years later when systems are vastly larger, 1% is too
much.

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] admin-guide: Fix list formatting in tained-kernels.html

[Jonathan Neuschäfer]

Without this patch, the points 1-9 in the list are rendered as an HTML
blockquote containing a list, causing them to be indented further than
the rest of the list.

While at it, also fix the quotation marks around G and P.

Signed-off-by: Jonathan Neuschäfer 
---
 Documentation/admin-guide/tainted-kernels.rst | 18 +-
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/Documentation/admin-guide/tainted-kernels.rst 
b/Documentation/admin-guide/tainted-kernels.rst
index 1df03b5cb02f..28a869c509a0 100644
--- a/Documentation/admin-guide/tainted-kernels.rst
+++ b/Documentation/admin-guide/tainted-kernels.rst
@@ -6,34 +6,34 @@ counter. This indicates that the kernel has been tainted by 
some
 mechanism.  The string is followed by a series of position-sensitive
 characters, each representing a particular tainted value.
 
-  1) 'G' if all modules loaded have a GPL or compatible license, 'P' if
+ 1)  ``G`` if all modules loaded have a GPL or compatible license, ``P`` if
  any proprietary module has been loaded.  Modules without a
  MODULE_LICENSE or with a MODULE_LICENSE that is not recognised by
  insmod as GPL compatible are assumed to be proprietary.
 
-  2) ``F`` if any module was force loaded by ``insmod -f``, ``' '`` if all
+ 2)  ``F`` if any module was force loaded by ``insmod -f``, ``' '`` if all
  modules were loaded normally.
 
-  3) ``S`` if the oops occurred on an SMP kernel running on hardware that
+ 3)  ``S`` if the oops occurred on an SMP kernel running on hardware that
  hasn't been certified as safe to run multiprocessor.
  Currently this occurs only on various Athlons that are not
  SMP capable.
 
-  4) ``R`` if a module was force unloaded by ``rmmod -f``, ``' '`` if all
+ 4)  ``R`` if a module was force unloaded by ``rmmod -f``, ``' '`` if all
  modules were unloaded normally.
 
-  5) ``M`` if any processor has reported a Machine Check Exception,
+ 5)  ``M`` if any processor has reported a Machine Check Exception,
  ``' '`` if no Machine Check Exceptions have occurred.
 
-  6) ``B`` if a page-release function has found a bad page reference or
+ 6)  ``B`` if a page-release function has found a bad page reference or
  some unexpected page flags.
 
-  7) ``U`` if a user or user application specifically requested that the
+ 7)  ``U`` if a user or user application specifically requested that the
  Tainted flag be set, ``' '`` otherwise.
 
-  8) ``D`` if the kernel has died recently, i.e. there was an OOPS or BUG.
+ 8)  ``D`` if the kernel has died recently, i.e. there was an OOPS or BUG.
 
-  9) ``A`` if the ACPI table has been overridden.
+ 9)  ``A`` if the ACPI table has been overridden.
 
  10) ``W`` if a warning has previously been issued by the kernel.
  (Though some warnings may set more specific taint flags.)
-- 
2.15.1

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] Documentation/process/howto: Remove outdated info about bugzilla mailing lists

[Jonathan Neuschäfer]

The mailing list archives[1,2] show no activity since September 2011.

[1]: https://lists.linuxfoundation.org/pipermail/bugme-new/
[2]: https://lists.linuxfoundation.org/pipermail/bugme-janitors/

Signed-off-by: Jonathan Neuschäfer 
---
 Documentation/process/howto.rst | 8 
 1 file changed, 8 deletions(-)

diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst
index c6875b1db56f..fbd236e037c2 100644
--- a/Documentation/process/howto.rst
+++ b/Documentation/process/howto.rst
@@ -381,14 +381,6 @@ bugs is one of the best ways to get merits among other 
developers, because
 not many people like wasting time fixing other people's bugs.
 
 To work in the already reported bug reports, go to https://bugzilla.kernel.org.
-If you want to be advised of the future bug reports, you can subscribe to the
-bugme-new mailing list (only new bug reports are mailed here) or to the
-bugme-janitor mailing list (every change in the bugzilla is mailed here)
-
-   https://lists.linux-foundation.org/mailman/listinfo/bugme-new
-
-   https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors
-
 
 
 Mailing lists
-- 
2.15.1

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 0/6] Restructure kernel-doc.rst

[Randy Dunlap]

On 02/13/2018 01:18 PM, Matthew Wilcox wrote:
> On Tue, Feb 13, 2018 at 01:03:18PM -0800, Randy Dunlap wrote:
>> As long as the examples don't dictate style...
>> E.g., Matthew likes to use:
>>
>> +  * @gfp: Memory allocation flags.
>>
>> a. Capitalize the first word after @param:
>> b. end with a period (even though it's not a sentence)
>>
>> I disagree with both of those.
> 
> OK, so which do you think looks better:
> 
> https://www.kernel.org/doc/html/latest/core-api/idr.html#c.idr_get_cursor
> https://www.kernel.org/doc/html/latest/core-api/idr.html#c.idr_alloc_u32

I can't tell. I don't mind your way but I don't think it should be something
that is codified/enforced.

> (yes, I have failed to be consistent.  I shall apply appropriate amounts
> of self-flagellation and fix them shortly.)

TMI :)


-- 
~Randy
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 0/5] Restructure kernel-doc.rst

[Jonathan Corbet]

On Tue, 13 Feb 2018 13:15:32 -0800
Matthew Wilcox  wrote:

> Jon asked me to redo the Context: patch on top of his current docs tree.
> Unfortunately, I was on a plane at the time, so I started fixing some
> other small things, and before I knew it, I'd completely restructured
> the entire doc-guide/kernel-doc.rst file.
> 
> v2: Dropped Style Guide section.
> Added header to split-man.pl as requested by Jon.
> Credited/blamed Mauro for the perl script, and included a GPL-2 SPDX
> tag.

Applied, thanks.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 0/6] Restructure kernel-doc.rst

[Matthew Wilcox]

On Tue, Feb 13, 2018 at 01:03:18PM -0800, Randy Dunlap wrote:
> On 02/13/2018 12:59 PM, Jonathan Corbet wrote:
> > I think this makes sense to do, but I really would like to see an intro
> > comment on the split-man.pl script itself.  Somebody wandering through
> > the scripts directory should be able to look at the top of the file and
> > know what the script does without having to reverse-engineer delightful
> > stuff like:
> > 
> >> if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) {

Fixed in v2 ;-)

> >>   Fix whitespace in example
> >>   Restructure kernel-doc.rst
> >>   Add a Style Guide section
> > 
> > This last one worries me a bit because we're starting to impinge a bit on
> > the coding style document.  If we're going to give guidance on things
> > like parameter names, I think that coding-style.rst is the right place
> > for it.

Dropped for v2.

> As long as the examples don't dictate style...
> E.g., Matthew likes to use:
> 
> +  * @gfp: Memory allocation flags.
> 
> a. Capitalize the first word after @param:
> b. end with a period (even though it's not a sentence)
> 
> I disagree with both of those.

OK, so which do you think looks better:

https://www.kernel.org/doc/html/latest/core-api/idr.html#c.idr_get_cursor
https://www.kernel.org/doc/html/latest/core-api/idr.html#c.idr_alloc_u32

(yes, I have failed to be consistent.  I shall apply appropriate amounts
of self-flagellation and fix them shortly.)
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 4/5] Fix whitespace in example

[Matthew Wilcox]

From: Matthew Wilcox 

Line up the second line in the way that the example purports to be
showing.

Signed-off-by: Matthew Wilcox 
---
 Documentation/doc-guide/kernel-doc.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/doc-guide/kernel-doc.rst 
b/Documentation/doc-guide/kernel-doc.rst
index 466347067f79..85efec8ecc44 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -154,7 +154,7 @@ The ``@argument:`` descriptions may span multiple lines.
the previous line, e. g.::
 
   * @argument: some long description
-  *   that continues on next lines
+  *that continues on next lines
 
or::
 
-- 
2.15.1

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 3/5] Add scripts/split-man.pl

[Matthew Wilcox]

From: Matthew Wilcox 

Instead of asking the user to copy and paste a small perl script from
the documentation, just distribute the perl script in the scripts
directory.

Signed-off-by: Matthew Wilcox 
---
 Documentation/doc-guide/kernel-doc.rst | 30 ++
 scripts/split-man.pl   | 28 
 2 files changed, 30 insertions(+), 28 deletions(-)
 create mode 100755 scripts/split-man.pl

diff --git a/Documentation/doc-guide/kernel-doc.rst 
b/Documentation/doc-guide/kernel-doc.rst
index 64ca081d075e..466347067f79 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -528,32 +528,6 @@ How to use kernel-doc to generate man pages
 ---
 
 If you just want to use kernel-doc to generate man pages you can do this
-from the Kernel git tree::
+from the kernel git tree::
 
-  $ scripts/kernel-doc -man $(git grep -l '/\*\*' |grep -v Documentation/) | 
./split-man.pl /tmp/man
-
-Using the small ``split-man.pl`` script below::
-
-
-  #!/usr/bin/perl
-
-  if ($#ARGV < 0) {
- die "where do I put the results?\n";
-  }
-
-  mkdir $ARGV[0],0777;
-  $state = 0;
-  while () {
-  if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) {
-   if ($state == 1) { close OUT }
-   $state = 1;
-   $fn = "$ARGV[0]/$1.9";
-   print STDERR "Creating $fn\n";
-   open OUT, ">$fn" or die "can't open $fn: $!\n";
-   print OUT $_;
-  } elsif ($state != 0) {
-   print OUT $_;
-  }
-  }
-
-  close OUT;
+  $ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) 
| scripts/split-man.pl /tmp/man
diff --git a/scripts/split-man.pl b/scripts/split-man.pl
new file mode 100755
index ..bfe16cbe42df
--- /dev/null
+++ b/scripts/split-man.pl
@@ -0,0 +1,28 @@
+#!/usr/bin/perl
+# SPDX-License-Identifier: GPL-2.0
+#
+# Author: Mauro Carvalho Chehab 
+#
+# Produce manpages from kernel-doc.
+# See Documentation/doc-guide/kernel-doc.rst for instructions
+
+if ($#ARGV < 0) {
+   die "where do I put the results?\n";
+}
+
+mkdir $ARGV[0],0777;
+$state = 0;
+while () {
+if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) {
+   if ($state == 1) { close OUT }
+   $state = 1;
+   $fn = "$ARGV[0]/$1.9";
+   print STDERR "Creating $fn\n";
+   open OUT, ">$fn" or die "can't open $fn: $!\n";
+   print OUT $_;
+} elsif ($state != 0) {
+   print OUT $_;
+}
+}
+
+close OUT;
-- 
2.15.1

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 5/5] Restructure kernel-doc.rst

[Matthew Wilcox]

From: Matthew Wilcox 

I found the layout confusing with multiple introductions to what
kernel-doc is and how to use it.

I made the following changes:
 - Moved the 'Including kernel-doc comments' section to the end of
   the document -- we should explain what it *is* before we explain
   how to integrate it.
 - Moved the 'Recommendations' subsection to the top.  We want people
   to know what to document before telling them how to do it.
 - Rewrite the 'Writing kernel-doc comments' section, integrating
   the 'Recommendations' subsection and a paragraph from 'How to format
   kernel-doc comments'.
 - Remove the paragraph about the kernel-doc script; we're supposed to
   be teaching people how to use punctuation to write pretty documentation,
   not documenting the build tooling.
 - Split the 'Parameters and member arguments' section into 'Function
   parameters' and 'Members'.  Structure members are not commonly
   referred to as arguments.
 - Integrate the 'private:' and 'public:' tag descriptions into the
   'Members' section.
 - Move the 'In-line member documentation comments' subsection up to be
   with the 'Members' section.

Signed-off-by: Matthew Wilcox 
---
 Documentation/doc-guide/kernel-doc.rst | 476 +++--
 1 file changed, 217 insertions(+), 259 deletions(-)

diff --git a/Documentation/doc-guide/kernel-doc.rst 
b/Documentation/doc-guide/kernel-doc.rst
index 85efec8ecc44..2fb7f2bfc245 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -1,202 +1,48 @@
-Including kernel-doc comments
-=
-
-The Linux kernel source files may contain structured documentation comments, or
-kernel-doc comments to describe the functions and types and design of the
-code. The documentation comments may be included to any of the reStructuredText
-documents using a dedicated kernel-doc Sphinx directive extension.
-
-The kernel-doc directive is of the format::
-
-  .. kernel-doc:: source
- :option:
-
-The *source* is the path to a source file, relative to the kernel source
-tree. The following directive options are supported:
-
-export: *[source-pattern ...]*
-  Include documentation for all functions in *source* that have been exported
-  using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any
-  of the files specified by *source-pattern*.
-
-  The *source-pattern* is useful when the kernel-doc comments have been placed
-  in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next 
to
-  the function definitions.
-
-  Examples::
-
-.. kernel-doc:: lib/bitmap.c
-   :export:
-
-.. kernel-doc:: include/net/mac80211.h
-   :export: net/mac80211/*.c
-
-internal: *[source-pattern ...]*
-  Include documentation for all functions and types in *source* that have
-  **not** been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either
-  in *source* or in any of the files specified by *source-pattern*.
-
-  Example::
-
-.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
-   :internal:
-
-doc: *title*
-  Include documentation for the ``DOC:`` paragraph identified by *title* in
-  *source*. Spaces are allowed in *title*; do not quote the *title*. The 
*title*
-  is only used as an identifier for the paragraph, and is not included in the
-  output. Please make sure to have an appropriate heading in the enclosing
-  reStructuredText document.
-
-  Example::
-
-.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
-   :doc: High Definition Audio over HDMI and Display Port
-
-functions: *function* *[...]*
-  Include documentation for each *function* in *source*.
-
-  Example::
-
-.. kernel-doc:: lib/bitmap.c
-   :functions: bitmap_parselist bitmap_parselist_user
-
-Without options, the kernel-doc directive includes all documentation comments
-from the source file.
-
-The kernel-doc extension is included in the kernel source tree, at
-``Documentation/sphinx/kerneldoc.py``. Internally, it uses the
-``scripts/kernel-doc`` script to extract the documentation comments from the
-source.
-
-.. _kernel_doc:
-
 Writing kernel-doc comments
 ===
 
-In order to provide embedded, "C" friendly, easy to maintain, but consistent 
and
-extractable overview, function and type documentation, the Linux kernel has
-adopted a consistent style for documentation comments. The format for this
-documentation is called the kernel-doc format, described below. This style
-embeds the documentation within the source files, using a few simple 
conventions
-for adding documentation paragraphs and documenting functions and their
-parameters, structures and unions and their members, enumerations, and 
typedefs.
-
-.. note:: The kernel-doc format is deceptively similar to gtk-doc or Doxygen,
-   yet distinctively different, for historical reasons. The kernel source
-   contains tens of thousands of kernel-doc 

[PATCH v2 2/5] Minor fixes to kernel-doc.rst

[Matthew Wilcox]

From: Matthew Wilcox 

The author clearly meant to use the word 'which' here.  Also replace
some tabs with spaces which fixes the syntax highlighting in my editor.

Signed-off-by: Matthew Wilcox 
---
 Documentation/doc-guide/kernel-doc.rst | 16 
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/doc-guide/kernel-doc.rst 
b/Documentation/doc-guide/kernel-doc.rst
index 315b0ecc7a11..64ca081d075e 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -277,7 +277,7 @@ named ``Return``.
 
   #) If the descriptive text you provide has lines that begin with
  some phrase followed by a colon, each of those phrases will be taken
- as a new section heading, with probably won't produce the desired
+ as a new section heading, which probably won't produce the desired
  effect.
 
 Structure, union, and enumeration documentation
@@ -324,22 +324,22 @@ It is possible to document nested structs unions, like::
   struct {
 int arg1;
 int arg2;
- }
+}
   struct {
 void *arg3;
 int arg4;
- }
-   }
-   union {
+  }
+}
+union {
   struct {
 int arg1;
 int arg2;
- } st1;
+  } st1;
   struct {
 void *arg1;
 int arg2;
- } st2;
-   } bar;
+  } st2;
+} bar;
   };
 
 .. note::
-- 
2.15.1

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 0/5] Restructure kernel-doc.rst

[Matthew Wilcox]

From: Matthew Wilcox 

Jon asked me to redo the Context: patch on top of his current docs tree.
Unfortunately, I was on a plane at the time, so I started fixing some
other small things, and before I knew it, I'd completely restructured
the entire doc-guide/kernel-doc.rst file.

v2: Dropped Style Guide section.
Added header to split-man.pl as requested by Jon.
Credited/blamed Mauro for the perl script, and included a GPL-2 SPDX
tag.

Matthew Wilcox (5):
  Add documentation for Context section
  Minor fixes to kernel-doc.rst
  Add scripts/split-man.pl
  Fix whitespace in example
  Restructure kernel-doc.rst

 Documentation/doc-guide/kernel-doc.rst | 539 +++--
 scripts/split-man.pl   |  28 ++
 2 files changed, 276 insertions(+), 291 deletions(-)
 create mode 100755 scripts/split-man.pl

-- 
2.15.1

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 1/5] Add documentation for Context section

[Matthew Wilcox]

From: Matthew Wilcox 

This section is mentioned in scripts/kernel-doc, so we should mention it
in doc-guide/kernel-doc.rst.  There are close to 500 comments using the
Context section already, and almost 300 using a Locking section which
fulfills much the same purpose (and should probably be converted for
consistency).

Signed-off-by: Matthew Wilcox 
---
 Documentation/doc-guide/kernel-doc.rst | 25 +
 1 file changed, 25 insertions(+)

diff --git a/Documentation/doc-guide/kernel-doc.rst 
b/Documentation/doc-guide/kernel-doc.rst
index 722d4525f7cf..315b0ecc7a11 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -117,6 +117,7 @@ Example kernel-doc function comment::
*
* Longer description of foobar.
*
+   * Context: Interrupt / locking context of foobar.
* Return: Description of return value of foobar.
*/
   int foobar(int argument1, char *argument2)
@@ -216,6 +217,9 @@ The general format of a function and function-like macro 
kernel-doc comment is::
*
* The longer description may have multiple paragraphs.
*
+   * Context: Describes whether the function can sleep, what locks it takes,
+   *  releases, or expects to be held. It can extend over multiple
+   *  lines.
* Return: Describe the return value of foobar.
*
* The return value description can also have multiple paragraphs, and should
@@ -226,6 +230,24 @@ The brief description following the function name may span 
multiple lines, and
 ends with an argument description, a blank comment line, or the end of the
 comment block.
 
+Function context
+
+
+The context in which a function can be called should be described in a
+section named ``Context``. This should include whether the function
+sleeps or can be called from interrupt context, as well as what locks
+it takes, releases and expects to be held by its caller.
+
+Examples::
+
+  * Context: Any context.
+  * Context: Any context. Takes and releases the RCU lock.
+  * Context: Any context. Expects  to be held by caller.
+  * Context: Process context. May sleep if @gfp flags permit.
+  * Context: Process context. Takes and releases .
+  * Context: Softirq or process context. Takes and releases , BH-safe.
+  * Context: Interrupt context.
+
 Return values
 ~
 
@@ -347,6 +369,9 @@ Typedefs with function prototypes can also be documented::
* @arg2: description of arg2
*
* Description of the type.
+   *
+   * Context: Locking context.
+   * Return: Meaning of the return value.
*/
typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);
 
-- 
2.15.1

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation/process: Co-developed-by instead of Co-Developed-by

[Jonathan Corbet]

On Sat, 10 Feb 2018 13:55:15 +0100
Dominik Brodowski  wrote:

> Up to now, all commit messages have used the "d" in lower case.

Applied, thanks.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] tracing: Fix incorrect file name

[Jonathan Corbet]

On Sun, 04 Feb 2018 18:14:24 +0800
Xiongwei Song  wrote:

> There is no file named 'enabled' in the directory tracing/events. It should
> be the file 'enable'.

Makes sense, applied to the docs tree, thanks.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 0/6] Restructure kernel-doc.rst

[Randy Dunlap]

On 02/13/2018 12:59 PM, Jonathan Corbet wrote:
> On Thu,  8 Feb 2018 06:45:07 -0800
> Matthew Wilcox  wrote:
> 
>> Jon asked me to redo the Context: patch on top of his current docs tree.
>> Unfortunately, I was on a plane at the time, so I started fixing some
>> other small things, and before I knew it, I'd completely restructured
>> the entire doc-guide/kernel-doc.rst file.
>>
>> Feel free to not take it all, particularly the last 'Style Guide' patch.
> 
> OK, this all makes sense.  Mostly.  Here's my quibbles.
>>
>> Matthew Wilcox (6):
>>   Add documentation for Context section
>>   Minor fixes to kernel-doc.rst
>>   Add scripts/split-man.pl
> 
> I think this makes sense to do, but I really would like to see an intro
> comment on the split-man.pl script itself.  Somebody wandering through
> the scripts directory should be able to look at the top of the file and
> know what the script does without having to reverse-engineer delightful
> stuff like:
> 
>> if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) {
> 
>>   Fix whitespace in example
>>   Restructure kernel-doc.rst
>>   Add a Style Guide section
> 
> This last one worries me a bit because we're starting to impinge a bit on
> the coding style document.  If we're going to give guidance on things
> like parameter names, I think that coding-style.rst is the right place
> for it.

As long as the examples don't dictate style...
E.g., Matthew likes to use:

+  * @gfp: Memory allocation flags.

a. Capitalize the first word after @param:
b. end with a period (even though it's not a sentence)

I disagree with both of those.

> I'll go ahead and apply the first five.  I'll try to get around to
> putting a comment on scripts/split-man.pl, but I sure wouldn't mind if
> somebody beat me to it...


-- 
~Randy
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 0/6] Restructure kernel-doc.rst

[Jonathan Corbet]

On Thu,  8 Feb 2018 06:45:07 -0800
Matthew Wilcox  wrote:

> Jon asked me to redo the Context: patch on top of his current docs tree.
> Unfortunately, I was on a plane at the time, so I started fixing some
> other small things, and before I knew it, I'd completely restructured
> the entire doc-guide/kernel-doc.rst file.
> 
> Feel free to not take it all, particularly the last 'Style Guide' patch.

OK, this all makes sense.  Mostly.  Here's my quibbles.
> 
> Matthew Wilcox (6):
>   Add documentation for Context section
>   Minor fixes to kernel-doc.rst
>   Add scripts/split-man.pl

I think this makes sense to do, but I really would like to see an intro
comment on the split-man.pl script itself.  Somebody wandering through
the scripts directory should be able to look at the top of the file and
know what the script does without having to reverse-engineer delightful
stuff like:

> if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) {

>   Fix whitespace in example
>   Restructure kernel-doc.rst
>   Add a Style Guide section

This last one worries me a bit because we're starting to impinge a bit on
the coding style document.  If we're going to give guidance on things
like parameter names, I think that coding-style.rst is the right place
for it.

I'll go ahead and apply the first five.  I'll try to get around to
putting a comment on scripts/split-man.pl, but I sure wouldn't mind if
somebody beat me to it...

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation: kdump: describe jumping to dump-capture kernel

[Bhupesh SHARMA]

On Tue, Feb 13, 2018 at 8:52 PM, Gioh Kim  wrote:
> Jumping between the system kernel and the dump-capture kernel
> has been supported for long time but there is no description
> how to use it. This patch adds the description how to use kexec tool
> to jump to the dump-capture kernel and jump back to the system kernel.
>
> Signed-off-by: Gioh Kim 
> ---
>  Documentation/kdump/kdump.txt | 38 ++
>  1 file changed, 38 insertions(+)
>
> diff --git a/Documentation/kdump/kdump.txt b/Documentation/kdump/kdump.txt
> index 51814450a7f8..35b71fef5d88 100644
> --- a/Documentation/kdump/kdump.txt
> +++ b/Documentation/kdump/kdump.txt
> @@ -460,6 +460,44 @@ and the system will boot into the dump-capture kernel.
>  For testing purposes, you can trigger a crash by using "ALT-SysRq-c",
>  "echo c > /proc/sysrq-trigger" or write a module to force the panic.
>
> +Jump between the System kernel and the Dump-capture kernel
> +===
> +
> +Without system crash, the system can jump to the dump-capture kernel.
> +
> +1) Enable "jump between system kernel and dump-capture kernel" support under
> +   "Processor type and features"
> +
> +   CONFIG_KEXEC_JUMP=y
> +
> +2) Load the dump-capture kernel with --load-preserve-context and mem-max
> +   options as following.
> +
> +   kexec -l  \
> +   --initrd= --args-linux \
> +   --append="root= " \
> +   --load-preserve-context \
> +   --mem-max=
> +
> +3) Jump to the loaded kernel
> +
> +   kexec -e
> +
> +Now the system is running with the dump-capture kernel. You can jump back
> +to the system kernel.
> +
> +1) Find kexec_jump_back_entry address in kernel booting parameters in
> +   /proc/cmdline. That is the address for kexec to jump to. For example:
> +   kexec_jump_back_entry=0x000810d2
> +
> +2) Following command sets the jump-back address for kexec.
> +
> +   kexec --load-jump-back-helper --entry=0x810d2
> +
> +3) Jump to the system kernel
> +
> +   kexec -e
> +

This is essentially the 'kexec -l' use case, i.e we are loading
another kernel and not the kexec -p (or the conventional kdump) use
case and description.

I remember not being able to use the kexec -p (kdump feature) with the
jump/preserve primary kernel attributes case previously, but that was
some time back and haven't tried the same recently. So I am not sure
if the kexec -p case works well with the jump feature currently, but I
can try to setup an environment at my end.

So I don't think that the kdump kernel documentation is the right
place for this addition (as in this kernel document we essentially
capture the 'kexec -p' or kdump case and not the 'kexec -l'). Rather
we should add it the kexec man page (inside kexec-tools). See
 for
the man page.

And I agree that this is a useful piece of documentation as I have
burnt my hands while experimenting with the jump feature previously
and I think it would be great to have this included somewhere in the
kexec man page for ready reference.

Regards,
Bhupesh


>  Write Out the Dump File
>  ===
>
> --
> 2.11.0
>
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 1/2] Documentation/locking/lockdep: update info about states

[Juri Lelli]

Commit d92a8cfcb37e ("locking/lockdep: Rework FS_RECLAIM annotation") removed
reclaim_fs lockdep STATE.

Reflect the change in documentation.

While we are at it, also clarify formula to calculate number of state
bits.

Signed-off-by: Juri Lelli 
Cc: Peter Zijlstra 
Cc: Ingo Molnar 
Cc: Jonathan Corbet 
Cc: linux-ker...@vger.kernel.org
Cc: linux-doc@vger.kernel.org
---
 Documentation/locking/lockdep-design.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/locking/lockdep-design.txt 
b/Documentation/locking/lockdep-design.txt
index 9de1c158d44c..e341c2f34e68 100644
--- a/Documentation/locking/lockdep-design.txt
+++ b/Documentation/locking/lockdep-design.txt
@@ -27,7 +27,8 @@ lock-class.
 State
 -
 
-The validator tracks lock-class usage history into 4n + 1 separate state bits:
+The validator tracks lock-class usage history into 4 * nSTATEs + 1 separate
+state bits:
 
 - 'ever held in STATE context'
 - 'ever held as readlock in STATE context'
@@ -37,7 +38,6 @@ The validator tracks lock-class usage history into 4n + 1 
separate state bits:
 Where STATE can be either one of (kernel/locking/lockdep_states.h)
  - hardirq
  - softirq
- - reclaim_fs
 
 - 'ever used'   [ == !unused]
 
-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[RFC PATCH 2/2] Documentation/locking/lockdep: Add section about available annotations

[Juri Lelli]

Add section about annotations that can be used to perform additional runtime
checking of locking correctness: assert that certain locks are held and
prevent accidental unlocking.

Signed-off-by: Juri Lelli 
Cc: Peter Zijlstra 
Cc: Ingo Molnar 
Cc: Jonathan Corbet 
Cc: linux-ker...@vger.kernel.org
Cc: linux-doc@vger.kernel.org
---
 Documentation/locking/lockdep-design.txt | 47 
 1 file changed, 47 insertions(+)

diff --git a/Documentation/locking/lockdep-design.txt 
b/Documentation/locking/lockdep-design.txt
index e341c2f34e68..74347a24efc7 100644
--- a/Documentation/locking/lockdep-design.txt
+++ b/Documentation/locking/lockdep-design.txt
@@ -169,6 +169,53 @@ Note: When changing code to use the _nested() primitives, 
be careful and
 check really thoroughly that the hierarchy is correctly mapped; otherwise
 you can get false positives or false negatives.
 
+Annotations
+---
+
+Two constructs can be used to annotate and check where and if certain locks
+must be held: lockdep_assert_held*() and lockdep_*pin_lock().
+
+As the name suggests, lockdep_assert_held* family of macros assert that a
+particular lock is held at a certain time (and generate a WARN otherwise).
+This annotation is largely used all over the kernel, e.g. kernel/sched/
+core.c
+
+  void update_rq_clock(struct rq *rq)
+  {
+   s64 delta;
+
+   lockdep_assert_held(>lock);
+   [...]
+  }
+
+where holding rq->lock is required to safely update a rq's clock.
+
+The other family of macros is lockdep_*pin_lock, which is admittedly only
+used for rq->lock ATM. Despite their limited adoption these annotations
+generate a WARN if the lock of interest is "accidentally" unlocked. This turns
+out to be especially helpful to debug code with callbacks, where an upper
+layer assumes a lock remains taken, but a lower layer thinks it can maybe drop
+and reacquire the lock ("unwittingly" introducing races). lockdep_pin_lock
+returns a 'struct pin_cookie' that is then used by lockdep_unpin_lock to check
+that nobody tampered with the lock, e.g. kernel/sched/sched.h
+
+  static inline void rq_pin_lock(struct rq *rq, struct rq_flags *rf)
+  {
+   rf->cookie = lockdep_pin_lock(>lock);
+   [...]
+  }
+
+  static inline void rq_unpin_lock(struct rq *rq, struct rq_flags *rf)
+  {
+   [...]
+   lockdep_unpin_lock(>lock, rf->cookie);
+  }
+
+While comments about locking requirements might provide useful information,
+the runtime checks performed by annotations are invaluable when debugging
+locking problems and they carry the same level of details when inspecting
+code.  Always prefer annotations when in doubt!
+
 Proof of 100% correctness:
 --
 
-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 0/2] Update lockdep doc and add section about annotations

[Juri Lelli]

Hi,

a couple of patches to lockdep docs.

First one is a small fix for that fact that Peter made documentation
stale (as usual :P).

Second one is an RFC. I thought that adding some info about lockdep
asserts might help spread adoption even wider (mostly regarding
lockdep_pin_lock stuff, which is pretty new and maybe got unnoticed
outside of the scheduler?).

Best,

- Juri 

Juri Lelli (2):
  Documentation/locking/lockdep: update info about states
  Documentation/locking/lockdep: Add section about available annotations

 Documentation/locking/lockdep-design.txt | 51 ++--
 1 file changed, 49 insertions(+), 2 deletions(-)

-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

RE: [PATCH v2] MIPS: Add nonxstack=on|off kernel parameter

[Aleksandar Markovic]

> 
> 
> From: James Hogan [jho...@kernel.org]
> Sent: Thursday, February 8, 2018 12:55 PM
> 
> Hi,
> 
> On Thu, Dec 07, 2017 at 11:33:47AM +, Miodrag Dinic wrote:
> > > On Wed, Dec 06, 2017 at 05:50:52PM +, Maciej W. Rozycki wrote:
> > > >  What problem are you trying to solve anyway?  Is it not something that
> > > > can be handled with the `execstack' utility?
> > >
> > > The commit message states that for Android "non-exec stack is required".
> > > Is Android checking that then Aleksandar? If so, how?
> >
> > Android is using SELinux configured to disallow NX mappings by handling
> > the following sepolicy rules :
> > * Executable stack (execstack)
> > * Executable heap (execheap)
> > * File-based executable code which has been modified (execmod)
> > * All other executable memory (execmem)
> 
> ...
> 
> > The effect of not having some workaround like this in the kernel, would
> > be to run Android only in SELinux permissive mode.
> 
> So you want to override the lack of RIXI so that SELinux sees an
> RX->RW->RX transition as execmod instead of execmem (since without RIXI
> its effectively RX->RWX->RX which is execmem)?
> 

That is correct.

> 
> Looking at file_map_prot_check(), it does the execmem check on this
> condition:
> 
> if (default_noexec &&
> (prot & PROT_EXEC) && (!file || IS_PRIVATE(file_inode(file)) ||
>(!shared && (prot & PROT_WRITE {
> /*
>  * We are making executable an anonymous mapping or a
>  * private file mapping that will also be writable.
>  * This has an additional check.
>  */
> 
> default_noexec is set if VM_DATA_DEFAULT_FLAGS doesn't have the exec
> flag set, and that flag depends on current->personality &
> READ_IMPLIES_EXEC, which depends on elf_read_implies_exec(), i.e.
> mips_elf_read_implies_exec(), and that should already return 1 if RIXI
> is unavailable.
> 
> I.e.
> 
> mips_elf_read_implies_exec() == 1
> 
> elf_read_implies_exec() == 1
> 
> READ_IMPLIES_EXEC will be set in current->personality
> 
> VM_DATA_DEFAULT_FLAGS will have VM_EXEC set
> 
> default_noexec will be set to 0 in selinux_init()
> 
> none of the execmem, execheap, execstack, execmod permission
> checks should take place.
> 
> So whats the problem exactly? Perhaps I misinterpreted something.

Thanks, James, for the analysis of this scenario! Hope the additional
info below will be useful for clarifying this matter.

---

Let me rephrase the scenario (for configurations where cpu_has_rixi
equals to 0) that you described: (line numbers may be approximate)


1. mips_elf_read_implies_exec() will return 1
(arch/mips/kernel/elf.c:336)

2. elf_read_implies_exec() will return 1
(arch/mips/include/asm/elf.h:513)

3. READ_IMPLIES_EXEC will be set in current->personality
(fs/binfmt_elf_fdpic.c:357)

4. VM_DATA_DEFAULT_FLAGS will have VM_EXEC set
(while execiting selinux_init() in security/selinux/hooks.c:6644)

5. default_noexec will be set to 0 in selinux_init()
(security/selinux/hooks.c:6644)

6. none of the execmem, execstack permission checks should take place.

---

However, in reality, these steps are not executed in this order, but in the 
following one:


4a. VM_DATA_DEFAULT_FLAGS will *NOT* have VM_EXEC set
(while execiting selinux_init() in security/selinux/hooks.c:6644)

5a. default_noexec will be set to *1* in selinux_init()
(security/selinux/hooks.c:6644)

1. mips_elf_read_implies_exec() will return 1
(arch/mips/kernel/elf.c:336)

2. elf_read_implies_exec() will return 1
(arch/mips/include/asm/elf.h:513)

3. READ_IMPLIES_EXEC will be set in current->personality
(fs/binfmt_elf_fdpic.c:357)

6a. both the execmem, execstack permission checks *do* take place.

--

The proposed change does affect the kernel in the sense that it indeed
hides the executable vulnerability of the system without RIXI support.
But we have made it unambiguous in the comments what are the
consequences of using this option.

--


Regards,

Aleksandar

> 
> Cheers
> James
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] Documentation: kdump: describe jumping to dump-capture kernel

[Gioh Kim]

Jumping between the system kernel and the dump-capture kernel
has been supported for long time but there is no description
how to use it. This patch adds the description how to use kexec tool
to jump to the dump-capture kernel and jump back to the system kernel.

Signed-off-by: Gioh Kim 
---
 Documentation/kdump/kdump.txt | 38 ++
 1 file changed, 38 insertions(+)

diff --git a/Documentation/kdump/kdump.txt b/Documentation/kdump/kdump.txt
index 51814450a7f8..35b71fef5d88 100644
--- a/Documentation/kdump/kdump.txt
+++ b/Documentation/kdump/kdump.txt
@@ -460,6 +460,44 @@ and the system will boot into the dump-capture kernel.
 For testing purposes, you can trigger a crash by using "ALT-SysRq-c",
 "echo c > /proc/sysrq-trigger" or write a module to force the panic.
 
+Jump between the System kernel and the Dump-capture kernel
+===
+
+Without system crash, the system can jump to the dump-capture kernel.
+
+1) Enable "jump between system kernel and dump-capture kernel" support under
+   "Processor type and features"
+
+   CONFIG_KEXEC_JUMP=y
+
+2) Load the dump-capture kernel with --load-preserve-context and mem-max
+   options as following.
+
+   kexec -l  \
+   --initrd= --args-linux \
+   --append="root= " \
+   --load-preserve-context \
+   --mem-max=
+
+3) Jump to the loaded kernel
+
+   kexec -e
+
+Now the system is running with the dump-capture kernel. You can jump back
+to the system kernel.
+
+1) Find kexec_jump_back_entry address in kernel booting parameters in
+   /proc/cmdline. That is the address for kexec to jump to. For example:
+   kexec_jump_back_entry=0x000810d2
+
+2) Following command sets the jump-back address for kexec.
+
+   kexec --load-jump-back-helper --entry=0x810d2
+
+3) Jump to the system kernel
+
+   kexec -e
+
 Write Out the Dump File
 ===
 
-- 
2.11.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] scripts: kernel_doc: fixup reporting of function identifiers

[Mike Rapoport]

When function description includes brackets after the function name as
suggested by Documentation/doc-guide/kernel-doc, the kernel-doc script
omits the function name from "Scanning doc for" report.
Extending match for identifier name with optional brackets fixes this
issue.

Signed-off-by: Mike Rapoport 
---
 scripts/kernel-doc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index fee8952037b1..a6a9a8ef116c 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1873,7 +1873,7 @@ sub process_file($) {
}
elsif (/$doc_decl/o) {
$identifier = $1;
-   if (/\s*([\w\s]+?)\s*-/) {
+   if (/\s*([\w\s]+?)(\(\))?\s*-/) {
$identifier = $1;
}
 
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 5/8] docs: kernel-doc: Move STATE_BODY processing to a separate function

[Jani Nikula]

On Fri, 09 Feb 2018, Linus Torvalds  wrote:
> On Fri, Feb 9, 2018 at 1:32 AM, Jani Nikula  
> wrote:
>>> + # miguel-style comment kludge, look for blank lines after
>>> + # @parameter line to signify start of description
>>
>> The "miguel-style" always intrigued me, but its origin predates git
>> history. Does anyone know?
>
> It came with the original script in 2.3.52-pre1, somewhere around March 2000.
>
> (Historical footnote: there was no actual 2.3.52 ever released - it
> was supposed turn into 2.4, but there was a long line of 2.3.99-pre
> kernels before that then finally happened early 2001).
>
> But no, back then we didn't track things well enough to have an actual
> reason. And even with git, we probably wouldn't have had a reason
> since it came in the initial patch.
>
> You'd have to go search emails if you really care. That "around March
> 2000" would at least give you a starting point for searches.

Thanks for the background digging! I had a cursory look at the list
archives, nothing much jumped at me but I found that the script was
originally called gdoc. A little googling revealed that other forks of
the script predating inclusion to the kernel also included the comment.

I'll bet whoever added that didn't think someone would wonder about it
two decades later.

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html