[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
