* Re: [PATCH] Documentation/features/locking: update lists
From: Jonathan Corbet @ 2019-07-26 20:45 UTC (permalink / raw)
To: Mark Rutland; +Cc: linux-kernel, linux-doc
In-Reply-To: <20190723132203.51814-1-mark.rutland@arm.com>
On Tue, 23 Jul 2019 14:22:03 +0100
Mark Rutland <mark.rutland@arm.com> wrote:
> The locking feature lists don't match reality as of v5.3-rc1:
>
> * arm64 moved to queued spinlocks in commit:
>
> c11090474d70590170cf5fa6afe85864ab494b37
>
> ("arm64: locking: Replace ticket lock implementation with qspinlock")
>
> * xtensa moved to queued spinlocks and rwlocks in commit:
>
> 579afe866f52adcd921272a224ab36733051059c
>
> ("xtensa: use generic spinlock/rwlock implementation")
>
> * architecture-specific rwsem support was removed in commit:
>
> 46ad0840b1584b92b5ff2cc3ed0b011dd6b8e0f1
>
> ("locking/rwsem: Remove arch specific rwsem files")
>
> So update the feature lists accordingly, and remove the now redundant
> rwsem-optimized list.
>
> Signed-off-by: Mark Rutland <mark.rutland@arm.com>
Applied, thanks.
jon
^ permalink raw reply
* Re: [PATCH v1] coda: Fix typo in the struct CodaCred documentation
From: Jonathan Corbet @ 2019-07-26 20:43 UTC (permalink / raw)
To: Andy Shevchenko; +Cc: Jan Harkes, coda, codalist, linux-doc
In-Reply-To: <20190723165750.66229-1-andriy.shevchenko@linux.intel.com>
On Tue, 23 Jul 2019 19:57:50 +0300
Andy Shevchenko <andriy.shevchenko@linux.intel.com> wrote:
> Documentation mistakenly refers to a different type while explaining
> the contents of the struct CodaCred.
>
> Fix the typo in the struct CodaCred description in the documentation.
>
> Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
People still use coda? :)
Applied, thanks.
jon
^ permalink raw reply
* Re: [PATCH] Correct documentation for /proc/schedstat
From: Jonathan Corbet @ 2019-07-26 20:41 UTC (permalink / raw)
To: Phil Frost; +Cc: Ingo Molnar, trivial, linux-doc, linux-kernel
In-Reply-To: <20190724185029.26822-1-indigo@bitglue.com>
On Wed, 24 Jul 2019 11:50:27 -0700
Phil Frost <indigo@bitglue.com> wrote:
> Commit 425e0968a25fa3f111f9919964cac079738140b5 ("sched: move code into
> kernel/sched_stats.h") appears to have inadvertently changed the unit of
> time from jiffies to nanoseconds as part of the implementation of CFS.
>
> Signed-off-by: Phil Frost <indigo@bitglue.com>
> ---
> Documentation/scheduler/sched-stats.txt | 10 ++++++++--
> 1 file changed, 8 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/scheduler/sched-stats.txt b/Documentation/scheduler/sched-stats.txt
> index 8259b34a66ae..b6c1807a01b3 100644
> --- a/Documentation/scheduler/sched-stats.txt
> +++ b/Documentation/scheduler/sched-stats.txt
> @@ -19,6 +19,11 @@ are no architectures which need more than three domain levels. The first
> field in the domain stats is a bit map indicating which cpus are affected
> by that domain.
>
> +2.6.23 introduced the CFS scheduler, and also an inadvertent
> +backwards-incompatible change to the statistics. Although the schedstat version
> +is 14 in either case, in 2.6.23 and later, counters accumulate time in
> +nanoseconds. Prior to that, jiffies.
Clearly, making the documentation correct is a good thing to do. I do
have to wonder if we really have to document how things were 12 years ago
as well, though. Anybody who is unfortunate enough to be dealing with a
pre-2.6.23 kernel will want to refer to the documentation files shipped
with that kernel rather than what we have now. So I'd recommend just
making the file reflect the current state of affairs.
Thanks,
jon
^ permalink raw reply
* Re: [PATCH] docs: admin-guide: Adjust title underline length
From: Jonathan Corbet @ 2019-07-26 20:34 UTC (permalink / raw)
To: Fabio Estevam; +Cc: mchehab+samsung, linux-doc
In-Reply-To: <20190726162754.5341-1-festevam@gmail.com>
On Fri, 26 Jul 2019 13:27:54 -0300
Fabio Estevam <festevam@gmail.com> wrote:
> The following warning is seen when building 'make htmldocs':
>
> Documentation/admin-guide/sysctl/kernel.rst:397: WARNING: Title underline too short.
>
> Fix it by adjusting the title underline length appropriately.
>
> Signed-off-by: Fabio Estevam <festevam@gmail.com>
So this appears to be fixing a change that came into linux-next via the -mm
tree; it's not in mainline or docs-next. That means I can't apply it. I'd
suggest resposting with a copy to Andrew Morton; that should let it land
in the right place.
Thanks,
jon
^ permalink raw reply
* Re: [PATCH] MAINTAINERS: add entries for some documentation scripts
From: Jonathan Corbet @ 2019-07-26 20:30 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel
In-Reply-To: <b21677443a602c5dc263537fa48f0e78da75187a.1564152752.git.mchehab+samsung@kernel.org>
On Fri, 26 Jul 2019 11:52:34 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> There are some documentation scripts I wrote with doesn't
> have any maintainer at maintainer's file.
>
> Add them to the DOCUMENTATION entry, in order to have
> Jon and linux-doc ML c/c on those patches, plus a new
> entry to ensure that I'll be c/c when people send patches
> to those.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Applied, thanks.
jon
^ permalink raw reply
* Re: [PATCH v3 2/2] doc: Update documentation for page_idle virtual address indexing
From: Joel Fernandes @ 2019-07-26 20:26 UTC (permalink / raw)
To: sspatil
Cc: linux-kernel, adobriyan, akpm, bgregg, chansen3, dancol, fmayer,
joaodias, corbet, keescook, kernel-team, linux-api, linux-doc,
linux-fsdevel, linux-mm, mhocko, rppt, minchan, namhyung, guro,
sfr, surenb, tkjos, vdavydov.dev, vbabka, wvw, sspatil+mutt
In-Reply-To: <20190726201710.GA144547@google.com>
On Fri, Jul 26, 2019 at 01:17:10PM -0700, sspatil@google.com wrote:
> Thanks Joel, just a couple of nits for the doc inline below. Other than that,
>
> Reviewed-by: Sandeep Patil <sspatil@google.com>
Thanks!
> I'll plan on making changes to Android to use this instead of the pagemap +
> page_idle. I think it will also be considerably faster.
Cool, glad to know.
> On Fri, Jul 26, 2019 at 11:23:19AM -0400, Joel Fernandes (Google) wrote:
> > This patch updates the documentation with the new page_idle tracking
> > feature which uses virtual address indexing.
> >
> > Signed-off-by: Joel Fernandes (Google) <joel@joelfernandes.org>
> > ---
> > .../admin-guide/mm/idle_page_tracking.rst | 43 ++++++++++++++++---
> > 1 file changed, 36 insertions(+), 7 deletions(-)
> >
> > diff --git a/Documentation/admin-guide/mm/idle_page_tracking.rst b/Documentation/admin-guide/mm/idle_page_tracking.rst
> > index df9394fb39c2..1eeac78c94a7 100644
> > --- a/Documentation/admin-guide/mm/idle_page_tracking.rst
> > +++ b/Documentation/admin-guide/mm/idle_page_tracking.rst
> > @@ -19,10 +19,14 @@ It is enabled by CONFIG_IDLE_PAGE_TRACKING=y.
> >
> > User API
> > ========
> > +There are 2 ways to access the idle page tracking API. One uses physical
> > +address indexing, another uses a simpler virtual address indexing scheme.
> >
> > -The idle page tracking API is located at ``/sys/kernel/mm/page_idle``.
> > -Currently, it consists of the only read-write file,
> > -``/sys/kernel/mm/page_idle/bitmap``.
> > +Physical address indexing
> > +-------------------------
> > +The idle page tracking API for physical address indexing using page frame
> > +numbers (PFN) is located at ``/sys/kernel/mm/page_idle``. Currently, it
> > +consists of the only read-write file, ``/sys/kernel/mm/page_idle/bitmap``.
> >
> > The file implements a bitmap where each bit corresponds to a memory page. The
> > bitmap is represented by an array of 8-byte integers, and the page at PFN #i is
> > @@ -74,6 +78,31 @@ See :ref:`Documentation/admin-guide/mm/pagemap.rst <pagemap>` for more
> > information about ``/proc/pid/pagemap``, ``/proc/kpageflags``, and
> > ``/proc/kpagecgroup``.
> >
> > +Virtual address indexing
> > +------------------------
> > +The idle page tracking API for virtual address indexing using virtual page
> > +frame numbers (VFN) is located at ``/proc/<pid>/page_idle``. It is a bitmap
> > +that follows the same semantics as ``/sys/kernel/mm/page_idle/bitmap``
> > +except that it uses virtual instead of physical frame numbers.
> > +
> > +This idle page tracking API does not need deal with PFN so it does not require
>
> s/need//
>
> > +prior lookups of ``pagemap`` in order to find if page is idle or not. This is
>
> s/in order to find if page is idle or not//
Fixed both, thank you! Will send out update soon.
thanks,
- Joel
^ permalink raw reply
* Re: [PATCH 0/7] Fix broken references to files under Documentation/*
From: Atish Patra @ 2019-07-26 20:18 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
Łukasz Stelmach, Rob Herring
In-Reply-To: <20190726171352.5eaa4d83@coco.lan>
On 7/26/19 1:14 PM, Mauro Carvalho Chehab wrote:
> Em Fri, 26 Jul 2019 12:55:36 -0700
> Atish Patra <atish.patra@wdc.com> escreveu:
>
>> On 7/26/19 4:47 AM, Mauro Carvalho Chehab wrote:
>>> Solves most of the pending broken references upstream, except for two of
>>> them:
>>>
>>> $ ./scripts/documentation-file-ref-check
>>> Documentation/riscv/boot-image-header.txt: Documentation/riscv/booting.txt
>>> MAINTAINERS: Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
>>>
>>> As written at boot-image-header.txt, it is waiting for the addition of
>>> a future file:
>>>
>>> "The complete booting guide will be available at
>>> Documentation/riscv/booting.txt."
>>>
>>
>> Yeah. We don't have complete booting guide defined in RISC-V land.
>> Documentation/riscv/booting.txt will be available once we have that.
>>
>> In the mean time, do we need to convert boot-image-header.txt to
>> boot-image-header.rst and fix the reference to
>> Documentation/riscv/booting.rst as well ?
>
> Well, in the mean time, every time someone builds the Kernel with
> COMPILE_TEST enabled, a warning will be produced.
>
> So, my suggestion would be to write it on a different way, like:
>
> "A complete booting guide is being written and should be
> available on future versions."
>
> Or:
> TODO:
> Write a complete booting guide.
>
> And update this once the guide is finished. This should be enough
> to prevent the warning.
>
Sounds good to me.
> With regards to converting it to ReST, that's recommended. I suspect
> we could be able to finish the entire doc conversion in a couple
> Kernel versions.
>
Sure.
> Also, it should be really trivial to convert this one to ReST.
>
Yes. Let me know if you prefer to update it along with your series or I
will send the patch.
> Thanks,
> Mauro
>
--
Regards,
Atish
^ permalink raw reply
* Re: [PATCH v3 2/2] doc: Update documentation for page_idle virtual address indexing
From: sspatil @ 2019-07-26 20:17 UTC (permalink / raw)
To: joel, linux-kernel, adobriyan, akpm, bgregg, chansen3, dancol,
fmayer, joaodias, joelaf, corbet, keescook, kernel-team,
linux-api, linux-doc, linux-fsdevel, linux-mm, mhocko, rppt,
minchan, namhyung, guro, sfr, surenb, tkjos, vdavydov.dev, vbabka,
wvw, sspatil+mutt
Cc: linux-kernel, Alexey Dobriyan, Andrew Morton, Brendan Gregg,
Christian Hansen, dancol, fmayer, joaodias, joelaf,
Jonathan Corbet, Kees Cook, kernel-team, linux-api, linux-doc,
linux-fsdevel, linux-mm, Michal Hocko, Mike Rapoport, minchan,
namhyung, Roman Gushchin, Stephen Rothwell, surenb, tkjos,
Vladimir Davydov, Vlastimil Babka, wvw
In-Reply-To: <20190726152319.134152-2-joel@joelfernandes.org>
Thanks Joel, just a couple of nits for the doc inline below. Other than that,
Reviewed-by: Sandeep Patil <sspatil@google.com>
I'll plan on making changes to Android to use this instead of the pagemap +
page_idle. I think it will also be considerably faster.
On Fri, Jul 26, 2019 at 11:23:19AM -0400, Joel Fernandes (Google) wrote:
> This patch updates the documentation with the new page_idle tracking
> feature which uses virtual address indexing.
>
> Signed-off-by: Joel Fernandes (Google) <joel@joelfernandes.org>
> ---
> .../admin-guide/mm/idle_page_tracking.rst | 43 ++++++++++++++++---
> 1 file changed, 36 insertions(+), 7 deletions(-)
>
> diff --git a/Documentation/admin-guide/mm/idle_page_tracking.rst b/Documentation/admin-guide/mm/idle_page_tracking.rst
> index df9394fb39c2..1eeac78c94a7 100644
> --- a/Documentation/admin-guide/mm/idle_page_tracking.rst
> +++ b/Documentation/admin-guide/mm/idle_page_tracking.rst
> @@ -19,10 +19,14 @@ It is enabled by CONFIG_IDLE_PAGE_TRACKING=y.
>
> User API
> ========
> +There are 2 ways to access the idle page tracking API. One uses physical
> +address indexing, another uses a simpler virtual address indexing scheme.
>
> -The idle page tracking API is located at ``/sys/kernel/mm/page_idle``.
> -Currently, it consists of the only read-write file,
> -``/sys/kernel/mm/page_idle/bitmap``.
> +Physical address indexing
> +-------------------------
> +The idle page tracking API for physical address indexing using page frame
> +numbers (PFN) is located at ``/sys/kernel/mm/page_idle``. Currently, it
> +consists of the only read-write file, ``/sys/kernel/mm/page_idle/bitmap``.
>
> The file implements a bitmap where each bit corresponds to a memory page. The
> bitmap is represented by an array of 8-byte integers, and the page at PFN #i is
> @@ -74,6 +78,31 @@ See :ref:`Documentation/admin-guide/mm/pagemap.rst <pagemap>` for more
> information about ``/proc/pid/pagemap``, ``/proc/kpageflags``, and
> ``/proc/kpagecgroup``.
>
> +Virtual address indexing
> +------------------------
> +The idle page tracking API for virtual address indexing using virtual page
> +frame numbers (VFN) is located at ``/proc/<pid>/page_idle``. It is a bitmap
> +that follows the same semantics as ``/sys/kernel/mm/page_idle/bitmap``
> +except that it uses virtual instead of physical frame numbers.
> +
> +This idle page tracking API does not need deal with PFN so it does not require
s/need//
> +prior lookups of ``pagemap`` in order to find if page is idle or not. This is
s/in order to find if page is idle or not//
> +an advantage on some systems where looking up PFN is considered a security
> +issue. Also in some cases, this interface could be slightly more reliable to
> +use than physical address indexing, since in physical address indexing, address
> +space changes can occur between reading the ``pagemap`` and reading the
> +``bitmap``, while in virtual address indexing, the process's ``mmap_sem`` is
> +held for the duration of the access.
> +
> +To estimate the amount of pages that are not used by a workload one should:
> +
> + 1. Mark all the workload's pages as idle by setting corresponding bits in
> + ``/proc/<pid>/page_idle``.
> +
> + 2. Wait until the workload accesses its working set.
> +
> + 3. Read ``/proc/<pid>/page_idle`` and count the number of bits set.
> +
> .. _impl_details:
>
> Implementation Details
> @@ -99,10 +128,10 @@ When a dirty page is written to swap or disk as a result of memory reclaim or
> exceeding the dirty memory limit, it is not marked referenced.
>
> The idle memory tracking feature adds a new page flag, the Idle flag. This flag
> -is set manually, by writing to ``/sys/kernel/mm/page_idle/bitmap`` (see the
> -:ref:`User API <user_api>`
> -section), and cleared automatically whenever a page is referenced as defined
> -above.
> +is set manually, by writing to ``/sys/kernel/mm/page_idle/bitmap`` for physical
> +addressing or by writing to ``/proc/<pid>/page_idle`` for virtual
> +addressing (see the :ref:`User API <user_api>` section), and cleared
> +automatically whenever a page is referenced as defined above.
>
> When a page is marked idle, the Accessed bit must be cleared in all PTEs it is
> mapped to, otherwise we will not be able to detect accesses to the page coming
> --
> 2.22.0.709.g102302147b-goog
>
> --
> To unsubscribe from this group and stop receiving emails from it, send an email to kernel-team+unsubscribe@android.com.
>
^ permalink raw reply
* Re: [PATCH 0/7] Fix broken references to files under Documentation/*
From: Mauro Carvalho Chehab @ 2019-07-26 20:13 UTC (permalink / raw)
To: Atish Patra
Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
Łukasz Stelmach, Rob Herring
In-Reply-To: <04794d40-0b39-0223-c91e-03b46cb6e2db@wdc.com>
Em Fri, 26 Jul 2019 12:55:36 -0700
Atish Patra <atish.patra@wdc.com> escreveu:
> On 7/26/19 4:47 AM, Mauro Carvalho Chehab wrote:
> > Solves most of the pending broken references upstream, except for two of
> > them:
> >
> > $ ./scripts/documentation-file-ref-check
> > Documentation/riscv/boot-image-header.txt: Documentation/riscv/booting.txt
> > MAINTAINERS: Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
> >
> > As written at boot-image-header.txt, it is waiting for the addition of
> > a future file:
> >
> > "The complete booting guide will be available at
> > Documentation/riscv/booting.txt."
> >
>
> Yeah. We don't have complete booting guide defined in RISC-V land.
> Documentation/riscv/booting.txt will be available once we have that.
>
> In the mean time, do we need to convert boot-image-header.txt to
> boot-image-header.rst and fix the reference to
> Documentation/riscv/booting.rst as well ?
Well, in the mean time, every time someone builds the Kernel with
COMPILE_TEST enabled, a warning will be produced.
So, my suggestion would be to write it on a different way, like:
"A complete booting guide is being written and should be
available on future versions."
Or:
TODO:
Write a complete booting guide.
And update this once the guide is finished. This should be enough
to prevent the warning.
With regards to converting it to ReST, that's recommended. I suspect
we could be able to finish the entire doc conversion in a couple
Kernel versions.
Also, it should be really trivial to convert this one to ReST.
Thanks,
Mauro
^ permalink raw reply
* Zdravstvujte! Vas interesuyut klientskie bazy dannyh?
From: linux-doc @ 2019-07-26 19:54 UTC (permalink / raw)
To: pMZJosvFE1linux-doc
Zdravstvujte! Vas interesuyut klientskie bazy dannyh?
^ permalink raw reply
* Re: [PATCH 0/7] Fix broken references to files under Documentation/*
From: Atish Patra @ 2019-07-26 19:55 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
Łukasz Stelmach, Rob Herring
In-Reply-To: <cover.1564140865.git.mchehab+samsung@kernel.org>
On 7/26/19 4:47 AM, Mauro Carvalho Chehab wrote:
> Solves most of the pending broken references upstream, except for two of
> them:
>
> $ ./scripts/documentation-file-ref-check
> Documentation/riscv/boot-image-header.txt: Documentation/riscv/booting.txt
> MAINTAINERS: Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
>
> As written at boot-image-header.txt, it is waiting for the addition of
> a future file:
>
> "The complete booting guide will be available at
> Documentation/riscv/booting.txt."
>
Yeah. We don't have complete booting guide defined in RISC-V land.
Documentation/riscv/booting.txt will be available once we have that.
In the mean time, do we need to convert boot-image-header.txt to
boot-image-header.rst and fix the reference to
Documentation/riscv/booting.rst as well ?
> The second is due to this patch, pending to be merged:
> https://lore.kernel.org/patchwork/patch/994210/
>
> I'm not a DT expert, but I can't see any issue with this patch, except
> for a missing acked-by a DT maintainer, and a possible conversion to
> yaml. IMO, the best fix for this would be to merge the DT patch.
>
> Patch 1 was already submitted before, together with the v1 of
> my PDF fix series.
>
> Mauro Carvalho Chehab (7):
> docs: fix broken doc references due to renames
> docs: generic-counter.rst: fix broken references for ABI file
> MAINTAINERS: fix reference to net phy ABI file
> MAINTAINERS: fix a renamed DT reference
> docs: cgroup-v1/blkio-controller.rst: remove a CFQ left over
> docs: zh_CN: howto.rst: fix a broken reference
> docs: dt: fix a sound binding broken reference
>
> Documentation/RCU/rculist_nulls.txt | 2 +-
> .../admin-guide/cgroup-v1/blkio-controller.rst | 6 ------
> .../devicetree/bindings/arm/idle-states.txt | 2 +-
> .../devicetree/bindings/sound/sun8i-a33-codec.txt | 2 +-
> Documentation/driver-api/generic-counter.rst | 4 ++--
> Documentation/locking/spinlocks.rst | 4 ++--
> Documentation/memory-barriers.txt | 2 +-
> .../translations/ko_KR/memory-barriers.txt | 2 +-
> Documentation/translations/zh_CN/process/howto.rst | 2 +-
> Documentation/watchdog/hpwdt.rst | 2 +-
> MAINTAINERS | 14 +++++++-------
> drivers/gpu/drm/drm_modes.c | 2 +-
> drivers/i2c/busses/i2c-nvidia-gpu.c | 2 +-
> drivers/scsi/hpsa.c | 4 ++--
> 14 files changed, 22 insertions(+), 28 deletions(-)
>
--
Regards,
Atish
^ permalink raw reply
* [PATCH 5/5] docs: zh_CN: howto.rst: fix a broken reference
From: Mauro Carvalho Chehab @ 2019-07-26 19:29 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Harry Wei, Alex Shi, Federico Vaga,
SeongJae Park
In-Reply-To: <5c44856436bbaeb4f2d4b750365b82de973ad054.1564169297.git.mchehab+samsung@kernel.org>
There's a broken reference there pointing to the long gone
DocBook dir.
While I don't read chinese, Google translator translates it
to:
"The generated documentation will be placed in
the Documentation/DocBook/ directory."
Well, we know that the output will be Documentation/output
dir. So, let's fix this one.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/translations/zh_CN/process/howto.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/translations/zh_CN/process/howto.rst b/Documentation/translations/zh_CN/process/howto.rst
index 5b671178b17b..c4ff8356b88d 100644
--- a/Documentation/translations/zh_CN/process/howto.rst
+++ b/Documentation/translations/zh_CN/process/howto.rst
@@ -147,7 +147,7 @@ Linux内核代码中包含有大量的文档。这些文档对于学习如何与
关于补丁是什么以及如何将它打在不同内核开发分支上的好介绍
内核还拥有大量从代码自动生成的文档。它包含内核内部API的全面介绍以及如何
-妥善处理加锁的规则。生成的文档会放在 Documentation/DocBook/目录下。在内
+妥善处理加锁的规则。生成的文档会放在 Documentation/output/目录下。在内
核源码的主目录中使用以下不同命令将会分别生成PDF、Postscript、HTML和手册
页等不同格式的文档::
--
2.21.0
^ permalink raw reply related
* [PATCH 1/5] MAINTAINERS: fix broken ref for ABI sysfs-bus-counter-ftm-quaddec
From: Mauro Carvalho Chehab @ 2019-07-26 19:29 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David S. Miller, Greg Kroah-Hartman,
Jonathan Cameron, Nicolas Ferre
There's a typo here:
sysfs-bus-counter-ftm-quadddec -> sysfs-bus-counter-ftm-quaddec
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
MAINTAINERS | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/MAINTAINERS b/MAINTAINERS
index 4b59bdc1aaf2..506ac266cf57 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -6317,7 +6317,7 @@ FLEXTIMER FTM-QUADDEC DRIVER
M: Patrick Havelange <patrick.havelange@essensium.com>
L: linux-iio@vger.kernel.org
S: Maintained
-F: Documentation/ABI/testing/sysfs-bus-counter-ftm-quadddec
+F: Documentation/ABI/testing/sysfs-bus-counter-ftm-quaddec
F: Documentation/devicetree/bindings/counter/ftm-quaddec.txt
F: drivers/counter/ftm-quaddec.c
--
2.21.0
^ permalink raw reply related
* [PATCH 3/5] MAINTAINERS: fix a renamed DT reference
From: Mauro Carvalho Chehab @ 2019-07-26 19:29 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David S. Miller, Greg Kroah-Hartman,
Jonathan Cameron, Nicolas Ferre
In-Reply-To: <5c44856436bbaeb4f2d4b750365b82de973ad054.1564169297.git.mchehab+samsung@kernel.org>
Fix this rename:
Documentation/devicetree/bindings/i2c/{i2c-mv64xxx.txt -> marvell,mv64xxx-i2c.yaml}
Fixes: f8bbde72ef44 ("dt-bindings: i2c: mv64xxx: Add YAML schemas")
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
MAINTAINERS | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/MAINTAINERS b/MAINTAINERS
index b57dd8494c93..454a26c77fa0 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7507,7 +7507,7 @@ I2C MV64XXX MARVELL AND ALLWINNER DRIVER
M: Gregory CLEMENT <gregory.clement@bootlin.com>
L: linux-i2c@vger.kernel.org
S: Maintained
-F: Documentation/devicetree/bindings/i2c/i2c-mv64xxx.txt
+F: Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml
F: drivers/i2c/busses/i2c-mv64xxx.c
I2C OVER PARALLEL PORT
--
2.21.0
^ permalink raw reply related
* [PATCH 2/5] MAINTAINERS: fix reference to net phy ABI file
From: Mauro Carvalho Chehab @ 2019-07-26 19:29 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David S. Miller, Greg Kroah-Hartman,
Jonathan Cameron, Nicolas Ferre
In-Reply-To: <5c44856436bbaeb4f2d4b750365b82de973ad054.1564169297.git.mchehab+samsung@kernel.org>
The file sysfs-bus-mdio got removed in favor of sysfs-class-net-phydev,
with contained a duplicated set of information.
Fixes: a6cd0d2d493a ("Documentation: net-sysfs: Remove duplicate PHY device documentation")
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
MAINTAINERS | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/MAINTAINERS b/MAINTAINERS
index 506ac266cf57..b57dd8494c93 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -6061,7 +6061,7 @@ M: Florian Fainelli <f.fainelli@gmail.com>
M: Heiner Kallweit <hkallweit1@gmail.com>
L: netdev@vger.kernel.org
S: Maintained
-F: Documentation/ABI/testing/sysfs-bus-mdio
+F: Documentation/ABI/testing/sysfs-class-net-phydev
F: Documentation/devicetree/bindings/net/ethernet-phy.yaml
F: Documentation/devicetree/bindings/net/mdio*
F: Documentation/networking/phy.rst
--
2.21.0
^ permalink raw reply related
* [PATCH 4/5] docs: cgroup-v1/blkio-controller.rst: remove a CFQ left over
From: Mauro Carvalho Chehab @ 2019-07-26 19:29 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Tejun Heo, Jens Axboe, Li Zefan, Johannes Weiner,
cgroups, linux-block
In-Reply-To: <5c44856436bbaeb4f2d4b750365b82de973ad054.1564169297.git.mchehab+samsung@kernel.org>
changeset fb5772cbfe48 ("blkio-controller.txt: Remove references to CFQ")
removed cgroup references to CFQ, but it kept one left. Get rid of
it.
Fixes: fb5772cbfe48 ("blkio-controller.txt: Remove references to CFQ")
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/admin-guide/cgroup-v1/blkio-controller.rst | 6 ------
1 file changed, 6 deletions(-)
diff --git a/Documentation/admin-guide/cgroup-v1/blkio-controller.rst b/Documentation/admin-guide/cgroup-v1/blkio-controller.rst
index 1d7d962933be..36d43ae7dc13 100644
--- a/Documentation/admin-guide/cgroup-v1/blkio-controller.rst
+++ b/Documentation/admin-guide/cgroup-v1/blkio-controller.rst
@@ -130,12 +130,6 @@ Proportional weight policy files
dev weight
8:16 300
-- blkio.leaf_weight[_device]
- - Equivalents of blkio.weight[_device] for the purpose of
- deciding how much weight tasks in the given cgroup has while
- competing with the cgroup's child cgroups. For details,
- please refer to Documentation/block/cfq-iosched.txt.
-
- blkio.time
- disk time allocated to cgroup per device in milliseconds. First
two fields specify the major and minor number of the device and
--
2.21.0
^ permalink raw reply related
* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
From: Mauro Carvalho Chehab @ 2019-07-26 19:14 UTC (permalink / raw)
To: Joel Fernandes
Cc: Paul E. McKenney, Josh Triplett, Steven Rostedt,
Mathieu Desnoyers, Lai Jiangshan, Jonathan Corbet, rcu, linux-doc,
Markus Heiser
In-Reply-To: <20190726180201.GE146401@google.com>
Em Fri, 26 Jul 2019 14:02:01 -0400
Joel Fernandes <joel@joelfernandes.org> escreveu:
> On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> [snip]
> > +| until the assignment to ``gp``, by which time both fields are fully |
> > +| initialized. So reordering the assignments to ``p->a`` and ``p->b`` |
> > +| cannot possibly cause any problems. |
> > ++-----------------------------------------------------------------------+
> > +
> > +It is tempting to assume that the reader need not do anything special to
> > +control its accesses to the RCU-protected data, as shown in
> > +``do_something_gp_buggy()`` below:
> > +
> > + ::
> > +
> > + 1 bool do_something_gp_buggy(void)
> > + 2 {
> > + 3 rcu_read_lock();
> > + 4 p = gp; /* OPTIMIZATIONS GALORE!!! */
> > + 5 if (p) {
> > + 6 do_something(p->a, p->b);
> > + 7 rcu_read_unlock();
> > + 8 return true;
> > + 9 }
> > + 10 rcu_read_unlock();
> > + 11 return false;
> > + 12 }
> > +
> > +However, this temptation must be resisted because there are a
> > +surprisingly large number of ways that the compiler (to say nothing of
> > +`DEC Alpha CPUs <https://h71000.www7.hp.com/wizard/wiz_2637.html>`__)
> > +can trip this code up. For but one example, if the compiler were short
> > +of registers, it might choose to refetch from ``gp`` rather than keeping
> > +a separate copy in ``p`` as follows:
> > +
> > + ::
> > +
> > + 1 bool do_something_gp_buggy_optimized(void)
> > + 2 {
> > + 3 rcu_read_lock();
> > + 4 if (gp) { /* OPTIMIZATIONS GALORE!!! */
> > + 5 do_something(gp->a, gp->b);
> > + 6 rcu_read_unlock();
> > + 7 return true;
> > + 8 }
> > + 9 rcu_read_unlock();
> > + 10 return false;
> > + 11 }
> > +
> > +If this function ran concurrently with a series of updates that replaced
> > +the current structure with a new one, the fetches of ``gp->a`` and
> > +``gp->b`` might well come from two different structures, which could
> > +cause serious confusion. To prevent this (and much else besides),
> > +``do_something_gp()`` uses ``rcu_dereference()`` to fetch from ``gp``:
> > +
> > + ::
> > +
> > + 1 bool do_something_gp(void)
> > + 2 {
> > + 3 rcu_read_lock();
> > + 4 p = rcu_dereference(gp);
> > + 5 if (p) {
> > + 6 do_something(p->a, p->b);
> > + 7 rcu_read_unlock();
> > + 8 return true;
> > + 9 }
> > + 10 rcu_read_unlock();
> > + 11 return false;
> > + 12 }
> > +
> > +The ``rcu_dereference()`` uses volatile casts and (for DEC Alpha) memory
> > +barriers in the Linux kernel. Should a `high-quality implementation of
> > +C11 ``memory_order_consume``
> > +[PDF] <http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf>`__
> > +ever appear, then ``rcu_dereference()`` could be implemented as a
> > +``memory_order_consume`` load. Regardless of the exact implementation, a
> > +pointer fetched by ``rcu_dereference()`` may not be used outside of the
> > +outermost RCU read-side critical section containing that
> > +``rcu_dereference()``, unless protection of the corresponding data
> > +element has been passed from RCU to some other synchronization
> > +mechanism, most commonly locking or `reference
> > +counting <https://www.kernel.org/doc/Documentation/RCU/rcuref.txt>`__.
>
> From the make htmldocs output, this appears very poorly for me, I get
> something like this in the browser:
>
> The rcu_dereference() uses volatile casts and (for DEC Alpha) memory barriers
> in the Linux kernel. Should a high-quality implementation of C11
> ``memory_order_consume` [PDF]
> <http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf>`__ ever
> appear, then rcu_dereference() could be implemented as a memory_order_consume
> load.
>
> Is there a syntax issue here?
Maybe. I tested those with Sphinx 2.0.1. Didn't test with older versions.
I'll do some tests with Sphinx 1.7.9 (with is the current minimal
recommended version) and do some cleanup on those references.
> One more feedback,
> the image under "RCU read-side critical section that started before the current
> grace period:" should probably be blown up a bit.
Unfortunately, the Kernel Sphinx image extension doesn't allow image scaling.
We had to add our own image extension at the Kernel, as otherwise,
for every image, we would need to add one parser for PDF and another
one for SVG.
We would also need an extra parser for DOT.
Markus solved all the 3 image formats with a single extension, but
it currently doesn't allow passing the image size.
-
Markus,
Any reason for the kernel-image extension to not support scaling?
-
If this can't be easily solved at the kernel-image.py extension, a
simple alternative would be to simply scale the SVG file
directly. It should be trivial to re-scale with inkscape, although
the diff may be big.
Thanks,
Mauro
^ permalink raw reply
* [PATCH] tools: memory-model: add it to the Documentation body
From: Mauro Carvalho Chehab @ 2019-07-26 19:01 UTC (permalink / raw)
To: Joel Fernandes, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Alan Stern, Andrea Parri, Will Deacon,
Peter Zijlstra, Boqun Feng, Nicholas Piggin, David Howells,
Jade Alglave, Luc Maranget, Paul E. McKenney, Akira Yokosawa,
Daniel Lustig, Ingo Molnar, Jason Gunthorpe, SeongJae Park,
linux-arch
In-Reply-To: <20190726180201.GE146401@google.com>
The books at tools/memory-model/Documentation are very well
formatted. Congrats to the ones that wrote them!
The manual conversion to ReST is really trivial:
- Add document titles;
- change the bullets on some lists;
- mark code blocks.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/core-api/refcount-vs-atomic.rst | 2 +-
Documentation/index.rst | 1 +
Documentation/tools/memory-model | 1 +
.../memory-model/Documentation/cheatsheet.rst | 36 +++++
.../memory-model/Documentation/cheatsheet.txt | 30 ----
.../{explanation.txt => explanation.rst} | 151 ++++++++++--------
tools/memory-model/Documentation/index.rst | 20 +++
.../{recipes.txt => recipes.rst} | 41 ++---
.../{references.txt => references.rst} | 46 +++---
tools/memory-model/README | 10 +-
10 files changed, 192 insertions(+), 146 deletions(-)
create mode 120000 Documentation/tools/memory-model
create mode 100644 tools/memory-model/Documentation/cheatsheet.rst
delete mode 100644 tools/memory-model/Documentation/cheatsheet.txt
rename tools/memory-model/Documentation/{explanation.txt => explanation.rst} (97%)
create mode 100644 tools/memory-model/Documentation/index.rst
rename tools/memory-model/Documentation/{recipes.txt => recipes.rst} (96%)
rename tools/memory-model/Documentation/{references.txt => references.rst} (71%)
diff --git a/Documentation/core-api/refcount-vs-atomic.rst b/Documentation/core-api/refcount-vs-atomic.rst
index 976e85adffe8..7e6500a6fa76 100644
--- a/Documentation/core-api/refcount-vs-atomic.rst
+++ b/Documentation/core-api/refcount-vs-atomic.rst
@@ -17,7 +17,7 @@ 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
-tools/memory-model/Documentation/explanation.txt.
+tools/memory-model/Documentation/explanation.rst.
memory-barriers.txt and atomic_t.txt provide more background to the
memory ordering in general and for atomic operations specifically.
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 0a564f3c336e..03ff920ac1cb 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -36,6 +36,7 @@ trying to get it to work optimally on a given system.
admin-guide/index
kbuild/index
+ tools/index
Firmware-related documentation
------------------------------
diff --git a/Documentation/tools/memory-model b/Documentation/tools/memory-model
new file mode 120000
index 000000000000..020ed38ce302
--- /dev/null
+++ b/Documentation/tools/memory-model
@@ -0,0 +1 @@
+../../tools/memory-model/Documentation/
\ No newline at end of file
diff --git a/tools/memory-model/Documentation/cheatsheet.rst b/tools/memory-model/Documentation/cheatsheet.rst
new file mode 100644
index 000000000000..35f8749b8a53
--- /dev/null
+++ b/tools/memory-model/Documentation/cheatsheet.rst
@@ -0,0 +1,36 @@
+===========
+Cheat Sheet
+===========
+
+::
+
+ Prior Operation Subsequent Operation
+ --------------- ---------------------------
+ C Self R W RMW Self R W DR DW RMW SV
+ -- ---- - - --- ---- - - -- -- --- --
+
+ Store, e.g., WRITE_ONCE() Y Y
+ Load, e.g., READ_ONCE() Y Y Y Y
+ Unsuccessful RMW operation Y Y Y Y
+ rcu_dereference() Y Y Y Y
+ Successful *_acquire() R Y Y Y Y Y Y
+ Successful *_release() C Y Y Y W Y
+ smp_rmb() Y R Y Y R
+ smp_wmb() Y W Y Y W
+ smp_mb() & synchronize_rcu() CP Y Y Y Y Y Y Y Y
+ Successful full non-void RMW CP Y Y Y Y Y Y Y Y Y Y Y
+ smp_mb__before_atomic() CP Y Y Y a a a a Y
+ smp_mb__after_atomic() CP a a Y Y Y Y Y Y
+
+
+ Key: C: Ordering is cumulative
+ P: Ordering propagates
+ R: Read, for example, READ_ONCE(), or read portion of RMW
+ W: Write, for example, WRITE_ONCE(), or write portion of RMW
+ Y: Provides ordering
+ a: Provides ordering given intervening RMW atomic operation
+ DR: Dependent read (address dependency)
+ DW: Dependent write (address, data, or control dependency)
+ RMW: Atomic read-modify-write operation
+ SELF: Orders self, as opposed to accesses before and/or after
+ SV: Orders later accesses to the same variable
diff --git a/tools/memory-model/Documentation/cheatsheet.txt b/tools/memory-model/Documentation/cheatsheet.txt
deleted file mode 100644
index 33ba98d72b16..000000000000
--- a/tools/memory-model/Documentation/cheatsheet.txt
+++ /dev/null
@@ -1,30 +0,0 @@
- Prior Operation Subsequent Operation
- --------------- ---------------------------
- C Self R W RMW Self R W DR DW RMW SV
- -- ---- - - --- ---- - - -- -- --- --
-
-Store, e.g., WRITE_ONCE() Y Y
-Load, e.g., READ_ONCE() Y Y Y Y
-Unsuccessful RMW operation Y Y Y Y
-rcu_dereference() Y Y Y Y
-Successful *_acquire() R Y Y Y Y Y Y
-Successful *_release() C Y Y Y W Y
-smp_rmb() Y R Y Y R
-smp_wmb() Y W Y Y W
-smp_mb() & synchronize_rcu() CP Y Y Y Y Y Y Y Y
-Successful full non-void RMW CP Y Y Y Y Y Y Y Y Y Y Y
-smp_mb__before_atomic() CP Y Y Y a a a a Y
-smp_mb__after_atomic() CP a a Y Y Y Y Y Y
-
-
-Key: C: Ordering is cumulative
- P: Ordering propagates
- R: Read, for example, READ_ONCE(), or read portion of RMW
- W: Write, for example, WRITE_ONCE(), or write portion of RMW
- Y: Provides ordering
- a: Provides ordering given intervening RMW atomic operation
- DR: Dependent read (address dependency)
- DW: Dependent write (address, data, or control dependency)
- RMW: Atomic read-modify-write operation
- SELF: Orders self, as opposed to accesses before and/or after
- SV: Orders later accesses to the same variable
diff --git a/tools/memory-model/Documentation/explanation.txt b/tools/memory-model/Documentation/explanation.rst
similarity index 97%
rename from tools/memory-model/Documentation/explanation.txt
rename to tools/memory-model/Documentation/explanation.rst
index 68caa9a976d0..227ec75f8dc4 100644
--- a/tools/memory-model/Documentation/explanation.txt
+++ b/tools/memory-model/Documentation/explanation.rst
@@ -1,5 +1,6 @@
+========================================================
Explanation of the Linux-Kernel Memory Consistency Model
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+========================================================
:Author: Alan Stern <stern@rowland.harvard.edu>
:Created: October 2017
@@ -107,7 +108,7 @@ and the flag are memory locations shared between the two CPUs.
We can abstract out the important pieces of the driver code as follows
(the reason for using WRITE_ONCE() and READ_ONCE() instead of simple
-assignment statements is discussed later):
+assignment statements is discussed later)::
int buf = 0, flag = 0;
@@ -219,7 +220,7 @@ Ordering). This model predicts that the undesired outcome for the MP
pattern cannot occur, but in other respects it differs from Sequential
Consistency. One example is the Store Buffer (SB) pattern, in which
each CPU stores to its own shared location and then loads from the
-other CPU's location:
+other CPU's location::
int x = 0, y = 0;
@@ -264,7 +265,7 @@ The counterpart to ordering is a cycle. Ordering rules out cycles:
It's not possible to have X ordered before Y, Y ordered before Z, and
Z ordered before X, because this would mean that X is ordered before
itself. The analysis of the MP example under Sequential Consistency
-involved just such an impossible cycle:
+involved just such an impossible cycle::
W: P0 stores 1 to flag executes before
X: P1 loads 1 from flag executes before
@@ -388,7 +389,7 @@ The protections provided by READ_ONCE(), WRITE_ONCE(), and others are
not perfect; and under some circumstances it is possible for the
compiler to undermine the memory model. Here is an example. Suppose
both branches of an "if" statement store the same value to the same
-location:
+location::
r1 = READ_ONCE(x);
if (r1) {
@@ -402,7 +403,7 @@ location:
For this code, the LKMM predicts that the load from x will always be
executed before either of the stores to y. However, a compiler could
lift the stores out of the conditional, transforming the code into
-something resembling:
+something resembling::
r1 = READ_ONCE(x);
WRITE_ONCE(y, 2);
@@ -418,7 +419,7 @@ model's original prediction could be invalidated by the compiler.
Another issue arises from the fact that in C, arguments to many
operators and function calls can be evaluated in any order. For
-example:
+example::
r1 = f(5) + g(6);
@@ -440,7 +441,7 @@ control (ctrl).
A read and a write event are linked by a data dependency if the value
obtained by the read affects the value stored by the write. As a very
-simple example:
+simple example::
int x, y;
@@ -455,7 +456,7 @@ values of multiple reads.
A read event and another memory access event are linked by an address
dependency if the value obtained by the read affects the location
accessed by the other event. The second event can be either a read or
-a write. Here's another simple example:
+a write. Here's another simple example::
int a[20];
int i;
@@ -471,7 +472,7 @@ pointer.
Finally, a read event and another memory access event are linked by a
control dependency if the value obtained by the read affects whether
-the second event is executed at all. Simple example:
+the second event is executed at all. Simple example::
int x, y;
@@ -510,7 +511,7 @@ Usage of the rf relation implicitly assumes that loads will always
read from a single store. It doesn't apply properly in the presence
of load-tearing, where a load obtains some of its bits from one store
and some of them from another store. Fortunately, use of READ_ONCE()
-and WRITE_ONCE() will prevent load-tearing; it's not possible to have:
+and WRITE_ONCE() will prevent load-tearing; it's not possible to have::
int x = 0;
@@ -530,7 +531,7 @@ and end up with r1 = 0x1200 (partly from x's initial value and partly
from the value stored by P0).
On the other hand, load-tearing is unavoidable when mixed-size
-accesses are used. Consider this example:
+accesses are used. Consider this example::
union {
u32 w;
@@ -612,7 +613,7 @@ requirement that every store eventually becomes visible to every CPU.)
Any reasonable memory model will include cache coherence. Indeed, our
expectation of cache coherence is so deeply ingrained that violations
of its requirements look more like hardware bugs than programming
-errors:
+errors::
int x;
@@ -628,6 +629,8 @@ write-write coherence rule: Since the store of 23 comes later in
program order, it must also come later in x's coherence order and
thus must overwrite the store of 17.
+::
+
int x = 0;
P0()
@@ -644,6 +647,8 @@ program order, so it must not read from that store but rather from one
coming earlier in the coherence order (in this case, x's initial
value).
+::
+
int x = 0;
P0()
@@ -694,7 +699,7 @@ value that R reads is overwritten (directly or indirectly) by W, or
equivalently, when R reads from a store which comes earlier than W in
the coherence order.
-For example:
+For example::
int x = 0;
@@ -721,6 +726,8 @@ relations; it is not independent. Given a read event R and a write
event W for the same location, we will have R ->fr W if and only if
the write which R reads from is co-before W. In symbols,
+::
+
(R ->fr W) := (there exists W' with W' ->rf R and W' ->co W).
@@ -907,7 +914,7 @@ whenever we have X ->rf Y or X ->co Y or X ->fr Y or X ->po-loc Y, the
X event comes before the Y event in the global ordering. The LKMM's
"coherence" axiom expresses this by requiring the union of these
relations not to have any cycles. This means it must not be possible
-to find events
+to find events::
X0 -> X1 -> X2 -> ... -> Xn -> X0,
@@ -929,7 +936,7 @@ this case) does not get altered between the read and the write events
making up the atomic operation. In particular, if two CPUs perform
atomic_inc(&x) concurrently, it must be guaranteed that the final
value of x will be the initial value plus two. We should never have
-the following sequence of events:
+the following sequence of events::
CPU 0 loads x obtaining 13;
CPU 1 loads x obtaining 13;
@@ -951,6 +958,8 @@ atomic read-modify-write and W' is the write event which R reads from,
there must not be any stores coming between W' and W in the coherence
order. Equivalently,
+::
+
(R ->rmw W) implies (there is no X with R ->fr X and X ->co W),
where the rmw relation links the read and write events making up each
@@ -1021,7 +1030,7 @@ includes address dependencies to loads in the ppo relation.
On the other hand, dependencies can indirectly affect the ordering of
two loads. This happens when there is a dependency from a load to a
-store and a second, po-later load reads from that store:
+store and a second, po-later load reads from that store::
R ->dep W ->rfi R',
@@ -1036,7 +1045,7 @@ R; if the speculation turns out to be wrong then the CPU merely has to
restart or abandon R'.
(In theory, a CPU might forward a store to a load when it runs across
-an address dependency like this:
+an address dependency like this::
r1 = READ_ONCE(ptr);
WRITE_ONCE(*r1, 17);
@@ -1048,7 +1057,7 @@ However, none of the architectures supported by the Linux kernel do
this.)
Two memory accesses of the same location must always be executed in
-program order if the second access is a store. Thus, if we have
+program order if the second access is a store. Thus, if we have::
R ->po-loc W
@@ -1056,7 +1065,7 @@ program order if the second access is a store. Thus, if we have
access the same location), the CPU is obliged to execute W after R.
If it executed W first then the memory subsystem would respond to R's
read request with the value stored by W (or an even later store), in
-violation of the read-write coherence rule. Similarly, if we had
+violation of the read-write coherence rule. Similarly, if we had::
W ->po-loc W'
@@ -1074,7 +1083,7 @@ AND THEN THERE WAS ALPHA
As mentioned above, the Alpha architecture is unique in that it does
not appear to respect address dependencies to loads. This means that
-code such as the following:
+code such as the following::
int x = 0;
int y = -1;
@@ -1128,7 +1137,7 @@ nothing at all on non-Alpha builds) after every READ_ONCE() and atomic
load. The effect of the fence is to cause the CPU not to execute any
po-later instructions until after the local cache has finished
processing all the stores it has already received. Thus, if the code
-was changed to:
+was changed to::
P1()
{
@@ -1199,7 +1208,7 @@ the first event in the coherence order and propagates to C before the
second event executes.
This is best explained with some examples. The simplest case looks
-like this:
+like this::
int x;
@@ -1225,7 +1234,7 @@ event, because P1's store came after P0's store in x's coherence
order, and P1's store propagated to P0 before P0's load executed.
An equally simple case involves two loads of the same location that
-read from different stores:
+read from different stores::
int x = 0;
@@ -1252,7 +1261,7 @@ P1's store propagated to P0 before P0's second load executed.
Less trivial examples of prop all involve fences. Unlike the simple
examples above, they can require that some instructions are executed
-out of program order. This next one should look familiar:
+out of program order. This next one should look familiar::
int buf = 0, flag = 0;
@@ -1303,7 +1312,7 @@ rfe link. You can concoct more exotic examples, containing more than
one fence, although this quickly leads to diminishing returns in terms
of complexity. For instance, here's an example containing a coe link
followed by two fences and an rfe link, utilizing the fact that
-release fences are A-cumulative:
+release fences are A-cumulative::
int x, y, z;
@@ -1363,7 +1372,7 @@ links. Let's see how this definition works out.
Consider first the case where E is a store (implying that the sequence
of links begins with coe). Then there are events W, X, Y, and Z such
-that:
+that::
E ->coe W ->cumul-fence* X ->rfe? Y ->strong-fence Z ->hb* F,
@@ -1390,7 +1399,7 @@ request with the value stored by W or an even later store,
contradicting the fact that E ->fre W.
A good example illustrating how pb works is the SB pattern with strong
-fences:
+fences::
int x = 0, y = 0;
@@ -1449,18 +1458,18 @@ span a full grace period. In more detail, the Guarantee says:
For any critical section C and any grace period G, at least
one of the following statements must hold:
-(1) C ends before G does, and in addition, every store that
- propagates to C's CPU before the end of C must propagate to
- every CPU before G ends.
+ (1) C ends before G does, and in addition, every store that
+ propagates to C's CPU before the end of C must propagate to
+ every CPU before G ends.
-(2) G starts before C does, and in addition, every store that
- propagates to G's CPU before the start of G must propagate
- to every CPU before C starts.
+ (2) G starts before C does, and in addition, every store that
+ propagates to G's CPU before the start of G must propagate
+ to every CPU before C starts.
In particular, it is not possible for a critical section to both start
before and end after a grace period.
-Here is a simple example of RCU in action:
+Here is a simple example of RCU in action::
int x, y;
@@ -1544,13 +1553,13 @@ the end of a critical section which starts before Z begins.
The LKMM goes on to define the rcu-fence relation as a sequence of
rcu-gp and rcu-rscsi links separated by rcu-link links, in which the
number of rcu-gp links is >= the number of rcu-rscsi links. For
-example:
+example::
X ->rcu-gp Y ->rcu-link Z ->rcu-rscsi T ->rcu-link U ->rcu-gp V
would imply that X ->rcu-fence V, because this sequence contains two
rcu-gp links and one rcu-rscsi link. (It also implies that
-X ->rcu-fence T and Z ->rcu-fence V.) On the other hand:
+X ->rcu-fence T and Z ->rcu-fence V.) On the other hand::
X ->rcu-rscsi Y ->rcu-link Z ->rcu-rscsi T ->rcu-link U ->rcu-gp V
@@ -1566,7 +1575,7 @@ E must execute before F; in fact, each synchronize_rcu() fence event
is linked to itself by rcu-fence as a degenerate case.)
To prove this in full generality requires some intellectual effort.
-We'll consider just a very simple case:
+We'll consider just a very simple case::
G ->rcu-gp W ->rcu-link Z ->rcu-rscsi F.
@@ -1621,7 +1630,7 @@ question, and let S be the synchronize_rcu() fence event for the grace
period. Saying that the critical section starts before S means there
are events Q and R where Q is po-after L (which marks the start of the
critical section), Q is "before" R in the sense used by the rcu-link
-relation, and R is po-before the grace period S. Thus we have:
+relation, and R is po-before the grace period S. Thus we have::
L ->rcu-link S.
@@ -1629,20 +1638,20 @@ Let W be the store mentioned above, let Y come before the end of the
critical section and witness that W propagates to the critical
section's CPU by reading from W, and let Z on some arbitrary CPU be a
witness that W has not propagated to that CPU, where Z happens after
-some event X which is po-after S. Symbolically, this amounts to:
+some event X which is po-after S. Symbolically, this amounts to::
S ->po X ->hb* Z ->fr W ->rf Y ->po U.
The fr link from Z to W indicates that W has not propagated to Z's CPU
at the time that Z executes. From this, it can be shown (see the
discussion of the rcu-link relation earlier) that S and U are related
-by rcu-link:
+by rcu-link::
S ->rcu-link U.
Since S is a grace period we have S ->rcu-gp S, and since L and U are
the start and end of the critical section C we have U ->rcu-rscsi L.
-From this we obtain:
+From this we obtain::
S ->rcu-gp S ->rcu-link U ->rcu-rscsi L ->rcu-link S,
@@ -1651,7 +1660,7 @@ the Grace Period Guarantee.
For something a little more down-to-earth, let's see how the axiom
works out in practice. Consider the RCU code example from above, this
-time with statement labels added:
+time with statement labels added::
int x, y;
@@ -1687,7 +1696,7 @@ Then U ->rcu-rscsi L ->rcu-link S ->rcu-gp S ->rcu-link U is a
forbidden cycle, violating the "rcu" axiom. Hence the outcome is not
allowed by the LKMM, as we would expect.
-For contrast, let's see what can happen in a more complicated example:
+For contrast, let's see what can happen in a more complicated example::
int x, y, z;
@@ -1726,22 +1735,22 @@ L2 ->rcu-link U0. However this cycle is not forbidden, because the
sequence of relations contains fewer instances of rcu-gp (one) than of
rcu-rscsi (two). Consequently the outcome is allowed by the LKMM.
The following instruction timing diagram shows how it might actually
-occur:
+occur::
-P0 P1 P2
--------------------- -------------------- --------------------
-rcu_read_lock()
-WRITE_ONCE(y, 1)
- r1 = READ_ONCE(y)
- synchronize_rcu() starts
- . rcu_read_lock()
- . WRITE_ONCE(x, 1)
-r0 = READ_ONCE(x) .
-rcu_read_unlock() .
- synchronize_rcu() ends
- WRITE_ONCE(z, 1)
- r2 = READ_ONCE(z)
- rcu_read_unlock()
+ P0 P1 P2
+ -------------------- -------------------- --------------------
+ rcu_read_lock()
+ WRITE_ONCE(y, 1)
+ r1 = READ_ONCE(y)
+ synchronize_rcu() starts
+ . rcu_read_lock()
+ . WRITE_ONCE(x, 1)
+ r0 = READ_ONCE(x) .
+ rcu_read_unlock() .
+ synchronize_rcu() ends
+ WRITE_ONCE(z, 1)
+ r2 = READ_ONCE(z)
+ rcu_read_unlock()
This requires P0 and P2 to execute their loads and stores out of
program order, but of course they are allowed to do so. And as you
@@ -1767,26 +1776,26 @@ The LKMM includes locking. In fact, there is special code for locking
in the formal model, added in order to make tools run faster.
However, this special code is intended to be more or less equivalent
to concepts we have already covered. A spinlock_t variable is treated
-the same as an int, and spin_lock(&s) is treated almost the same as:
+the same as an int, and spin_lock(&s) is treated almost the same as::
while (cmpxchg_acquire(&s, 0, 1) != 0)
cpu_relax();
This waits until s is equal to 0 and then atomically sets it to 1,
and the read part of the cmpxchg operation acts as an acquire fence.
-An alternate way to express the same thing would be:
+An alternate way to express the same thing would be::
r = xchg_acquire(&s, 1);
along with a requirement that at the end, r = 0. Similarly,
-spin_trylock(&s) is treated almost the same as:
+spin_trylock(&s) is treated almost the same as::
return !cmpxchg_acquire(&s, 0, 1);
which atomically sets s to 1 if it is currently equal to 0 and returns
true if it succeeds (the read part of the cmpxchg operation acts as an
acquire fence only if the operation is successful). spin_unlock(&s)
-is treated almost the same as:
+is treated almost the same as::
smp_store_release(&s, 0);
@@ -1802,7 +1811,7 @@ requires that every instruction po-before the lock-release must
execute before any instruction po-after the lock-acquire. This would
naturally hold if the release and acquire operations were on different
CPUs, but the LKMM says it holds even when they are on the same CPU.
-For example:
+For example::
int x, y;
spinlock_t s;
@@ -1833,7 +1842,7 @@ MP pattern).
This requirement does not apply to ordinary release and acquire
fences, only to lock-related operations. For instance, suppose P0()
-in the example had been written as:
+in the example had been written as::
P0()
{
@@ -1847,7 +1856,7 @@ in the example had been written as:
Then the CPU would be allowed to forward the s = 1 value from the
smp_store_release() to the smp_load_acquire(), executing the
-instructions in the following order:
+instructions in the following order::
r3 = smp_load_acquire(&s); // Obtains r3 = 1
r2 = READ_ONCE(y);
@@ -1859,7 +1868,7 @@ and thus it could load y before x, obtaining r2 = 0 and r1 = 1.
Second, when a lock-acquire reads from a lock-release, and some other
stores W and W' occur po-before the lock-release and po-after the
lock-acquire respectively, the LKMM requires that W must propagate to
-each CPU before W' does. For example, consider:
+each CPU before W' does. For example, consider::
int x, y;
spinlock_t x;
@@ -1928,7 +1937,7 @@ smp_store_release().) The final effect is the same.
Although we didn't mention it above, the instruction execution
ordering provided by the smp_rmb() fence doesn't apply to read events
that are part of a non-value-returning atomic update. For instance,
-given:
+given::
atomic_inc(&x);
smp_rmb();
@@ -1967,14 +1976,14 @@ they behave as follows:
events.
Interestingly, RCU and locking each introduce the possibility of
-deadlock. When faced with code sequences such as:
+deadlock. When faced with code sequences such as::
spin_lock(&s);
spin_lock(&s);
spin_unlock(&s);
spin_unlock(&s);
-or:
+or::
rcu_read_lock();
synchronize_rcu();
@@ -1984,7 +1993,7 @@ what does the LKMM have to say? Answer: It says there are no allowed
executions at all, which makes sense. But this can also lead to
misleading results, because if a piece of code has multiple possible
executions, some of which deadlock, the model will report only on the
-non-deadlocking executions. For example:
+non-deadlocking executions. For example::
int x, y;
diff --git a/tools/memory-model/Documentation/index.rst b/tools/memory-model/Documentation/index.rst
new file mode 100644
index 000000000000..0e53d83a5a48
--- /dev/null
+++ b/tools/memory-model/Documentation/index.rst
@@ -0,0 +1,20 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+========================
+Linux Memory Model Tools
+========================
+
+.. toctree::
+ :maxdepth: 1
+
+ explanation
+ recipes
+ references
+ cheatsheet
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/tools/memory-model/Documentation/recipes.txt b/tools/memory-model/Documentation/recipes.rst
similarity index 96%
rename from tools/memory-model/Documentation/recipes.txt
rename to tools/memory-model/Documentation/recipes.rst
index 7fe8d7aa3029..0229a431b1a2 100644
--- a/tools/memory-model/Documentation/recipes.txt
+++ b/tools/memory-model/Documentation/recipes.rst
@@ -1,3 +1,8 @@
+=======
+Recipes
+=======
+
+
This document provides "recipes", that is, litmus tests for commonly
occurring situations, as well as a few that illustrate subtly broken but
attractive nuisances. Many of these recipes include example code from
@@ -67,7 +72,7 @@ has acquired a given lock sees any changes previously seen or made by any
CPU before it released that same lock. Note that this statement is a bit
stronger than "Any CPU holding a given lock sees all changes made by any
CPU during the time that CPU was holding this same lock". For example,
-consider the following pair of code fragments:
+consider the following pair of code fragments::
/* See MP+polocks.litmus. */
void CPU0(void)
@@ -93,7 +98,7 @@ value of r1 must also be equal to 1. In contrast, the weaker rule would
say nothing about the final value of r1.
The converse to the basic rule also holds, as illustrated by the
-following litmus test:
+following litmus test::
/* See MP+porevlocks.litmus. */
void CPU0(void)
@@ -124,7 +129,7 @@ across multiple CPUs.
However, it is not necessarily the case that accesses ordered by
locking will be seen as ordered by CPUs not holding that lock.
-Consider this example:
+Consider this example::
/* See Z6.0+pooncerelease+poacquirerelease+fencembonceonce.litmus. */
void CPU0(void)
@@ -157,7 +162,7 @@ CPU2() never acquired the lock, and thus did not benefit from the
lock's ordering properties.
Ordering can be extended to CPUs not holding the lock by careful use
-of smp_mb__after_spinlock():
+of smp_mb__after_spinlock()::
/* See Z6.0+pooncelock+poonceLock+pombonce.litmus. */
void CPU0(void)
@@ -214,7 +219,7 @@ Release and acquire
~~~~~~~~~~~~~~~~~~~
Use of smp_store_release() and smp_load_acquire() is one way to force
-the desired MP ordering. The general approach is shown below:
+the desired MP ordering. The general approach is shown below::
/* See MP+pooncerelease+poacquireonce.litmus. */
void CPU0(void)
@@ -245,7 +250,7 @@ Assign and dereference
Use of rcu_assign_pointer() and rcu_dereference() is quite similar to the
use of smp_store_release() and smp_load_acquire(), except that both
rcu_assign_pointer() and rcu_dereference() operate on RCU-protected
-pointers. The general approach is shown below:
+pointers. The general approach is shown below::
/* See MP+onceassign+derefonce.litmus. */
int z;
@@ -290,7 +295,7 @@ Write and read memory barriers
It is usually better to use smp_store_release() instead of smp_wmb()
and to use smp_load_acquire() instead of smp_rmb(). However, the older
smp_wmb() and smp_rmb() APIs are still heavily used, so it is important
-to understand their use cases. The general approach is shown below:
+to understand their use cases. The general approach is shown below::
/* See MP+fencewmbonceonce+fencermbonceonce.litmus. */
void CPU0(void)
@@ -312,7 +317,7 @@ smp_rmb() macro orders prior loads against later loads. Therefore, if
the final value of r0 is 1, the final value of r1 must also be 1.
The xlog_state_switch_iclogs() function in fs/xfs/xfs_log.c contains
-the following write-side code fragment:
+the following write-side code fragment::
log->l_curr_block -= log->l_logBBsize;
ASSERT(log->l_curr_block >= 0);
@@ -327,7 +332,7 @@ the corresponding read-side code fragment:
cur_block = READ_ONCE(log->l_curr_block);
Alternatively, consider the following comment in function
-perf_output_put_handle() in kernel/events/ring_buffer.c:
+perf_output_put_handle() in kernel/events/ring_buffer.c::
* kernel user
*
@@ -358,7 +363,7 @@ absence of any ordering it is quite possible that this may happen, as
can be seen in the LB+poonceonces.litmus litmus test.
One way of avoiding the counter-intuitive outcome is through the use of a
-control dependency paired with a full memory barrier:
+control dependency paired with a full memory barrier::
/* See LB+fencembonceonce+ctrlonceonce.litmus. */
void CPU0(void)
@@ -382,7 +387,7 @@ The A/D pairing from the ring-buffer use case shown earlier also
illustrates LB. Here is a repeat of the comment in
perf_output_put_handle() in kernel/events/ring_buffer.c, showing a
control dependency on the kernel side and a full memory barrier on
-the user side:
+the user side::
* kernel user
*
@@ -407,7 +412,7 @@ Release-acquire chains
Release-acquire chains are a low-overhead, flexible, and easy-to-use
method of maintaining order. However, they do have some limitations that
-need to be fully understood. Here is an example that maintains order:
+need to be fully understood. Here is an example that maintains order::
/* See ISA2+pooncerelease+poacquirerelease+poacquireonce.litmus. */
void CPU0(void)
@@ -436,7 +441,7 @@ example, ordering would still be preserved if CPU1()'s smp_load_acquire()
invocation was replaced with READ_ONCE().
It is tempting to assume that CPU0()'s store to x is globally ordered
-before CPU1()'s store to z, but this is not the case:
+before CPU1()'s store to z, but this is not the case::
/* See Z6.0+pooncerelease+poacquirerelease+mbonceonce.litmus. */
void CPU0(void)
@@ -474,7 +479,7 @@ Store buffering
Store buffering can be thought of as upside-down load buffering, so
that one CPU first stores to one variable and then loads from a second,
while another CPU stores to the second variable and then loads from the
-first. Preserving order requires nothing less than full barriers:
+first. Preserving order requires nothing less than full barriers::
/* See SB+fencembonceonces.litmus. */
void CPU0(void)
@@ -498,7 +503,7 @@ this counter-intuitive outcome.
This pattern most famously appears as part of Dekker's locking
algorithm, but it has a much more practical use within the Linux kernel
of ordering wakeups. The following comment taken from waitqueue_active()
-in include/linux/wait.h shows the canonical pattern:
+in include/linux/wait.h shows the canonical pattern::
* CPU0 - waker CPU1 - waiter
*
@@ -550,16 +555,16 @@ The strength of memory ordering required for a given litmus test to
avoid a counter-intuitive outcome depends on the types of relations
linking the memory accesses for the outcome in question:
-o If all links are write-to-read links, then the weakest
+- If all links are write-to-read links, then the weakest
possible ordering within each CPU suffices. For example, in
the LB litmus test, a control dependency was enough to do the
job.
-o If all but one of the links are write-to-read links, then a
+- If all but one of the links are write-to-read links, then a
release-acquire chain suffices. Both the MP and the ISA2
litmus tests illustrate this case.
-o If more than one of the links are something other than
+- If more than one of the links are something other than
write-to-read links, then a full memory barrier is required
between each successive pair of non-write-to-read links. This
case is illustrated by the Z6.0 litmus tests, both in the
diff --git a/tools/memory-model/Documentation/references.txt b/tools/memory-model/Documentation/references.rst
similarity index 71%
rename from tools/memory-model/Documentation/references.txt
rename to tools/memory-model/Documentation/references.rst
index b177f3e4a614..275876cd10b8 100644
--- a/tools/memory-model/Documentation/references.txt
+++ b/tools/memory-model/Documentation/references.rst
@@ -1,3 +1,7 @@
+==========
+References
+==========
+
This document provides background reading for memory models and related
tools. These documents are aimed at kernel hackers who are interested
in memory models.
@@ -6,64 +10,64 @@ in memory models.
Hardware manuals and models
===========================
-o SPARC International Inc. (Ed.). 1994. "The SPARC Architecture
+- SPARC International Inc. (Ed.). 1994. "The SPARC Architecture
Reference Manual Version 9". SPARC International Inc.
-o Compaq Computer Corporation (Ed.). 2002. "Alpha Architecture
+- Compaq Computer Corporation (Ed.). 2002. "Alpha Architecture
Reference Manual". Compaq Computer Corporation.
-o Intel Corporation (Ed.). 2002. "A Formal Specification of Intel
+- Intel Corporation (Ed.). 2002. "A Formal Specification of Intel
Itanium Processor Family Memory Ordering". Intel Corporation.
-o Intel Corporation (Ed.). 2002. "Intel 64 and IA-32 Architectures
+- Intel Corporation (Ed.). 2002. "Intel 64 and IA-32 Architectures
Software Developer’s Manual". Intel Corporation.
-o Peter Sewell, Susmit Sarkar, Scott Owens, Francesco Zappa Nardelli,
+- Peter Sewell, Susmit Sarkar, Scott Owens, Francesco Zappa Nardelli,
and Magnus O. Myreen. 2010. "x86-TSO: A Rigorous and Usable
Programmer's Model for x86 Multiprocessors". Commun. ACM 53, 7
(July, 2010), 89-97. http://doi.acm.org/10.1145/1785414.1785443
-o IBM Corporation (Ed.). 2009. "Power ISA Version 2.06". IBM
+- IBM Corporation (Ed.). 2009. "Power ISA Version 2.06". IBM
Corporation.
-o ARM Ltd. (Ed.). 2009. "ARM Barrier Litmus Tests and Cookbook".
+- ARM Ltd. (Ed.). 2009. "ARM Barrier Litmus Tests and Cookbook".
ARM Ltd.
-o Susmit Sarkar, Peter Sewell, Jade Alglave, Luc Maranget, and
+- Susmit Sarkar, Peter Sewell, Jade Alglave, Luc Maranget, and
Derek Williams. 2011. "Understanding POWER Multiprocessors". In
Proceedings of the 32Nd ACM SIGPLAN Conference on Programming
Language Design and Implementation (PLDI ’11). ACM, New York,
NY, USA, 175–186.
-o Susmit Sarkar, Kayvan Memarian, Scott Owens, Mark Batty,
+- Susmit Sarkar, Kayvan Memarian, Scott Owens, Mark Batty,
Peter Sewell, Luc Maranget, Jade Alglave, and Derek Williams.
2012. "Synchronising C/C++ and POWER". In Proceedings of the 33rd
ACM SIGPLAN Conference on Programming Language Design and
Implementation (PLDI '12). ACM, New York, NY, USA, 311-322.
-o ARM Ltd. (Ed.). 2014. "ARM Architecture Reference Manual (ARMv8,
+- ARM Ltd. (Ed.). 2014. "ARM Architecture Reference Manual (ARMv8,
for ARMv8-A architecture profile)". ARM Ltd.
-o Imagination Technologies, LTD. 2015. "MIPS(R) Architecture
+- Imagination Technologies, LTD. 2015. "MIPS(R) Architecture
For Programmers, Volume II-A: The MIPS64(R) Instruction,
Set Reference Manual". Imagination Technologies,
LTD. https://imgtec.com/?do-download=4302.
-o Shaked Flur, Kathryn E. Gray, Christopher Pulte, Susmit
+- Shaked Flur, Kathryn E. Gray, Christopher Pulte, Susmit
Sarkar, Ali Sezgin, Luc Maranget, Will Deacon, and Peter
Sewell. 2016. "Modelling the ARMv8 Architecture, Operationally:
Concurrency and ISA". In Proceedings of the 43rd Annual ACM
SIGPLAN-SIGACT Symposium on Principles of Programming Languages
(POPL ’16). ACM, New York, NY, USA, 608–621.
-o Shaked Flur, Susmit Sarkar, Christopher Pulte, Kyndylan Nienhuis,
+- Shaked Flur, Susmit Sarkar, Christopher Pulte, Kyndylan Nienhuis,
Luc Maranget, Kathryn E. Gray, Ali Sezgin, Mark Batty, and Peter
Sewell. 2017. "Mixed-size Concurrency: ARM, POWER, C/C++11,
and SC". In Proceedings of the 44th ACM SIGPLAN Symposium on
Principles of Programming Languages (POPL 2017). ACM, New York,
NY, USA, 429–442.
-o Christopher Pulte, Shaked Flur, Will Deacon, Jon French,
+- Christopher Pulte, Shaked Flur, Will Deacon, Jon French,
Susmit Sarkar, and Peter Sewell. 2018. "Simplifying ARM concurrency:
multicopy-atomic axiomatic and operational models for ARMv8". In
Proceedings of the ACM on Programming Languages, Volume 2, Issue
@@ -73,18 +77,18 @@ o Christopher Pulte, Shaked Flur, Will Deacon, Jon French,
Linux-kernel memory model
=========================
-o Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
+- Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
Alan Stern. 2018. "Frightening small children and disconcerting
grown-ups: Concurrency in the Linux kernel". In Proceedings of
the 23rd International Conference on Architectural Support for
Programming Languages and Operating Systems (ASPLOS 2018). ACM,
New York, NY, USA, 405-418. Webpage: http://diy.inria.fr/linux/.
-o Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
+- Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
Alan Stern. 2017. "A formal kernel memory-ordering model (part 1)"
Linux Weekly News. https://lwn.net/Articles/718628/
-o Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
+- Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
Alan Stern. 2017. "A formal kernel memory-ordering model (part 2)"
Linux Weekly News. https://lwn.net/Articles/720550/
@@ -92,16 +96,16 @@ o Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
Memory-model tooling
====================
-o Daniel Jackson. 2002. "Alloy: A Lightweight Object Modelling
+- Daniel Jackson. 2002. "Alloy: A Lightweight Object Modelling
Notation". ACM Trans. Softw. Eng. Methodol. 11, 2 (April 2002),
256–290. http://doi.acm.org/10.1145/505145.505149
-o Jade Alglave, Luc Maranget, and Michael Tautschnig. 2014. "Herding
+- Jade Alglave, Luc Maranget, and Michael Tautschnig. 2014. "Herding
Cats: Modelling, Simulation, Testing, and Data Mining for Weak
Memory". ACM Trans. Program. Lang. Syst. 36, 2, Article 7 (July
2014), 7:1–7:74 pages.
-o Jade Alglave, Patrick Cousot, and Luc Maranget. 2016. "Syntax and
+- Jade Alglave, Patrick Cousot, and Luc Maranget. 2016. "Syntax and
semantics of the weak consistency model specification language
cat". CoRR abs/1608.07531 (2016). http://arxiv.org/abs/1608.07531
@@ -109,6 +113,6 @@ o Jade Alglave, Patrick Cousot, and Luc Maranget. 2016. "Syntax and
Memory-model comparisons
========================
-o Paul E. McKenney, Ulrich Weigand, Andrea Parri, and Boqun
+- Paul E. McKenney, Ulrich Weigand, Andrea Parri, and Boqun
Feng. 2016. "Linux-Kernel Memory Model". (6 June 2016).
http://open-std.org/JTC1/SC22/WG21/docs/papers/2016/p0124r2.html.
diff --git a/tools/memory-model/README b/tools/memory-model/README
index 2b87f3971548..04bb1fa9ed76 100644
--- a/tools/memory-model/README
+++ b/tools/memory-model/README
@@ -105,16 +105,16 @@ for more information.
DESCRIPTION OF FILES
====================
-Documentation/cheatsheet.txt
+Documentation/cheatsheet.rst
Quick-reference guide to the Linux-kernel memory model.
-Documentation/explanation.txt
+Documentation/explanation.rst
Describes the memory model in detail.
-Documentation/recipes.txt
+Documentation/recipes.rst
Lists common memory-ordering patterns.
-Documentation/references.txt
+Documentation/references.rst
Provides background reading.
linux-kernel.bell
@@ -173,7 +173,7 @@ The Linux-kernel memory model has the following limitations:
of READ_ONCE() and WRITE_ONCE() limits the compiler's ability
to optimize, but there is Linux-kernel code that uses bare C
memory accesses. Handling this code is on the to-do list.
- For more information, see Documentation/explanation.txt (in
+ For more information, see Documentation/explanation.rst (in
particular, the "THE PROGRAM ORDER RELATION: po AND po-loc"
and "A WARNING" sections).
--
2.21.0
^ permalink raw reply related
* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
From: Mauro Carvalho Chehab @ 2019-07-26 18:45 UTC (permalink / raw)
To: Joel Fernandes
Cc: Paul E. McKenney, Josh Triplett, Steven Rostedt,
Mathieu Desnoyers, Lai Jiangshan, Jonathan Corbet, rcu, linux-doc
In-Reply-To: <20190726175527.GD146401@google.com>
Em Fri, 26 Jul 2019 13:55:27 -0400
Joel Fernandes <joel@joelfernandes.org> escreveu:
> On Fri, Jul 26, 2019 at 02:00:28PM -0300, Mauro Carvalho Chehab wrote:
> > Hi Joel,
> >
> > Em Fri, 26 Jul 2019 12:20:02 -0400
> > Joel Fernandes <joel@joelfernandes.org> escreveu:
> >
> > > On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> > > > There are 4 RCU articles that are written on html format.
> > > >
> > > Could you list what were the "some broken things" that you had to manually
> > > fix to make reviewing easier?
> >
> > There are a couple of things.
> >
> > At least the pandoc's version I used here has a bug: its conversion
> > from html to ReST on those files only start after a <body> tag - or
> > when the first quiz table starts. I only discovered that adding a
> > <body> at the beginning of the file solve this book at the last
> > conversions.
> >
> > So, for most html->ReST conversions, I manually converted the first
> > part of the document, basically stripping html paragraph tags and
> > by replacing highlights by the ReST syntax.
> >
> > Also, all the quiz tables seem to assume some javascript macro or
> > css style that would be hiding the answer part until the mouse moves
> > to it. Such macro/css was not there at the kernel tree. So, the quiz
> > answers have the same color as the background, making them invisible.
> > Even if we had such macro/css, this is not portable for pdf/LaTeX output
> > (and I'm not sure if this would work with ePub).
> >
> > So, I ended by manually doing the table conversion.
> >
> > Finally, I double-checked if the conversions ended ok, addressing any
> > issues that might have heppened.
> >
> > So, after both automatic conversion and manual fixes, I opened both the
> > html files produced by Sphinx and the original ones and compared them
> > line per line (except for the indexes, as Sphinx produces them
> > automatically), in order to see if all information from the original
> > files will be there on a format close to what we have on other ReST
> > files, fixing any pending issues if any.
>
> Thanks, I am in the process of going through these docs today and will let
> you know anything I find. It would be nice to include the above challenges in
> the changelog as well.
Ok, will add on a next spin - or if you prefer to pick via your tree - feel
free to add them.
> Some reason 'make htmldocs' needed me to install a whole bunch of
> dependencies this time around.
Yes, you need Sphinx, plus some LaTeX stuff - not only for PDF but
also due to some math expressions found on some books.
Just installing Sphinx + its dependencies is enough for this specific
book.
> By the way, that tools/memory-model/Documentation/explanation.txt is a useful
> little document. Well not really little with over 1000 lines ;-). But it
> would certainly benefit from ReST's / htmldocs ability to jump to labels and
> search, etc since it is so long..
tools/*/Documentation is currently out of the current docs build system.
Maybe if you pass SPHINXDIRS=../tools/memory-model/Documentation/ it
could allow you to build something out there.
Btw, did a quick hack here, just for testing:
$ ln -sf ../tools/memory-model/Documentation/ Documentation/tools
$ cp tools/memory-model/Documentation/explanation.txt tools/memory-model/Documentation/explanation.rst
Sphinx tried to build explanation.txt:
/devel/v4l/docs_temp/Documentation/tools/explanation.rst:116: WARNING: Unexpected indentation.
/devel/v4l/docs_temp/Documentation/tools/explanation.rst:118: WARNING: Block quote ends without a blank line; unexpected unindent.
/devel/v4l/docs_temp/Documentation/tools/explanation.rst:122: WARNING: Unexpected indentation.
/devel/v4l/docs_temp/Documentation/tools/explanation.rst:127: WARNING: Unexpected indentation.
/devel/v4l/docs_temp/Documentation/tools/explanation.rst:128: WARNING: Block quote ends without a blank line; unexpected unindent.
/devel/v4l/docs_temp/Documentation/tools/explanation.rst:228: WARNING: Unexpected indentation.
...
So, it shouldn't be too hard to add it, but some adjustments will
be needed, specially at the code blocks.
Btw, if you want to play with it, the enclosing patch should give you
a good start.
As there aren't many files there, I suspect that converting them to
ReST should not be hard.
Thanks,
Mauro
[PATCH RFC] tools/memory-model: add it to the Documentation body
Add the cheatsheet file to the Documentation body.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 0a564f3c336e..03ff920ac1cb 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -36,6 +36,7 @@ trying to get it to work optimally on a given system.
admin-guide/index
kbuild/index
+ tools/index
Firmware-related documentation
------------------------------
diff --git a/Documentation/tools/memory-model b/Documentation/tools/memory-model
new file mode 120000
index 000000000000..020ed38ce302
--- /dev/null
+++ b/Documentation/tools/memory-model
@@ -0,0 +1 @@
+../../tools/memory-model/Documentation/
\ No newline at end of file
diff --git a/tools/memory-model/Documentation/cheatsheet.rst b/tools/memory-model/Documentation/cheatsheet.rst
new file mode 100644
index 000000000000..35f8749b8a53
--- /dev/null
+++ b/tools/memory-model/Documentation/cheatsheet.rst
@@ -0,0 +1,36 @@
+===========
+Cheat Sheet
+===========
+
+::
+
+ Prior Operation Subsequent Operation
+ --------------- ---------------------------
+ C Self R W RMW Self R W DR DW RMW SV
+ -- ---- - - --- ---- - - -- -- --- --
+
+ Store, e.g., WRITE_ONCE() Y Y
+ Load, e.g., READ_ONCE() Y Y Y Y
+ Unsuccessful RMW operation Y Y Y Y
+ rcu_dereference() Y Y Y Y
+ Successful *_acquire() R Y Y Y Y Y Y
+ Successful *_release() C Y Y Y W Y
+ smp_rmb() Y R Y Y R
+ smp_wmb() Y W Y Y W
+ smp_mb() & synchronize_rcu() CP Y Y Y Y Y Y Y Y
+ Successful full non-void RMW CP Y Y Y Y Y Y Y Y Y Y Y
+ smp_mb__before_atomic() CP Y Y Y a a a a Y
+ smp_mb__after_atomic() CP a a Y Y Y Y Y Y
+
+
+ Key: C: Ordering is cumulative
+ P: Ordering propagates
+ R: Read, for example, READ_ONCE(), or read portion of RMW
+ W: Write, for example, WRITE_ONCE(), or write portion of RMW
+ Y: Provides ordering
+ a: Provides ordering given intervening RMW atomic operation
+ DR: Dependent read (address dependency)
+ DW: Dependent write (address, data, or control dependency)
+ RMW: Atomic read-modify-write operation
+ SELF: Orders self, as opposed to accesses before and/or after
+ SV: Orders later accesses to the same variable
diff --git a/tools/memory-model/Documentation/cheatsheet.txt b/tools/memory-model/Documentation/cheatsheet.txt
deleted file mode 100644
index 33ba98d72b16..000000000000
--- a/tools/memory-model/Documentation/cheatsheet.txt
+++ /dev/null
@@ -1,30 +0,0 @@
- Prior Operation Subsequent Operation
- --------------- ---------------------------
- C Self R W RMW Self R W DR DW RMW SV
- -- ---- - - --- ---- - - -- -- --- --
-
-Store, e.g., WRITE_ONCE() Y Y
-Load, e.g., READ_ONCE() Y Y Y Y
-Unsuccessful RMW operation Y Y Y Y
-rcu_dereference() Y Y Y Y
-Successful *_acquire() R Y Y Y Y Y Y
-Successful *_release() C Y Y Y W Y
-smp_rmb() Y R Y Y R
-smp_wmb() Y W Y Y W
-smp_mb() & synchronize_rcu() CP Y Y Y Y Y Y Y Y
-Successful full non-void RMW CP Y Y Y Y Y Y Y Y Y Y Y
-smp_mb__before_atomic() CP Y Y Y a a a a Y
-smp_mb__after_atomic() CP a a Y Y Y Y Y Y
-
-
-Key: C: Ordering is cumulative
- P: Ordering propagates
- R: Read, for example, READ_ONCE(), or read portion of RMW
- W: Write, for example, WRITE_ONCE(), or write portion of RMW
- Y: Provides ordering
- a: Provides ordering given intervening RMW atomic operation
- DR: Dependent read (address dependency)
- DW: Dependent write (address, data, or control dependency)
- RMW: Atomic read-modify-write operation
- SELF: Orders self, as opposed to accesses before and/or after
- SV: Orders later accesses to the same variable
diff --git a/tools/memory-model/Documentation/index.rst b/tools/memory-model/Documentation/index.rst
new file mode 100644
index 000000000000..23caee7a96cc
--- /dev/null
+++ b/tools/memory-model/Documentation/index.rst
@@ -0,0 +1,17 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========
+Linux Tools
+===========
+
+.. toctree::
+ :maxdepth: 1
+
+ cheatsheet
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
^ permalink raw reply related
* Re: [GIT PULL] Documentation fixes for 5.3
From: pr-tracker-bot @ 2019-07-26 18:35 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: Linus Torvalds, LKML, linux-doc, Mauro Carvalho Chehab
In-Reply-To: <20190726082125.0c8467e9@lwn.net>
The pull request you sent on Fri, 26 Jul 2019 08:21:25 -0600:
> git://git.lwn.net/linux.git tags/docs-5.3-1
has been merged into torvalds/linux.git:
https://git.kernel.org/torvalds/c/3ea54d9b0d655dab5b5becc7d6456082089fc166
Thank you!
--
Deet-doot-dot, I am a bot.
https://korg.wiki.kernel.org/userdoc/prtracker
^ permalink raw reply
* Re: [PATCH v10 3/5] overlayfs: add __get xattr method
From: Mark Salyzyn @ 2019-07-26 18:30 UTC (permalink / raw)
To: Amir Goldstein
Cc: linux-kernel, kernel-team, Miklos Szeredi, Jonathan Corbet,
Vivek Goyal, Eric W . Biederman, Randy Dunlap, Stephen Smalley,
overlayfs, linux-doc
In-Reply-To: <CAOQ4uxg8k=4D5_VEBy61PwBo+2pCCakUPw3uCar2oQpi3yaLmA@mail.gmail.com>
On 7/25/19 10:04 PM, Amir Goldstein wrote:
> On Thu, Jul 25, 2019 at 7:22 PM Mark Salyzyn <salyzyn@android.com> wrote:
>> On 7/25/19 8:43 AM, Amir Goldstein wrote:
>>> On Thu, Jul 25, 2019 at 6:03 PM Mark Salyzyn <salyzyn@android.com> wrote:
>>>> On 7/24/19 10:48 PM, Amir Goldstein wrote:
>>>>> On Wed, Jul 24, 2019 at 10:57 PM Mark Salyzyn <salyzyn@android.com> wrote:
>>>>>> Because of the overlayfs getxattr recursion, the incoming inode fails
>>>>>> to update the selinux sid resulting in avc denials being reported
>>>>>> against a target context of u:object_r:unlabeled:s0.
>>>>> This description is too brief for me to understand the root problem.
>>>>> What's wring with the overlayfs getxattr recursion w.r.t the selinux
>>>>> security model?
>>>> __vfs_getxattr (the way the security layer acquires the target sid
>>>> without recursing back to security to check the access permissions)
>>>> calls get xattr method, which in overlayfs calls vfs_getxattr on the
>>>> lower layer (which then recurses back to security to check permissions)
>>>> and reports back -EACCES if there was a denial (which is OK) and _no_
>>>> sid copied to caller's inode security data, bubbles back to the security
>>>> layer caller, which reports an invalid avc: message for
>>>> u:object_r:unlabeled:s0 (the uninitialized sid instead of the sid for
>>>> the lower filesystem target). The blocked access is 100% valid, it is
>>>> supposed to be blocked. This does however result in a cosmetic issue
>>>> that makes it impossible to use audit2allow to construct a rule that
>>>> would be usable to fix the access problem.
>>>>
>>> Ahhh you are talking about getting the security.selinux.* xattrs?
>>> I was under the impression (Vivek please correct me if I wrong)
>>> that overlayfs objects cannot have individual security labels and
>> They can, and we _need_ them for Android's use cases, upper and lower
>> filesystems.
>>
>> Some (most?) union filesystems (like Android's sdcardfs) set sepolicy
>> from the mount options, we did not need this adjustment there of course.
>>
>>> the only way to label overlayfs objects is by mount options on the
>>> entire mount? Or is this just for lower layer objects?
>>>
>>> Anyway, the API I would go for is adding a @flags argument to
>>> get() which can take XATTR_NOSECURITY akin to
>>> FMODE_NONOTIFY, GFP_NOFS, meant to avoid recursions.
>> I do like it better (with the following 7 stages of grief below), best
>> for the future.
>>
>> The change in this handler's API will affect all filesystem drivers
>> (well, my change affects the ABI, so it is not as-if I saved the world
>> from a module recompile) touching all filesystem sources with an even
>> larger audience of stakeholders. Larger audience of stakeholders, the
>> harder to get the change in ;-/. This is also concerning since I would
>> like this change to go to stable 4.4, 4.9, 4.14 and 4.19 where this
>> regression got introduced. I can either craft specific stable patches or
>> just let it go and deal with them in the android-common distributions
>> rather than seeking stable merged down. ABI/API breaks are a problem for
>> stable anyway ...
>>
> Use the memalloc_nofs_save/restore design pattern will avoid all that
> grief.
> As a matter of fact, this issue could and should be handled inside security
> subsystem without bothering any other subsystem.
> LSM have per task context right? That context could carry the recursion
> flags to know that the getxattr call is made by the security subsystem itself.
> The problem is not limited to union filesystems.
> In general its a stacking issue. ecryptfs is also a stacking fs, out-of-tree
> shiftfs as well. But it doesn't end there.
> A filesystem on top of a loop device inside another filesystem could
> also maybe result in security hook recursion (not sure if in practice).
>
> Thanks,
> Amir.
Good point, back to Stephen Smalley?
There are four __vfs_getxattr calls inside security, not sure I see any
natural way to determine the recursion in security/selinux I can
beg/borrow/steal from; but I get the strange feeling that it is better
to detect recursion in __vfs_getxattr in this manner, and switch out
checking in vfs_getxattr since it is localized to just fs/xattr.c.
selinux might not be the only user of __vfs_getxattr nature ...
I have implemented and tested the solution where we add a flag to the
.get method, it works. I would be tempted to submit that instead in case
someone in the future can imagine using that flag argument to solve
other problem(s) (if you build it, they will come).
<flips coin>
Will add a new per-process flag that __vfs_getxattr and vfs_getxattr
plays with and see how it works and what it looks like.
Sincerely -- Mark Salyzyn
^ permalink raw reply
* Re: [PATCH v6 1/1] sched/fair: Fix low cpu usage with high throttling by removing expiration of cpu-local slices
From: Peter Zijlstra @ 2019-07-26 18:14 UTC (permalink / raw)
To: Phil Auld
Cc: Dave Chiluk, Ben Segall, Peter Oskolkov, Ingo Molnar, cgroups,
linux-kernel, Brendan Gregg, Kyle Anderson, Gabriel Munos,
John Hammond, Cong Wang, Jonathan Corbet, linux-doc
In-Reply-To: <20190723171307.GC2947@lorien.usersys.redhat.com>
On Tue, Jul 23, 2019 at 01:13:09PM -0400, Phil Auld wrote:
> Hi Dave,
>
> On Tue, Jul 23, 2019 at 11:44:26AM -0500 Dave Chiluk wrote:
> > It has been observed, that highly-threaded, non-cpu-bound applications
> > running under cpu.cfs_quota_us constraints can hit a high percentage of
> > periods throttled while simultaneously not consuming the allocated
> > amount of quota. This use case is typical of user-interactive non-cpu
> > bound applications, such as those running in kubernetes or mesos when
> > run on multiple cpu cores.
> >
> > This has been root caused to cpu-local run queue being allocated per cpu
> > bandwidth slices, and then not fully using that slice within the period.
> > At which point the slice and quota expires. This expiration of unused
> > slice results in applications not being able to utilize the quota for
> > which they are allocated.
> >
> > The non-expiration of per-cpu slices was recently fixed by
> > 'commit 512ac999d275 ("sched/fair: Fix bandwidth timer clock drift
> > condition")'. Prior to that it appears that this had been broken since
> > at least 'commit 51f2176d74ac ("sched/fair: Fix unlocked reads of some
> > cfs_b->quota/period")' which was introduced in v3.16-rc1 in 2014. That
> > added the following conditional which resulted in slices never being
> > expired.
> >
> > if (cfs_rq->runtime_expires != cfs_b->runtime_expires) {
> > /* extend local deadline, drift is bounded above by 2 ticks */
> > cfs_rq->runtime_expires += TICK_NSEC;
> >
> > Because this was broken for nearly 5 years, and has recently been fixed
> > and is now being noticed by many users running kubernetes
> > (https://github.com/kubernetes/kubernetes/issues/67577) it is my opinion
> > that the mechanisms around expiring runtime should be removed
> > altogether.
> >
> > This allows quota already allocated to per-cpu run-queues to live longer
> > than the period boundary. This allows threads on runqueues that do not
> > use much CPU to continue to use their remaining slice over a longer
> > period of time than cpu.cfs_period_us. However, this helps prevent the
> > above condition of hitting throttling while also not fully utilizing
> > your cpu quota.
> >
> > This theoretically allows a machine to use slightly more than its
> > allotted quota in some periods. This overflow would be bounded by the
> > remaining quota left on each per-cpu runqueueu. This is typically no
> > more than min_cfs_rq_runtime=1ms per cpu. For CPU bound tasks this will
> > change nothing, as they should theoretically fully utilize all of their
> > quota in each period. For user-interactive tasks as described above this
> > provides a much better user/application experience as their cpu
> > utilization will more closely match the amount they requested when they
> > hit throttling. This means that cpu limits no longer strictly apply per
> > period for non-cpu bound applications, but that they are still accurate
> > over longer timeframes.
> >
> > This greatly improves performance of high-thread-count, non-cpu bound
> > applications with low cfs_quota_us allocation on high-core-count
> > machines. In the case of an artificial testcase (10ms/100ms of quota on
> > 80 CPU machine), this commit resulted in almost 30x performance
> > improvement, while still maintaining correct cpu quota restrictions.
> > That testcase is available at https://github.com/indeedeng/fibtest.
> >
> > Fixes: 512ac999d275 ("sched/fair: Fix bandwidth timer clock drift condition")
> > Signed-off-by: Dave Chiluk <chiluk+linux@indeed.com>
> > Reviewed-by: Ben Segall <bsegall@google.com>
>
> This still works for me. The documentation reads pretty well, too. Good job.
>
> Feel free to add my Acked-by: or Reviewed-by: Phil Auld <pauld@redhat.com>.
Thanks guys!
^ permalink raw reply
* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
From: Joel Fernandes @ 2019-07-26 18:02 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Paul E. McKenney, Josh Triplett, Steven Rostedt,
Mathieu Desnoyers, Lai Jiangshan, Jonathan Corbet, rcu, linux-doc
In-Reply-To: <8444797277eea7be474f40625bb190775a9cee33.1564145354.git.mchehab+samsung@kernel.org>
On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
[snip]
> +| until the assignment to ``gp``, by which time both fields are fully |
> +| initialized. So reordering the assignments to ``p->a`` and ``p->b`` |
> +| cannot possibly cause any problems. |
> ++-----------------------------------------------------------------------+
> +
> +It is tempting to assume that the reader need not do anything special to
> +control its accesses to the RCU-protected data, as shown in
> +``do_something_gp_buggy()`` below:
> +
> + ::
> +
> + 1 bool do_something_gp_buggy(void)
> + 2 {
> + 3 rcu_read_lock();
> + 4 p = gp; /* OPTIMIZATIONS GALORE!!! */
> + 5 if (p) {
> + 6 do_something(p->a, p->b);
> + 7 rcu_read_unlock();
> + 8 return true;
> + 9 }
> + 10 rcu_read_unlock();
> + 11 return false;
> + 12 }
> +
> +However, this temptation must be resisted because there are a
> +surprisingly large number of ways that the compiler (to say nothing of
> +`DEC Alpha CPUs <https://h71000.www7.hp.com/wizard/wiz_2637.html>`__)
> +can trip this code up. For but one example, if the compiler were short
> +of registers, it might choose to refetch from ``gp`` rather than keeping
> +a separate copy in ``p`` as follows:
> +
> + ::
> +
> + 1 bool do_something_gp_buggy_optimized(void)
> + 2 {
> + 3 rcu_read_lock();
> + 4 if (gp) { /* OPTIMIZATIONS GALORE!!! */
> + 5 do_something(gp->a, gp->b);
> + 6 rcu_read_unlock();
> + 7 return true;
> + 8 }
> + 9 rcu_read_unlock();
> + 10 return false;
> + 11 }
> +
> +If this function ran concurrently with a series of updates that replaced
> +the current structure with a new one, the fetches of ``gp->a`` and
> +``gp->b`` might well come from two different structures, which could
> +cause serious confusion. To prevent this (and much else besides),
> +``do_something_gp()`` uses ``rcu_dereference()`` to fetch from ``gp``:
> +
> + ::
> +
> + 1 bool do_something_gp(void)
> + 2 {
> + 3 rcu_read_lock();
> + 4 p = rcu_dereference(gp);
> + 5 if (p) {
> + 6 do_something(p->a, p->b);
> + 7 rcu_read_unlock();
> + 8 return true;
> + 9 }
> + 10 rcu_read_unlock();
> + 11 return false;
> + 12 }
> +
> +The ``rcu_dereference()`` uses volatile casts and (for DEC Alpha) memory
> +barriers in the Linux kernel. Should a `high-quality implementation of
> +C11 ``memory_order_consume``
> +[PDF] <http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf>`__
> +ever appear, then ``rcu_dereference()`` could be implemented as a
> +``memory_order_consume`` load. Regardless of the exact implementation, a
> +pointer fetched by ``rcu_dereference()`` may not be used outside of the
> +outermost RCU read-side critical section containing that
> +``rcu_dereference()``, unless protection of the corresponding data
> +element has been passed from RCU to some other synchronization
> +mechanism, most commonly locking or `reference
> +counting <https://www.kernel.org/doc/Documentation/RCU/rcuref.txt>`__.
From the make htmldocs output, this appears very poorly for me, I get
something like this in the browser:
The rcu_dereference() uses volatile casts and (for DEC Alpha) memory barriers
in the Linux kernel. Should a high-quality implementation of C11
``memory_order_consume` [PDF]
<http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf>`__ ever
appear, then rcu_dereference() could be implemented as a memory_order_consume
load.
Is there a syntax issue here?
One more feedback,
the image under "RCU read-side critical section that started before the current
grace period:" should probably be blown up a bit.
^ permalink raw reply
* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
From: Joel Fernandes @ 2019-07-26 17:55 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Paul E. McKenney, Josh Triplett, Steven Rostedt,
Mathieu Desnoyers, Lai Jiangshan, Jonathan Corbet, rcu, linux-doc
In-Reply-To: <20190726140028.38abb5fa@coco.lan>
On Fri, Jul 26, 2019 at 02:00:28PM -0300, Mauro Carvalho Chehab wrote:
> Hi Joel,
>
> Em Fri, 26 Jul 2019 12:20:02 -0400
> Joel Fernandes <joel@joelfernandes.org> escreveu:
>
> > On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> > > There are 4 RCU articles that are written on html format.
> > >
> > > The way they are, they can't be part of the Linux Kernel
> > > documentation body nor share the styles and pdf output.
> > >
> > > So, convert them to ReST format.
> > >
> > > This way, make htmldocs and make pdfdocs will produce a
> > > documentation output that will be like the original ones, but
> > > will be part of the Linux Kernel documentation body.
> > >
> > > Part of the conversion was done with the help of pandoc, but
> > > the result had some broken things that had to be manually
> > > fixed.
> >
> > This looks Ok to me, but I also nervous something could have been done
> > incorrectly during the conversion.
> >
> > Could you list what were the "some broken things" that you had to manually
> > fix to make reviewing easier?
>
> There are a couple of things.
>
> At least the pandoc's version I used here has a bug: its conversion
> from html to ReST on those files only start after a <body> tag - or
> when the first quiz table starts. I only discovered that adding a
> <body> at the beginning of the file solve this book at the last
> conversions.
>
> So, for most html->ReST conversions, I manually converted the first
> part of the document, basically stripping html paragraph tags and
> by replacing highlights by the ReST syntax.
>
> Also, all the quiz tables seem to assume some javascript macro or
> css style that would be hiding the answer part until the mouse moves
> to it. Such macro/css was not there at the kernel tree. So, the quiz
> answers have the same color as the background, making them invisible.
> Even if we had such macro/css, this is not portable for pdf/LaTeX output
> (and I'm not sure if this would work with ePub).
>
> So, I ended by manually doing the table conversion.
>
> Finally, I double-checked if the conversions ended ok, addressing any
> issues that might have heppened.
>
> So, after both automatic conversion and manual fixes, I opened both the
> html files produced by Sphinx and the original ones and compared them
> line per line (except for the indexes, as Sphinx produces them
> automatically), in order to see if all information from the original
> files will be there on a format close to what we have on other ReST
> files, fixing any pending issues if any.
Thanks, I am in the process of going through these docs today and will let
you know anything I find. It would be nice to include the above challenges in
the changelog as well.
Some reason 'make htmldocs' needed me to install a whole bunch of
dependencies this time around.
By the way, that tools/memory-model/Documentation/explanation.txt is a useful
little document. Well not really little with over 1000 lines ;-). But it
would certainly benefit from ReST's / htmldocs ability to jump to labels and
search, etc since it is so long..
thanks,
- Joel
^ permalink raw reply
* [PATCH] docs: admin-guide: Adjust title underline length
From: Fabio Estevam @ 2019-07-26 16:27 UTC (permalink / raw)
To: corbet; +Cc: mchehab+samsung, linux-doc, Fabio Estevam
The following warning is seen when building 'make htmldocs':
Documentation/admin-guide/sysctl/kernel.rst:397: WARNING: Title underline too short.
Fix it by adjusting the title underline length appropriately.
Signed-off-by: Fabio Estevam <festevam@gmail.com>
---
Documentation/admin-guide/sysctl/kernel.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst
index 2e36620ec1e4..8af424dd0364 100644
--- a/Documentation/admin-guide/sysctl/kernel.rst
+++ b/Documentation/admin-guide/sysctl/kernel.rst
@@ -394,7 +394,7 @@ This file shows up if CONFIG_DETECT_HUNG_TASK is enabled.
hung_task_interval_warnings:
-===================
+============================
The same as hung_task_warnings, but set the number of interval
warnings to be issued about detected hung tasks during check
--
2.17.1
^ permalink raw reply related
page: next (older) | prev (newer) | latest
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox