Re: [PATCH 5/8] docs: kernel-doc: Move STATE_BODY processing to a separate function
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
[PATCH] scripts: kernel_doc: fixup reporting of function identifiers
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
[PATCH] Documentation: kdump: describe jumping to dump-capture kernel
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
RE: [PATCH v2] MIPS: Add nonxstack=on|off kernel parameter
> > > 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
[RFC PATCH 2/2] Documentation/locking/lockdep: Add section about available annotations
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*(&lock) and lockdep_*pin_lock(&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(&rq->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(&rq->lock); + [...] + } + + static inline void rq_unpin_lock(struct rq *rq, struct rq_flags *rf) + { + [...] + lockdep_unpin_lock(&rq->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
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
[PATCH 1/2] Documentation/locking/lockdep: update info about states
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
Re: [PATCH] Documentation: kdump: describe jumping to dump-capture kernel
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
Re: [PATCH 0/6] Restructure kernel-doc.rst
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 0/6] Restructure kernel-doc.rst
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] tracing: Fix incorrect file name
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] Documentation/process: Co-developed-by instead of Co-Developed-by
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
[PATCH v2 0/5] Restructure kernel-doc.rst
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
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
[PATCH v2 4/5] Fix whitespace in example
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
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
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 comments. Please stick to the style - described here.
[PATCH v2 2/5] Minor fixes to kernel-doc.rst
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
Re: [PATCH 0/6] Restructure kernel-doc.rst
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
Re: [PATCH v2 0/5] Restructure kernel-doc.rst
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
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
[PATCH] Documentation/process/howto: Remove outdated info about bugzilla mailing lists
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
[PATCH] admin-guide: Fix list formatting in tained-kernels.html
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
Re: [patch 1/2] mm, page_alloc: extend kernelcore and movablecore for percent
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
Re: [patch 1/2] mm, page_alloc: extend kernelcore and movablecore for percent
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
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 'movablecore='? -- Mike Kravetz -- To unsubsc
Re: [patch 1/2] mm, page_alloc: extend kernelcore and movablecore for percent
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
[patch -mm] mm, page_alloc: extend kernelcore and movablecore for percent fix
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 -mm] mm, page_alloc: extend kernelcore and movablecore for percent fix
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
Re: [patch 1/2] mm, page_alloc: extend kernelcore and movablecore for percent
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] Documentation: kdump: describe jumping to dump-capture kernel
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