[PATCH v3 4/4] document: change the document for immovable_mem
Add the document for the change of new parameter immovable_mem=nn[KMG]@ss[KMG]. Cc: linux-doc@vger.kernel.org Cc: Jonathan Corbet Signed-off-by: Chao Fan --- Documentation/admin-guide/kernel-parameters.txt | 9 + 1 file changed, 9 insertions(+) diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index b74e13312fdc..eea755af697f 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -2355,6 +2355,15 @@ allocations which rules out almost all kernel allocations. Use with caution! + immovable_mem=nn[KMG]@ss[KMG] + [KNL] Force usage of a specific region of memory. + Make memory hotplug work well with KASLR. + Region of memory in immovable node is from ss to ss+nn. + Multiple regions can be specified, comma delimited. + Notice: we support 4 regions at most now. + Example: + immovable_mem=1G,500M@2G,1G@4G + MTD_Partition= [MTD] Format: ,,, -- 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] refcount_t: documentation for memory ordering differences
On Wed, Nov 29, 2017 at 4:36 AM, Elena Reshetova > wrote: > > Some functions from refcount_t API provide different > > memory ordering guarantees that their atomic counterparts. > > This adds a document outlining these differences. > > > > Signed-off-by: Elena Reshetova > > Thanks for the improvements! > > I have some markup changes to add, but I'll send that as a separate patch. Thank you Kees! I guess I was too minimal on my markup use, so doc was pretty plain before. I have just joined your changes with mine and put both of our sign-off to the resulting patch. I think this way it is easier for reviewers since ultimately content is the same. I will now fix one more thing Randy noticed and then send it to linux-doc and Jon Corbet. Best Regards, Elena. > > Acked-by: Kees Cook > > -Kees > > > --- > > Documentation/core-api/index.rst | 1 + > > Documentation/core-api/refcount-vs-atomic.rst | 129 > ++ > > 2 files changed, 130 insertions(+) > > create mode 100644 Documentation/core-api/refcount-vs-atomic.rst > > > > diff --git a/Documentation/core-api/index.rst > > b/Documentation/core-api/index.rst > > index d5bbe03..d4d54b0 100644 > > --- a/Documentation/core-api/index.rst > > +++ b/Documentation/core-api/index.rst > > @@ -14,6 +14,7 @@ Core utilities > > kernel-api > > assoc_array > > atomic_ops > > + refcount-vs-atomic > > cpu_hotplug > > local_ops > > workqueue > > diff --git a/Documentation/core-api/refcount-vs-atomic.rst > b/Documentation/core-api/refcount-vs-atomic.rst > > new file mode 100644 > > index 000..5619d48 > > --- /dev/null > > +++ b/Documentation/core-api/refcount-vs-atomic.rst > > @@ -0,0 +1,129 @@ > > +=== > > +refcount_t API compared to atomic_t > > +=== > > + > > +The goal of refcount_t API is to provide a minimal API for implementing > > +an object's reference counters. While a generic architecture-independent > > +implementation from lib/refcount.c uses atomic operations underneath, > > +there are a number of differences between some of the refcount_*() and > > +atomic_*() functions with regards to the memory ordering guarantees. > > +This document outlines the differences and provides respective examples > > +in order to help maintainers validate their code against the change in > > +these memory ordering guarantees. > > + > > +memory-barriers.txt and atomic_t.txt provide more background to the > > +memory ordering in general and for atomic operations specifically. > > + > > +Relevant types of memory ordering > > += > > + > > +**Note**: the following section only covers some of the memory > > +ordering types that are relevant for the atomics and reference > > +counters and used through this document. For a much broader picture > > +please consult memory-barriers.txt document. > > + > > +In the absence of any memory ordering guarantees (i.e. fully unordered) > > +atomics & refcounters only provide atomicity and > > +program order (po) relation (on the same CPU). It guarantees that > > +each atomic_*() and refcount_*() operation is atomic and instructions > > +are executed in program order on a single CPU. > > +This is implemented using READ_ONCE()/WRITE_ONCE() and > > +compare-and-swap primitives. > > + > > +A strong (full) memory ordering guarantees that all prior loads and > > +stores (all po-earlier instructions) on the same CPU are completed > > +before any po-later instruction is executed on the same CPU. > > +It also guarantees that all po-earlier stores on the same CPU > > +and all propagated stores from other CPUs must propagate to all > > +other CPUs before any po-later instruction is executed on the original > > +CPU (A-cumulative property). This is implemented using smp_mb(). > > + > > +A RELEASE memory ordering guarantees that all prior loads and > > +stores (all po-earlier instructions) on the same CPU are completed > > +before the operation. It also guarantees that all po-earlier > > +stores on the same CPU and all propagated stores from other CPUs > > +must propagate to all other CPUs before the release operation > > +(A-cumulative property). This is implemented using smp_store_release(). > > + > > +A control dependency (on success) for refcounters guarantees that > > +if a reference for an object was successfully obtained (reference > > +counter increment or addition happened, function returned true), > > +then further stores are ordered against this operation. > > +Control dependency on stores are not implemented using any explicit > > +barriers, but rely on CPU not to speculate on stores. This is only > > +a single CPU relation and provides no guarantees for other CPUs. > > + > > + > > +Comparison of functions > > +=== > > + > > +case 1) - non-"Read/Modify/Write" (RMW) ops > > +--- > > + > > +Function changes: > > +
[PATCH] docs: refcount_t documentation
Some functions from refcount_t API provide different memory ordering guarantees that their atomic counterparts. This adds a document outlining these differences ( Documentation/core-api/refcount-vs-atomic.rst) as well as some other minor improvements. Signed-off-by: Elena Reshetova Signed-off-by: Kees Cook --- Documentation/core-api/index.rst | 1 + Documentation/core-api/refcount-vs-atomic.rst | 150 ++ Documentation/driver-api/basics.rst | 21 ++-- include/linux/refcount.h | 2 +- 4 files changed, 167 insertions(+), 7 deletions(-) create mode 100644 Documentation/core-api/refcount-vs-atomic.rst diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index d5bbe03..d4d54b0 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -14,6 +14,7 @@ Core utilities kernel-api assoc_array atomic_ops + refcount-vs-atomic cpu_hotplug local_ops workqueue diff --git a/Documentation/core-api/refcount-vs-atomic.rst b/Documentation/core-api/refcount-vs-atomic.rst new file mode 100644 index 000..83351c2 --- /dev/null +++ b/Documentation/core-api/refcount-vs-atomic.rst @@ -0,0 +1,150 @@ +=== +refcount_t API compared to atomic_t +=== + +.. contents:: :local: + +Introduction + + +The goal of refcount_t API is to provide a minimal API for implementing +an object's reference counters. While a generic architecture-independent +implementation from lib/refcount.c uses atomic operations underneath, +there are a number of differences between some of the ``refcount_*()`` and +``atomic_*()`` functions with regards to the memory ordering guarantees. +This document outlines the differences and provides respective examples +in order to help maintainers validate their code against the change in +these memory ordering guarantees. + +The terms used through this document try to follow the formal LKMM defined in +github.com/aparri/memory-model/blob/master/Documentation/explanation.txt + +memory-barriers.txt and atomic_t.txt provide more background to the +memory ordering in general and for atomic operations specifically. + +Relevant types of memory ordering += + +.. note:: The following section only covers some of the memory + ordering types that are relevant for the atomics and reference + counters and used through this document. For a much broader picture + please consult memory-barriers.txt document. + +In the absence of any memory ordering guarantees (i.e. fully unordered) +atomics & refcounters only provide atomicity and +program order (po) relation (on the same CPU). It guarantees that +each ``atomic_*()`` and ``refcount_*()`` operation is atomic and instructions +are executed in program order on a single CPU. +This is implemented using :c:func:`READ_ONCE`/:c:func:`WRITE_ONCE` and +compare-and-swap primitives. + +A strong (full) memory ordering guarantees that all prior loads and +stores (all po-earlier instructions) on the same CPU are completed +before any po-later instruction is executed on the same CPU. +It also guarantees that all po-earlier stores on the same CPU +and all propagated stores from other CPUs must propagate to all +other CPUs before any po-later instruction is executed on the original +CPU (A-cumulative property). This is implemented using :c:func:`smp_mb`. + +A RELEASE memory ordering guarantees that all prior loads and +stores (all po-earlier instructions) on the same CPU are completed +before the operation. It also guarantees that all po-earlier +stores on the same CPU and all propagated stores from other CPUs +must propagate to all other CPUs before the release operation +(A-cumulative property). This is implemented using +:c:func:`smp_store_release`. + +A control dependency (on success) for refcounters guarantees that +if a reference for an object was successfully obtained (reference +counter increment or addition happened, function returned true), +then further stores are ordered against this operation. +Control dependency on stores are not implemented using any explicit +barriers, but rely on CPU not to speculate on stores. This is only +a single CPU relation and provides no guarantees for other CPUs. + + +Comparison of functions +=== + +case 1) - non-"Read/Modify/Write" (RMW) ops +--- + +Function changes: + + * :c:func:`atomic_set` --> :c:func:`refcount_set` + * :c:func:`atomic_read` --> :c:func:`refcount_read` + +Memory ordering guarantee changes: + + * none (both fully unordered) + + +case 2) - increment-based ops that return no value +-- + +Function changes: + + * :c:func:`atomic_inc` --> :c:func:`refcount_inc` + * :c:func:`atomic_add` --> :c:func:`refcount_add` + +Memory ordering guarantee changes: + + * none (both fully un
Re: [PATCH v2] thinkad_acpi: Support the battery wear control
On Sun, Dec 03, 2017 at 11:56:40PM +0100, Ognjen Galic wrote: > Add support for the ACPI batteries on newer thinkpad models > (>Sandy Bridge) that support the setting of start and stop > thresholds. > > The actual interface to the driver is a extension for the > existing ACPI battery driver. This was done so that users > can write transparently to the interface of the ACPI battery > driver and dont have to use some private interface > (for ex. /sys/devices/platform/thinkpad_acpi/). > > Two new interfaces are created: > > /sys/class/power_supply/BAT{0,1}/charge_start_threshold > /sys/class/power_supply/BAT{0,1}/charge_stop_threshold Just tried this on my X1 Carbon (i7-3667U Ivy Lake): # cat /sys/class/power_supply/BAT0/charge_stop_threshold 100 # cat /sys/class/power_supply/BAT0/charge_start_threshold 100 That doesn't seem to make any sense. Is my battery somehow reporting false values here? Any way to cross check these values? -- Regards, Christoph -- 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 v3 4/4] document: change the document for immovable_mem
On 12/05/2017 12:52 AM, Chao Fan wrote: > Add the document for the change of new parameter > immovable_mem=nn[KMG]@ss[KMG]. > > Cc: linux-doc@vger.kernel.org > Cc: Jonathan Corbet > Signed-off-by: Chao Fan > --- > Documentation/admin-guide/kernel-parameters.txt | 9 + > 1 file changed, 9 insertions(+) > > diff --git a/Documentation/admin-guide/kernel-parameters.txt > b/Documentation/admin-guide/kernel-parameters.txt > index b74e13312fdc..eea755af697f 100644 > --- a/Documentation/admin-guide/kernel-parameters.txt > +++ b/Documentation/admin-guide/kernel-parameters.txt > @@ -2355,6 +2355,15 @@ > allocations which rules out almost all kernel > allocations. Use with caution! > > + immovable_mem=nn[KMG]@ss[KMG] immovable_mem=nn[KMG][@ss[KMG]] > + [KNL] Force usage of a specific region of memory. > + Make memory hotplug work well with KASLR. ^^only one space, please > + Region of memory in immovable node is from ss to > ss+nn.> + Multiple regions can be specified, comma > delimited. If ss is omitted, it defaults to 0. > + Notice: we support 4 regions at most now. > + Example: > + immovable_mem=1G,500M@2G,1G@4G > + > MTD_Partition= [MTD] > Format: ,,, > > -- ~Randy -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v2] thinkad_acpi: Support the battery wear control
On Tue, Dec 05, 2017 at 03:22:28PM +0100, Christoph Böhmwalder wrote: > On Sun, Dec 03, 2017 at 11:56:40PM +0100, Ognjen Galic wrote: > > Add support for the ACPI batteries on newer thinkpad models > > (>Sandy Bridge) that support the setting of start and stop > > thresholds. > > > > The actual interface to the driver is a extension for the > > existing ACPI battery driver. This was done so that users > > can write transparently to the interface of the ACPI battery > > driver and dont have to use some private interface > > (for ex. /sys/devices/platform/thinkpad_acpi/). > > > > Two new interfaces are created: > > > > /sys/class/power_supply/BAT{0,1}/charge_start_threshold > > /sys/class/power_supply/BAT{0,1}/charge_stop_threshold > > Just tried this on my X1 Carbon (i7-3667U Ivy Lake): > > # cat /sys/class/power_supply/BAT0/charge_stop_threshold > 100 > # cat /sys/class/power_supply/BAT0/charge_start_threshold > 100 > > That doesn't seem to make any sense. Is my battery somehow reporting > false values here? Any way to cross check these values? It means that both values are 0 (default). The first one is wrongly mapped to 100, but should probably be reported as 0. Also, the values are not mangled correctly when writing: 100 as a stop threshold should be written as 0, and and 100 as a start threshold should be illegal, giving you: start = [0, 99] stop = [1, 100] Which is what my patch series a few years ago implemented. I never got to integrate that with the acpi battery driver, though. -- debian developer - deb.li/jak | jak-linux.org - free software dev ubuntu core developer i speak de, en -- 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 v3 4/4] document: change the document for immovable_mem
On Tue, Dec 05, 2017 at 09:36:24AM -0800, Randy Dunlap wrote: >On 12/05/2017 12:52 AM, Chao Fan wrote: >> Add the document for the change of new parameter >> immovable_mem=nn[KMG]@ss[KMG]. >> >> Cc: linux-doc@vger.kernel.org >> Cc: Jonathan Corbet >> Signed-off-by: Chao Fan >> --- >> Documentation/admin-guide/kernel-parameters.txt | 9 + >> 1 file changed, 9 insertions(+) >> >> diff --git a/Documentation/admin-guide/kernel-parameters.txt >> b/Documentation/admin-guide/kernel-parameters.txt >> index b74e13312fdc..eea755af697f 100644 >> --- a/Documentation/admin-guide/kernel-parameters.txt >> +++ b/Documentation/admin-guide/kernel-parameters.txt >> @@ -2355,6 +2355,15 @@ >> allocations which rules out almost all kernel >> allocations. Use with caution! >> >> +immovable_mem=nn[KMG]@ss[KMG] > > immovable_mem=nn[KMG][@ss[KMG]] > >> +[KNL] Force usage of a specific region of memory. >> +Make memory hotplug work well with KASLR. > > ^^only one space, please > >> +Region of memory in immovable node is from ss to >> ss+nn.> + Multiple regions can be specified, comma >> delimited. > If ss is omitted, it defaults to 0. Sorry for the mistake. Will change it in next version. Thanks, Chao Fan >> +Notice: we support 4 regions at most now. >> +Example: >> +immovable_mem=1G,500M@2G,1G@4G >> + >> MTD_Partition= [MTD] >> Format: ,,, >> >> > > >-- >~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] doc: convert printk-formats.txt to rst
Documentation/printk-formats.txt is a candidate for conversion to ReStructuredText format. Some effort has already been made to do this conversion even thought the suffix is currently .txt Changes required to complete conversion - Add double backticks where needed. - Add entry to Documentation/index.rst - Use flat-table instead of ASCII table. - Fix minor grammatical errors. - Capitalize headers and correctly order heading adornments. - Use 'Passed by reference' uniformly. - Update pointer documentation around %px specifier. - Fix erroneous double backticks (to commas). - Simplify documentation for kobject. - Convert lib/vsnprintf.c function docs to use kernel-docs and include in Documentation/printk-formats.rst Signed-off-by: Tobin C. Harding --- The last two need special reviewing please. In particular the conversion of kernel-docs in vsnprintf.c attempt was made to reduce documentation duplication with comments in the source code being simplified in order to be suitable for inclusion in Documentation/printk-formats.rst I used -M when formatting the patch. If you don't like the diff with this flag just holla. thanks, Tobin. Documentation/index.rst| 10 + .../{printk-formats.txt => printk-formats.rst} | 295 - lib/vsprintf.c | 160 +-- 3 files changed, 235 insertions(+), 230 deletions(-) rename Documentation/{printk-formats.txt => printk-formats.rst} (61%) diff --git a/Documentation/index.rst b/Documentation/index.rst index cb7f1ba5b3b1..83ace60efbe7 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -87,6 +87,16 @@ implementation. sh/index +Miscellaneous documentation +--- + +These guides contain general information useful when writing kernel code. + +.. toctree:: + :maxdepth: 1 + + printk-formats + Korean translations --- diff --git a/Documentation/printk-formats.txt b/Documentation/printk-formats.rst similarity index 61% rename from Documentation/printk-formats.txt rename to Documentation/printk-formats.rst index aa0a776c817a..51449d213748 100644 --- a/Documentation/printk-formats.txt +++ b/Documentation/printk-formats.rst @@ -1,6 +1,6 @@ -= -How to get printk format specifiers right -= += +How to Get ``printk`` Format Specifiers Right += :Author: Randy Dunlap :Author: Andrew Murray @@ -8,56 +8,91 @@ How to get printk format specifiers right Integer types = -:: +For printing integer types, we have the following format specifiers: + + .. flat-table:: + :widths: 2 2 + + * - **Type** + - **Specifier** + + * - ``int`` +- ``%d`` or ``%x`` + + * - ``unsigned int`` + - ``%u`` or ``%x`` + + * - ``long`` + - ``%ld`` or ``%lx`` + + * - ``unsigned long`` + - ``%lu`` or ``%lx`` + + * - ``long long`` + - ``%lld`` or ``%llx`` - If variable is of Type, use printk format specifier: - - int %d or %x - unsigned int%u or %x - long%ld or %lx - unsigned long %lu or %lx - long long %lld or %llx - unsigned long long %llu or %llx - size_t %zu or %zx - ssize_t %zd or %zx - s32 %d or %x - u32 %u or %x - s64 %lld or %llx - u64 %llu or %llx - -If is dependent on a config option for its size (e.g., ``sector_t``, + * - ``unsigned long long`` + - ``%llu`` or ``%llx`` + + * - ``size_t`` + - ``%zu`` or ``%zx`` + + * - ``ssize_t`` + - ``%zd`` or ``%zx`` + + * - ``s32`` + - ``%d`` or ``%x`` + + * - ``u32`` + - ``%u`` or ``%x`` + + * - ``s64`` + - ``%lld`` or ``%llx`` + + * - ``u64`` + - ``%llu`` or ``%llx`` + + +If is dependent on a config option for its size (e.g., ``sector_t``, ``blkcnt_t``) or is architecture-dependent for its size (e.g., ``tcflag_t``), use a format specifier of its largest possible type and explicitly cast to it. Example:: - printk("test: sector number/total blocks: %llu/%llu\n", - (unsigned long long)sector, (unsigned long long)blockcount); + printk("test: total blocks: %llu\n", (unsigned long long)blockcount); -Reminder: ``sizeof()`` result is of type ``size_t``. +Reminder: ``sizeof()`` returns type ``size_t``. -The kernel's printf does not support ``%n``. For obvious reasons, floating +The kernel's pri
Re: [PATCH] doc: convert printk-formats.txt to rst
> Am 06.12.2017 um 02:45 schrieb Tobin C. Harding : > > Documentation/printk-formats.txt is a candidate for conversion to > ReStructuredText format. Some effort has already been made to do this > conversion even thought the suffix is currently .txt > > Changes required to complete conversion > > - Add double backticks where needed. > - Add entry to Documentation/index.rst > - Use flat-table instead of ASCII table. [...] > += > +How to Get ``printk`` Format Specifiers Right > += > > :Author: Randy Dunlap > :Author: Andrew Murray > @@ -8,56 +8,91 @@ How to get printk format specifiers right > Integer types > = > > -:: > +For printing integer types, we have the following format specifiers: > + > + .. flat-table:: > + :widths: 2 2 > + > + * - **Type** > + - **Specifier** > + > + * - ``int`` > +- ``%d`` or ``%x`` > + > + * - ``unsigned int`` > + - ``%u`` or ``%x`` > + > + * - ``long`` > + - ``%ld`` or ``%lx`` > + > + * - ``unsigned long`` > + - ``%lu`` or ``%lx`` > + > + * - ``long long`` > + - ``%lld`` or ``%llx`` > > - If variable is of Type, use printk format specifier: > - > - int %d or %x > - unsigned int%u or %x > - long%ld or %lx > - unsigned long %lu or %lx > - long long %lld or %llx > - unsigned long long %llu or %llx > - size_t %zu or %zx > - ssize_t %zd or %zx > - s32 %d or %x > - u32 %u or %x > - s64 %lld or %llx > - u64 %llu or %llx > - > -If is dependent on a config option for its size (e.g., ``sector_t``, > + * - ``unsigned long long`` > + - ``%llu`` or ``%llx`` > + > + * - ``size_t`` > + - ``%zu`` or ``%zx`` > + > + * - ``ssize_t`` > + - ``%zd`` or ``%zx`` > + > + * - ``s32`` > + - ``%d`` or ``%x`` > + > + * - ``u32`` > + - ``%u`` or ``%x`` > + > + * - ``s64`` > + - ``%lld`` or ``%llx`` > + > + * - ``u64`` > + - ``%llu`` or ``%llx`` > + > + Thanks! just a question .. might it be better we stay with ASCII table in cases like this. I guess this table won't changed often. The flat-table directive is good for big and therefore frequently changed tables where a small precise diff reduce the patch. But flat-table is also hard to read in plain text. Its a balancing and thats my opinion, lets hear what other say ... -- Markus 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] doc: convert printk-formats.txt to rst
On Wed, 2017-12-06 at 08:11 +0100, Markus Heiser wrote: > > Am 06.12.2017 um 02:45 schrieb Tobin C. Harding : > > Documentation/printk-formats.txt is a candidate for conversion to > > ReStructuredText format. Some effort has already been made to do this > > conversion even thought the suffix is currently .txt [] > just a question .. might it be better we stay with ASCII table > in cases like this. I guess this table won't changed often. > The flat-table directive is good for big and therefore frequently > changed tables where a small precise diff reduce the patch. > But flat-table is also hard to read in plain text. Its a balancing > and thats my opinion, lets hear what other say ... I think the proposed conversion is unreadable and the original table quite clear. -- 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