[PATCH] mm:Add watermark slope for high mark
When tuning the watermark_scale_factor to reduce stalls and compactions
the high mark is also changed, it changed a bit too much. So this
patch introduces a slope that can reduce this overhead a bit, or
increase it if needed.
Signed-off-by: Peter Enderborg
---
Documentation/sysctl/vm.txt | 15 +++
include/linux/mm.h | 1 +
include/linux/mmzone.h | 2 ++
kernel/sysctl.c | 9 +
mm/page_alloc.c | 6 +-
5 files changed, 32 insertions(+), 1 deletion(-)
diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt
index eda628c..aecff6c 100644
--- a/Documentation/sysctl/vm.txt
+++ b/Documentation/sysctl/vm.txt
@@ -62,6 +62,7 @@ Currently, these files are in /proc/sys/vm:
- user_reserve_kbytes
- vfs_cache_pressure
- watermark_scale_factor
+- watermark_high_factor_slope
- zone_reclaim_mode
==
@@ -857,6 +858,20 @@ that the number of free pages kswapd maintains for latency
reasons is
too small for the allocation bursts occurring in the system. This knob
can then be used to tune kswapd aggressiveness accordingly.
+=
+
+watermark_high_factor_slope:
+
+This factor is high mark for watermark_scale_factor.
+The unit is in percent.
+Max value is 1000 and min value is 100. (High watermark is the same as
+low water mark) Low watermark is min_wmark_pages + watermark_scale_factor.
+and high watermark is
+min_wmark_pages+(watermark_scale_factor * watermark_high_factor_slope).
+
+The default value is 200.
+
+
==
zone_reclaim_mode:
diff --git a/include/linux/mm.h b/include/linux/mm.h
index 7661156..c89536b 100644
--- a/include/linux/mm.h
+++ b/include/linux/mm.h
@@ -2094,6 +2094,7 @@ extern void zone_pcp_reset(struct zone *zone);
/* page_alloc.c */
extern int min_free_kbytes;
extern int watermark_scale_factor;
+extern int watermark_high_factor_slope;
/* nommu.c */
extern atomic_long_t mmap_pages_allocated;
diff --git a/include/linux/mmzone.h b/include/linux/mmzone.h
index 67f2e3c..91bf842 100644
--- a/include/linux/mmzone.h
+++ b/include/linux/mmzone.h
@@ -886,6 +886,8 @@ int min_free_kbytes_sysctl_handler(struct ctl_table *, int,
void __user *, size_t *, loff_t *);
int watermark_scale_factor_sysctl_handler(struct ctl_table *, int,
void __user *, size_t *, loff_t *);
+//int watermark_high_factor_tilt_sysctl_handler(struct ctl_table *, int,
+// void __user *, size_t *, loff_t *);
extern int sysctl_lowmem_reserve_ratio[MAX_NR_ZONES-1];
int lowmem_reserve_ratio_sysctl_handler(struct ctl_table *, int,
void __user *, size_t *, loff_t *);
diff --git a/kernel/sysctl.c b/kernel/sysctl.c
index 2fb4e27..83c48c9 100644
--- a/kernel/sysctl.c
+++ b/kernel/sysctl.c
@@ -1444,6 +1444,15 @@ static struct ctl_table vm_table[] = {
.extra2 = &one_thousand,
},
{
+ .procname = "watermark_high_factor_slope",
+ .data = &watermark_high_factor_slope,
+ .maxlen = sizeof(watermark_high_factor_slope),
+ .mode = 0644,
+ .proc_handler = watermark_scale_factor_sysctl_handler,
+ .extra1 = &one_hundred,
+ .extra2 = &one_thousand,
+ },
+ {
.procname = "percpu_pagelist_fraction",
.data = &percpu_pagelist_fraction,
.maxlen = sizeof(percpu_pagelist_fraction),
diff --git a/mm/page_alloc.c b/mm/page_alloc.c
index 48b5b01..3dc50ff 100644
--- a/mm/page_alloc.c
+++ b/mm/page_alloc.c
@@ -263,6 +263,7 @@ compound_page_dtor * const compound_page_dtors[] = {
int min_free_kbytes = 1024;
int user_min_free_kbytes = -1;
int watermark_scale_factor = 10;
+int watermark_high_factor_slope = 200;
static unsigned long __meminitdata nr_kernel_pages;
static unsigned long __meminitdata nr_all_pages;
@@ -6989,6 +6990,7 @@ static void __setup_per_zone_wmarks(void)
for_each_zone(zone) {
u64 tmp;
+ u64 tmp_high;
spin_lock_irqsave(&zone->lock, flags);
tmp = (u64)pages_min * zone->managed_pages;
@@ -7026,7 +7028,9 @@ static void __setup_per_zone_wmarks(void)
watermark_scale_factor, 1));
zone->watermark[WMARK_LOW] = min_wmark_pages(zone) + tmp;
- zone->watermark[WMARK_HIGH] = min_wmark_pages(zone) + tmp * 2;
+ tmp_high = mult_frac(tmp, watermark_high_factor_slope, 100);
+ zone->watermark[WMARK_HIGH] = min_wmark_pages(zone) + tmp_high;
+
spin_unlock_irqrestore(&zone->lock, flags);
}
--
2
Re: [PATCH] mm:Add watermark slope for high mark
On Fri 24-11-17 11:07:07, Peter Enderborg wrote:
> When tuning the watermark_scale_factor to reduce stalls and compactions
> the high mark is also changed, it changed a bit too much. So this
> patch introduces a slope that can reduce this overhead a bit, or
> increase it if needed.
This doesn't explain what is the problem, why it is a problem and why we
need yet another tuning to address it. Users shouldn't really care about
internal stuff like watermark tuning for each watermark independently.
This looks like a gross hack. Please start over with the problem
description and then we can move on to an approapriate fix. Piling up
tuning knobs to workaround problems is simply not acceptable.
> Signed-off-by: Peter Enderborg
> ---
> Documentation/sysctl/vm.txt | 15 +++
> include/linux/mm.h | 1 +
> include/linux/mmzone.h | 2 ++
> kernel/sysctl.c | 9 +
> mm/page_alloc.c | 6 +-
> 5 files changed, 32 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt
> index eda628c..aecff6c 100644
> --- a/Documentation/sysctl/vm.txt
> +++ b/Documentation/sysctl/vm.txt
> @@ -62,6 +62,7 @@ Currently, these files are in /proc/sys/vm:
> - user_reserve_kbytes
> - vfs_cache_pressure
> - watermark_scale_factor
> +- watermark_high_factor_slope
> - zone_reclaim_mode
>
> ==
> @@ -857,6 +858,20 @@ that the number of free pages kswapd maintains for
> latency reasons is
> too small for the allocation bursts occurring in the system. This knob
> can then be used to tune kswapd aggressiveness accordingly.
>
> +=
> +
> +watermark_high_factor_slope:
> +
> +This factor is high mark for watermark_scale_factor.
> +The unit is in percent.
> +Max value is 1000 and min value is 100. (High watermark is the same as
> +low water mark) Low watermark is min_wmark_pages + watermark_scale_factor.
> +and high watermark is
> +min_wmark_pages+(watermark_scale_factor * watermark_high_factor_slope).
> +
> +The default value is 200.
> +
> +
> ==
>
> zone_reclaim_mode:
> diff --git a/include/linux/mm.h b/include/linux/mm.h
> index 7661156..c89536b 100644
> --- a/include/linux/mm.h
> +++ b/include/linux/mm.h
> @@ -2094,6 +2094,7 @@ extern void zone_pcp_reset(struct zone *zone);
> /* page_alloc.c */
> extern int min_free_kbytes;
> extern int watermark_scale_factor;
> +extern int watermark_high_factor_slope;
>
> /* nommu.c */
> extern atomic_long_t mmap_pages_allocated;
> diff --git a/include/linux/mmzone.h b/include/linux/mmzone.h
> index 67f2e3c..91bf842 100644
> --- a/include/linux/mmzone.h
> +++ b/include/linux/mmzone.h
> @@ -886,6 +886,8 @@ int min_free_kbytes_sysctl_handler(struct ctl_table *,
> int,
> void __user *, size_t *, loff_t *);
> int watermark_scale_factor_sysctl_handler(struct ctl_table *, int,
> void __user *, size_t *, loff_t *);
> +//int watermark_high_factor_tilt_sysctl_handler(struct ctl_table *, int,
> +// void __user *, size_t *, loff_t *);
> extern int sysctl_lowmem_reserve_ratio[MAX_NR_ZONES-1];
> int lowmem_reserve_ratio_sysctl_handler(struct ctl_table *, int,
> void __user *, size_t *, loff_t *);
> diff --git a/kernel/sysctl.c b/kernel/sysctl.c
> index 2fb4e27..83c48c9 100644
> --- a/kernel/sysctl.c
> +++ b/kernel/sysctl.c
> @@ -1444,6 +1444,15 @@ static struct ctl_table vm_table[] = {
> .extra2 = &one_thousand,
> },
> {
> + .procname = "watermark_high_factor_slope",
> + .data = &watermark_high_factor_slope,
> + .maxlen = sizeof(watermark_high_factor_slope),
> + .mode = 0644,
> + .proc_handler = watermark_scale_factor_sysctl_handler,
> + .extra1 = &one_hundred,
> + .extra2 = &one_thousand,
> + },
> + {
> .procname = "percpu_pagelist_fraction",
> .data = &percpu_pagelist_fraction,
> .maxlen = sizeof(percpu_pagelist_fraction),
> diff --git a/mm/page_alloc.c b/mm/page_alloc.c
> index 48b5b01..3dc50ff 100644
> --- a/mm/page_alloc.c
> +++ b/mm/page_alloc.c
> @@ -263,6 +263,7 @@ compound_page_dtor * const compound_page_dtors[] = {
> int min_free_kbytes = 1024;
> int user_min_free_kbytes = -1;
> int watermark_scale_factor = 10;
> +int watermark_high_factor_slope = 200;
>
> static unsigned long __meminitdata nr_kernel_pages;
> static unsigned long __meminitdata nr_all_pages;
> @@ -6989,6 +6990,7 @@ static void __setup_per_zone_wmarks(void)
>
> for_each_zone(zone) {
> u64 tmp;
> + u64 tmp_high;
>
Re: [PATCH] mm:Add watermark slope for high mark
On 11/24/2017 11:14 AM, Michal Hocko wrote:
> On Fri 24-11-17 11:07:07, Peter Enderborg wrote:
>> When tuning the watermark_scale_factor to reduce stalls and compactions
>> the high mark is also changed, it changed a bit too much. So this
>> patch introduces a slope that can reduce this overhead a bit, or
>> increase it if needed.
>
> This doesn't explain what is the problem, why it is a problem and why we
> need yet another tuning to address it. Users shouldn't really care about
> internal stuff like watermark tuning for each watermark independently.
> This looks like a gross hack. Please start over with the problem
> description and then we can move on to an approapriate fix. Piling up
> tuning knobs to workaround problems is simply not acceptable.
Agreed. Also if you send a patch adding userspace API or a tuning knob,
please CC linux-api mailing list (did that for this reply).
>> Signed-off-by: Peter Enderborg
>> ---
>> Documentation/sysctl/vm.txt | 15 +++
>> include/linux/mm.h | 1 +
>> include/linux/mmzone.h | 2 ++
>> kernel/sysctl.c | 9 +
>> mm/page_alloc.c | 6 +-
>> 5 files changed, 32 insertions(+), 1 deletion(-)
>>
>> diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt
>> index eda628c..aecff6c 100644
>> --- a/Documentation/sysctl/vm.txt
>> +++ b/Documentation/sysctl/vm.txt
>> @@ -62,6 +62,7 @@ Currently, these files are in /proc/sys/vm:
>> - user_reserve_kbytes
>> - vfs_cache_pressure
>> - watermark_scale_factor
>> +- watermark_high_factor_slope
>> - zone_reclaim_mode
>>
>> ==
>> @@ -857,6 +858,20 @@ that the number of free pages kswapd maintains for
>> latency reasons is
>> too small for the allocation bursts occurring in the system. This knob
>> can then be used to tune kswapd aggressiveness accordingly.
>>
>> +=
>> +
>> +watermark_high_factor_slope:
>> +
>> +This factor is high mark for watermark_scale_factor.
>> +The unit is in percent.
>> +Max value is 1000 and min value is 100. (High watermark is the same as
>> +low water mark) Low watermark is min_wmark_pages + watermark_scale_factor.
>> +and high watermark is
>> +min_wmark_pages+(watermark_scale_factor * watermark_high_factor_slope).
>> +
>> +The default value is 200.
>> +
>> +
>> ==
>>
>> zone_reclaim_mode:
>> diff --git a/include/linux/mm.h b/include/linux/mm.h
>> index 7661156..c89536b 100644
>> --- a/include/linux/mm.h
>> +++ b/include/linux/mm.h
>> @@ -2094,6 +2094,7 @@ extern void zone_pcp_reset(struct zone *zone);
>> /* page_alloc.c */
>> extern int min_free_kbytes;
>> extern int watermark_scale_factor;
>> +extern int watermark_high_factor_slope;
>>
>> /* nommu.c */
>> extern atomic_long_t mmap_pages_allocated;
>> diff --git a/include/linux/mmzone.h b/include/linux/mmzone.h
>> index 67f2e3c..91bf842 100644
>> --- a/include/linux/mmzone.h
>> +++ b/include/linux/mmzone.h
>> @@ -886,6 +886,8 @@ int min_free_kbytes_sysctl_handler(struct ctl_table *,
>> int,
>> void __user *, size_t *, loff_t *);
>> int watermark_scale_factor_sysctl_handler(struct ctl_table *, int,
>> void __user *, size_t *, loff_t *);
>> +//int watermark_high_factor_tilt_sysctl_handler(struct ctl_table *, int,
>> +// void __user *, size_t *, loff_t *);
>> extern int sysctl_lowmem_reserve_ratio[MAX_NR_ZONES-1];
>> int lowmem_reserve_ratio_sysctl_handler(struct ctl_table *, int,
>> void __user *, size_t *, loff_t *);
>> diff --git a/kernel/sysctl.c b/kernel/sysctl.c
>> index 2fb4e27..83c48c9 100644
>> --- a/kernel/sysctl.c
>> +++ b/kernel/sysctl.c
>> @@ -1444,6 +1444,15 @@ static struct ctl_table vm_table[] = {
>> .extra2 = &one_thousand,
>> },
>> {
>> +.procname = "watermark_high_factor_slope",
>> +.data = &watermark_high_factor_slope,
>> +.maxlen = sizeof(watermark_high_factor_slope),
>> +.mode = 0644,
>> +.proc_handler = watermark_scale_factor_sysctl_handler,
>> +.extra1 = &one_hundred,
>> +.extra2 = &one_thousand,
>> +},
>> +{
>> .procname = "percpu_pagelist_fraction",
>> .data = &percpu_pagelist_fraction,
>> .maxlen = sizeof(percpu_pagelist_fraction),
>> diff --git a/mm/page_alloc.c b/mm/page_alloc.c
>> index 48b5b01..3dc50ff 100644
>> --- a/mm/page_alloc.c
>> +++ b/mm/page_alloc.c
>> @@ -263,6 +263,7 @@ compound_page_dtor * const compound_page_dtors[] = {
>> int min_free_kbytes = 1024;
>> int user_min_free_kbytes = -1;
>> int watermark_scale_factor = 10;
>> +int watermark_high_factor_slope =
Re: [PATCH] mm:Add watermark slope for high mark
On 11/24/2017 11:15 AM, Vlastimil Babka wrote: > Agreed. Also if you send a patch adding userspace API or a tuning knob, > please CC linux-api mailing list (did that for this reply). > The cc-list is generated by get_maintainer.pl script. -- 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:Add watermark slope for high mark
On 11/24/2017 11:14 AM, Michal Hocko wrote: > On Fri 24-11-17 11:07:07, Peter Enderborg wrote: >> When tuning the watermark_scale_factor to reduce stalls and compactions >> the high mark is also changed, it changed a bit too much. So this >> patch introduces a slope that can reduce this overhead a bit, or >> increase it if needed. > This doesn't explain what is the problem, why it is a problem and why we > need yet another tuning to address it. Users shouldn't really care about > internal stuff like watermark tuning for each watermark independently. > This looks like a gross hack. Please start over with the problem > description and then we can move on to an approapriate fix. Piling up > tuning knobs to workaround problems is simply not acceptable. > In the original patch - https://lkml.org/lkml/2016/2/18/498 - had a discussion about small systems with 8GB RAM. In the handheld world, that's a lot of RAM. However, the magic number 2 used in the present algorithm is out of the blue. Compaction problems are the same for both small and big. So small devices also need to increase watermark to get compaction to work and reduce direct reclaims. Changing the low watermark makes direct reclaim rate drop a lot. But it will cause kswap to work more, and that has a negative impact. Lowering the gap will smooth out the kswap workload to suite embedded devices a lot better. This can be addressed by reducing the high watermark using the slope patch herein. Im sort of understand your opinion on user knobs, but hard-coded magic numbers are even worse. -- 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:Add watermark slope for high mark
On Fri 24-11-17 14:12:56, peter enderborg wrote: > On 11/24/2017 11:14 AM, Michal Hocko wrote: > > On Fri 24-11-17 11:07:07, Peter Enderborg wrote: > >> When tuning the watermark_scale_factor to reduce stalls and compactions > >> the high mark is also changed, it changed a bit too much. So this > >> patch introduces a slope that can reduce this overhead a bit, or > >> increase it if needed. > > This doesn't explain what is the problem, why it is a problem and why we > > need yet another tuning to address it. Users shouldn't really care about > > internal stuff like watermark tuning for each watermark independently. > > This looks like a gross hack. Please start over with the problem > > description and then we can move on to an approapriate fix. Piling up > > tuning knobs to workaround problems is simply not acceptable. > > > > In the original patch - https://lkml.org/lkml/2016/2/18/498 - had a > > discussion about small systems with 8GB RAM. In the handheld world, that's > a lot of RAM. However, the magic number 2 used in the present algorithm > is out of the blue. Compaction problems are the same for both small and > big. So small devices also need to increase watermark to > get compaction to work and reduce direct reclaims. Changing the low watermark > makes direct reclaim rate drop a lot. But it will cause kswap to work more, > and that has a negative impact. Lowering the gap will smooth out the kswap > workload to suite embedded devices a lot better. This can be addressed by > reducing the high watermark using the slope patch herein. Im sort of > understand > your opinion on user knobs, but hard-coded magic numbers are even worse. How can a poor user know how to tune it when _we_ cannot do a qualified guess and we do know all the implementation details. Really, describe problems you are seeing with the current code and we can talk about a proper fix or a heuristic when the fix is hard/unfeasible. -- Michal Hocko SUSE Labs -- 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 v5 11/11] intel_sgx: driver documentation
On Fri, Nov 17, 2017 at 01:43:10PM -0800, Darren Hart wrote: > This series will need to be updated per the comments received so far, as > well as with commit messages and a complete Cc list *per patch* giving > all required parties an opportunity to review. > > With respect to the obvious security nature of this series, who from the > kernel security folks are going to be reviewing this? > secur...@kernel.org? I think it would make sense to CC this to linux-security module. > Cc updated for this thread, and specifically the question regarding > location below: > > > Signed-off-by: Jarkko Sakkinen > > --- > > Documentation/index.rst | 1 + > > Documentation/x86/intel_sgx.rst | 131 > > > > 2 files changed, 132 insertions(+) > > create mode 100644 Documentation/x86/intel_sgx.rst > > > > ... > > > diff --git a/Documentation/x86/intel_sgx.rst > > b/Documentation/x86/intel_sgx.rst > > new file mode 100644 > > index ..34bcf6a2a495 > > --- /dev/null > > +++ b/Documentation/x86/intel_sgx.rst > > @@ -0,0 +1,131 @@ > > +=== > > +Intel(R) SGX driver > > +=== > > + > > +Introduction > > + > > + > > +Intel(R) SGX is a set of CPU instructions that can be used by applications > > to > > +set aside private regions of code and data. The code outside the enclave is > > +disallowed to access the memory inside the enclave by the CPU access > > control. > > +In a way you can think that SGX provides inverted sandbox. It protects the > > +application from a malicious host. > > + > > +There is a new hardware unit in the processor called Memory Encryption > > Engine > > +(MEE) starting from the Skylake microarchitecture. BIOS can define one or > > many > > +MEE regions that can hold enclave data by configuring them with PRMRR > > registers. > > + > > +The MEE automatically encrypts the data leaving the processor package to > > the MEE > > +regions. The data is encrypted using a random key whose life-time is > > exactly one > > +power cycle. > > + > > +You can tell if your CPU supports SGX by looking into ``/proc/cpuinfo``: > > + > > + ``cat /proc/cpuinfo | grep sgx`` > > Is SGX considered architectural or not? A quick search of the SDM > includes it in Volume 3: > > Volume 3: Includes the full system programming guide, parts 1, 2, 3, and > 4. Describes the operating-system support environment of Intel® 64 and > IA-32 architectures, including: memory management, protection, task > management, interrupt and exception handling, multi-processor support, > thermal and power management features, debugging, performance > monitoring, system management mode, virtual machine extensions (VMX) > instructions, Intel® Virtualization Technology (Intel® VT), and Intel® > Software Guard Extensions (Intel® SGX). > > https://software.intel.com/en-us/articles/intel-sdm > > Depending on the answer, this impacts whether this belongs in > drivers/platform/x86 or arch/x86/platform per our recent agreement with > Thomas. > > Thomas, Mingo, HPA, do you wish to see this organized/located > differently than it is here in v5? The code is made easily relocatable. I just wanted to keep it as an encapsulated driver up until I hear the maintainer feedback. I'll submit v6 with code otherwise fixed according to the feedback that I've heard up until that point and relocate it in v7 based on your feedback. > > +Launch control > > +== > > + > > +For launching an enclave, two structures must be provided for ENCLS(EINIT): > > + > > +1. **SIGSTRUCT:** a signed measurement of the enclave binary. > > +2. **EINITTOKEN:** the measurement, the public key of the signer and > > various > > + enclave attributes. This structure contains a MAC of its contents using > > + hardware derived symmetric key called *launch key*. > > + > > +The hardware platform contains a root key pair for signing the SIGTRUCT > > +for a *launch enclave* that is able to acquire the *launch key* for > > +creating EINITTOKEN's for other enclaves. For the launch enclave > > +EINITTOKEN is not needed because it is signed with the private root key. > > + > > +There are two feature control bits associate with launch control > > Nit: missing colon at the end of the line above ^ Yes. Thanks for spotting that out :-) /Jarkko -- 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: [RFC] doc: add maintainer book
On Tue, Nov 21, 2017 at 2:39 PM, Tobin C. Harding wrote: > There is currently very little documentation in the kernel on maintainer > level tasks. In particular there are no documents on creating pull > requests to submit to Linus. > > Quoting Greg Kroah-Hartman on LKML: > > Anyway, this actually came up at the kernel summit / maintainer > meeting a few weeks ago, in that "how do I make a > good pull request to Linus" is something we need to document. > > Here's what I do, and it seems to work well, so maybe we should turn > it into the start of the documentation for how to do it. > > (quote references: kernel summit, Europe 2017) > > Create a new kernel documentation book 'how to be a maintainer' > (suggested by Jonathan Corbet). Add chapters on 'configuring git' and > 'creating a pull request'. > > Most of the content was written by Linus Torvalds and Greg Kroah-Hartman > in discussion on LKML. This is stated at the start of one of the > chapters and the original email thread is referenced in > 'pull-requests.rst'. > > Signed-off-by: Tobin C. Harding > --- > > Linus and Greg are CC'd because they are quoted heavily in the document. > > Greg, > > This is my second attempt at this but still it reads as if I am saying things > that actually you said. I feel this is in the spirit of your original message > but I would still like you to okay it please. Any suggestions (from anyone) > on a > better way to word, or structure, the document most welcome. > > thanks. > > > Dan, > > Is this in line with your ideas for the maintainer documentation you have > planned? I am a total noob at writing docs, please don't be shy to say if > there > is a better way. This is a good start that we can build on, I'll let others comment on the mechanical doc building details I want to focus on the content. The only change I would make at this point is to the index... [..] > diff --git a/Documentation/maintainer/index.rst > b/Documentation/maintainer/index.rst > new file mode 100644 > index ..23dd28ec8762 > --- /dev/null > +++ b/Documentation/maintainer/index.rst > @@ -0,0 +1,10 @@ > += > +How to Be a Kernel Maintainer > += Let's call this the "Kernel Maintainer Handbook". Unlike SubmittingPatches and CodingStyle, this won't be a list of rules and mandates but instead some common principles and practical advice that maintainers will find useful, especially new and casual maintainers. > + > +.. toctree:: > + :maxdepth: 2 > + > + configure-git > + pull-requests > + > diff --git a/Documentation/maintainer/pull-requests.rst > b/Documentation/maintainer/pull-requests.rst > new file mode 100644 > index ..0ca9f9bfd679 > --- /dev/null > +++ b/Documentation/maintainer/pull-requests.rst > @@ -0,0 +1,178 @@ > +.. _pullrequests: > + > +Creating Pull Requests > +== It strikes me that the very next chapter we need to precede this one is how to age commits in -next and the art of avoiding rebasing. -- 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: [RFC] doc: add maintainer book
On Fri, Nov 24, 2017 at 11:02:49AM -0800, Dan Williams wrote: > On Tue, Nov 21, 2017 at 2:39 PM, Tobin C. Harding wrote: > > There is currently very little documentation in the kernel on maintainer > > level tasks. In particular there are no documents on creating pull > > requests to submit to Linus. > > > > Quoting Greg Kroah-Hartman on LKML: > > > > Anyway, this actually came up at the kernel summit / maintainer > > meeting a few weeks ago, in that "how do I make a > > good pull request to Linus" is something we need to document. > > > > Here's what I do, and it seems to work well, so maybe we should turn > > it into the start of the documentation for how to do it. > > > > (quote references: kernel summit, Europe 2017) > > > > Create a new kernel documentation book 'how to be a maintainer' > > (suggested by Jonathan Corbet). Add chapters on 'configuring git' and > > 'creating a pull request'. > > > > Most of the content was written by Linus Torvalds and Greg Kroah-Hartman > > in discussion on LKML. This is stated at the start of one of the > > chapters and the original email thread is referenced in > > 'pull-requests.rst'. > > > > Signed-off-by: Tobin C. Harding > > --- > > > > Linus and Greg are CC'd because they are quoted heavily in the document. > > > > Greg, > > > > This is my second attempt at this but still it reads as if I am saying > > things > > that actually you said. I feel this is in the spirit of your original > > message > > but I would still like you to okay it please. Any suggestions (from anyone) > > on a > > better way to word, or structure, the document most welcome. > > > > thanks. > > > > > > Dan, > > > > Is this in line with your ideas for the maintainer documentation you have > > planned? I am a total noob at writing docs, please don't be shy to say if > > there > > is a better way. > > This is a good start that we can build on, I'll let others comment on > the mechanical doc building details I want to focus on the content. > The only change I would make at this point is to the index... > > [..] > > diff --git a/Documentation/maintainer/index.rst > > b/Documentation/maintainer/index.rst > > new file mode 100644 > > index ..23dd28ec8762 > > --- /dev/null > > +++ b/Documentation/maintainer/index.rst > > @@ -0,0 +1,10 @@ > > += > > +How to Be a Kernel Maintainer > > += > > Let's call this the "Kernel Maintainer Handbook". Unlike > SubmittingPatches and CodingStyle, this won't be a list of rules and > mandates but instead some common principles and practical advice that > maintainers will find useful, especially new and casual maintainers. Sounds good to me, I'll re-spin it with that change. > > + > > +.. toctree:: > > + :maxdepth: 2 > > + > > + configure-git > > + pull-requests > > + > > diff --git a/Documentation/maintainer/pull-requests.rst > > b/Documentation/maintainer/pull-requests.rst > > new file mode 100644 > > index ..0ca9f9bfd679 > > --- /dev/null > > +++ b/Documentation/maintainer/pull-requests.rst > > @@ -0,0 +1,178 @@ > > +.. _pullrequests: > > + > > +Creating Pull Requests > > +== > > It strikes me that the very next chapter we need to precede this one > is how to age commits in -next and the art of avoiding rebasing. I'd like to read this! thanks, Tobin. -- 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] doc: add maintainer book
There is currently very little documentation in the kernel on maintainer
level tasks. In particular there are no documents on creating pull
requests to submit to Linus.
Quoting Greg Kroah-Hartman on LKML:
Anyway, this actually came up at the kernel summit / maintainer
meeting a few weeks ago, in that "how do I make a
good pull request to Linus" is something we need to document.
Here's what I do, and it seems to work well, so maybe we should turn
it into the start of the documentation for how to do it.
(quote references: kernel summit, Europe 2017)
Create a new kernel documentation book 'how to be a maintainer'
(suggested by Jonathan Corbet). Add chapters on 'configuring git' and
'creating a pull request'.
Most of the content was written by Linus Torvalds and Greg Kroah-Hartman
in discussion on LKML. This is stated at the start of one of the
chapters and the original email thread is referenced in
'pull-requests.rst'.
Signed-off-by: Tobin C. Harding
---
v2:
- Change title of book, suggested by Dan Williams.
thanks,
Tobin.
Documentation/index.rst| 1 +
Documentation/maintainer/conf.py | 10 ++
Documentation/maintainer/configure-git.rst | 34 ++
Documentation/maintainer/index.rst | 10 ++
Documentation/maintainer/pull-requests.rst | 178 +
5 files changed, 233 insertions(+)
create mode 100644 Documentation/maintainer/conf.py
create mode 100644 Documentation/maintainer/configure-git.rst
create mode 100644 Documentation/maintainer/index.rst
create mode 100644 Documentation/maintainer/pull-requests.rst
diff --git a/Documentation/index.rst b/Documentation/index.rst
index cb7f1ba5b3b1..a4fb34dddcf3 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -52,6 +52,7 @@ merged much easier.
dev-tools/index
doc-guide/index
kernel-hacking/index
+ maintainer/index
Kernel API documentation
diff --git a/Documentation/maintainer/conf.py b/Documentation/maintainer/conf.py
new file mode 100644
index ..81e9eb7a7884
--- /dev/null
+++ b/Documentation/maintainer/conf.py
@@ -0,0 +1,10 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = 'Linux Kernel Development Documentation'
+
+tags.add("subproject")
+
+latex_documents = [
+('index', 'maintainer.tex', 'Linux Kernel Development Documentation',
+ 'The kernel development community', 'manual'),
+]
diff --git a/Documentation/maintainer/configure-git.rst
b/Documentation/maintainer/configure-git.rst
new file mode 100644
index ..780d2c84
--- /dev/null
+++ b/Documentation/maintainer/configure-git.rst
@@ -0,0 +1,34 @@
+.. _configuregit:
+
+Configure Git
+=
+
+This chapter describes maintainer level git configuration.
+
+Tagged branches used in :ref:`Documentation/maintainer/pull-requests.rst
+` should be signed with the developers public GPG key. Signed
+tags can be created by passing the ``-u`` flag to ``git tag``. However,
+since you would *usually* use the same key for the same project, you can
+set it once with
+::
+
+ git config user.signingkey "keyname"
+
+Alternatively, edit your ``.git/config`` or ``~/.gitconfig`` file by hand:
+::
+
+ [user]
+ name = Jane Developer
+ email = j...@domain.org
+ signingkey = j...@domain.org
+
+You may need to tell ``git`` to use ``gpg2``
+::
+
+ [gpg]
+ program = /path/to/gpg2
+
+You may also like to tell ``gpg`` which ``tty`` to use (add to your shell rc
file)
+::
+
+ export GPG_TTY=$(tty)
diff --git a/Documentation/maintainer/index.rst
b/Documentation/maintainer/index.rst
new file mode 100644
index ..fa84ac9cae39
--- /dev/null
+++ b/Documentation/maintainer/index.rst
@@ -0,0 +1,10 @@
+==
+Kernel Maintainer Handbook
+==
+
+.. toctree::
+ :maxdepth: 2
+
+ configure-git
+ pull-requests
+
diff --git a/Documentation/maintainer/pull-requests.rst
b/Documentation/maintainer/pull-requests.rst
new file mode 100644
index ..0ca9f9bfd679
--- /dev/null
+++ b/Documentation/maintainer/pull-requests.rst
@@ -0,0 +1,178 @@
+.. _pullrequests:
+
+Creating Pull Requests
+==
+
+This chapter describes how maintainers can create and submit pull requests
+to other maintainers. This is useful for transferring changes from one
+maintainers tree to another maintainers tree.
+
+This document was written by Tobin C. Harding (who at that time, was not an
+experienced maintainer) primarily from comments made by Greg Kroah-Hartman
+and Linus Torvalds on LKML. Suggestions and fixes by Jonathan Corbet.
+Misrepresentation was unintentional but inevitable, please direct abuse to
+Tobin C. Harding .
+
+Original email thread::
+
+ http://lkml.kernel.org/r/20171114110500.ga21...@kroah.com
+
+
+Create Branch
+-
+
+To start with you will need to have all the changes you wish to
Re: [PATCH v2] doc: add maintainer book
On Sat, Nov 25, 2017 at 08:44:19AM +1100, Tobin C. Harding wrote: > There is currently very little documentation in the kernel on maintainer > level tasks. In particular there are no documents on creating pull > requests to submit to Linus. > > Quoting Greg Kroah-Hartman on LKML: > > Anyway, this actually came up at the kernel summit / maintainer > meeting a few weeks ago, in that "how do I make a > good pull request to Linus" is something we need to document. > > Here's what I do, and it seems to work well, so maybe we should turn > it into the start of the documentation for how to do it. > > (quote references: kernel summit, Europe 2017) > > Create a new kernel documentation book 'how to be a maintainer' > (suggested by Jonathan Corbet). Add chapters on 'configuring git' and > 'creating a pull request'. > > Most of the content was written by Linus Torvalds and Greg Kroah-Hartman > in discussion on LKML. This is stated at the start of one of the > chapters and the original email thread is referenced in > 'pull-requests.rst'. > > Signed-off-by: Tobin C. Harding > --- You dropped my reviewed-by :( -- 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
