Linux Documentation

Linux Documentation
 help / color / mirror / Atom feed

* Re: [PATCH v2 3/9] rcu/sync: Remove custom check for reader-section
From: Paul E. McKenney @ 2019-07-14 18:50 UTC (permalink / raw)
  To: Joel Fernandes
  Cc: linux-kernel, Oleg Nesterov, Alexey Kuznetsov, Bjorn Helgaas,
	Borislav Petkov, c0d1n61at3, David S. Miller, edumazet,
	Greg Kroah-Hartman, Hideaki YOSHIFUJI, H. Peter Anvin,
	Ingo Molnar, Jonathan Corbet, Josh Triplett, keescook,
	kernel-hardening, kernel-team, Lai Jiangshan, Len Brown,
	linux-acpi, linux-doc, linux-pci, linux-pm, Mathieu Desnoyers,
	neilb, netdev, Pavel Machek, peterz, Rafael J. Wysocki,
	Rasmus Villemoes, rcu, Steven Rostedt, Tejun Heo, Thomas Gleixner,
	will, maintainer:X86 ARCHITECTURE (32-BIT AND 64-BIT)
In-Reply-To: <20190714183820.GD34501@google.com>

On Sun, Jul 14, 2019 at 02:38:20PM -0400, Joel Fernandes wrote:
> On Sun, Jul 14, 2019 at 02:10:53PM -0400, Joel Fernandes wrote:
> > On Sat, Jul 13, 2019 at 02:28:12PM -0700, Paul E. McKenney wrote:
> [snip]
> > > > > > > > > > 
> > > > > > > > > > Cc: Oleg Nesterov <oleg@redhat.com>
> > > > > > > > > > Signed-off-by: Joel Fernandes (Google) <joel@joelfernandes.org>
> > > > > > > > > > ---
> > > > > > > > > >  include/linux/rcu_sync.h | 4 +---
> > > > > > > > > >  1 file changed, 1 insertion(+), 3 deletions(-)
> > > > > > > > > > 
> > > > > > > > > > diff --git a/include/linux/rcu_sync.h b/include/linux/rcu_sync.h
> > > > > > > > > > index 9b83865d24f9..0027d4c8087c 100644
> > > > > > > > > > --- a/include/linux/rcu_sync.h
> > > > > > > > > > +++ b/include/linux/rcu_sync.h
> > > > > > > > > > @@ -31,9 +31,7 @@ struct rcu_sync {
> > > > > > > > > >   */
> > > > > > > > > >  static inline bool rcu_sync_is_idle(struct rcu_sync *rsp)
> > > > > > > > > >  {
> > > > > > > > > > -	RCU_LOCKDEP_WARN(!rcu_read_lock_held() &&
> > > > > > > > > > -			 !rcu_read_lock_bh_held() &&
> > > > > > > > > > -			 !rcu_read_lock_sched_held(),
> > > > > > > > > > +	RCU_LOCKDEP_WARN(!rcu_read_lock_any_held(),
> > > > > > > > > 
> > > > > > > > > I believe that replacing rcu_read_lock_sched_held() with preemptible()
> > > > > > > > > in a CONFIG_PREEMPT=n kernel will give you false-positive splats here.
> > > > > > > > > If you have not already done so, could you please give it a try?
> > > > > > > > 
> > > > > > > > Hi Paul,
> > > > > > > > I don't think it will cause splats for !CONFIG_PREEMPT.
> > > > > > > > 
> > > > > > > > Currently, rcu_read_lock_any_held() introduced in this patch returns true if
> > > > > > > > !preemptible(). This means that:
> > > > > > > > 
> > > > > > > > The following expression above:
> > > > > > > > RCU_LOCKDEP_WARN(!rcu_read_lock_any_held(),...)
> > > > > > > > 
> > > > > > > > Becomes:
> > > > > > > > RCU_LOCKDEP_WARN(preemptible(), ...)
> > > > > > > > 
> > > > > > > > For, CONFIG_PREEMPT=n kernels, this means:
> > > > > > > > RCU_LOCKDEP_WARN(0, ...)
> > > > > > > > 
> > > > > > > > Which would mean no splats. Or, did I miss the point?
> > > > > > > 
> > > > > > > I suggest trying it out on a CONFIG_PREEMPT=n kernel.
> > > > > > 
> > > > > > Sure, will do, sorry did not try it out yet because was busy with weekend
> > > > > > chores but will do soon, thanks!
> > > > > 
> > > > > I am not faulting you for taking the weekend off, actually.  ;-)
> > > > 
> > > > ;-) 
> > > > 
> > > > I tried doing RCU_LOCKDEP_WARN(preemptible(), ...) in this code path and I
> > > > don't get any splats. I also disassembled the code and it seems to me
> > > > RCU_LOCKDEP_WARN() becomes a NOOP which also the above reasoning confirms.
> > > 
> > > OK, very good.  Could you do the same thing for the RCU_LOCKDEP_WARN()
> > > in synchronize_rcu()?  Why or why not?
> > > 
> > 
> > Hi Paul,
> > 
> > Yes synchronize_rcu() can also make use of this technique since it is
> > strictly illegal to call synchronize_rcu() within a reader section.
> > 
> > I will add this to the set of my patches as well and send them all out next
> > week, along with the rcu-sync and bh clean ups we discussed.
> 
> After sending this email, it occurs to me it wont work in synchronize_rcu()
> for !CONFIG_PREEMPT kernels. This is because in a !CONFIG_PREEMPT kernel,
> executing in kernel mode itself looks like being in an RCU reader. So we
> should leave that as is. However it will work fine for rcu_sync_is_idle (for
> CONFIG_PREEMPT=n kernels) as I mentioned earlier.
> 
> Were trying to throw me a Quick-Quiz ? ;-) In that case, hope I passed!

You did pass.  This time.  ;-)

							Thanx, Paul

^ permalink raw reply

* Re: [PATCH v2 3/9] rcu/sync: Remove custom check for reader-section
From: Joel Fernandes @ 2019-07-14 18:38 UTC (permalink / raw)
  To: Paul E. McKenney
  Cc: linux-kernel, Oleg Nesterov, Alexey Kuznetsov, Bjorn Helgaas,
	Borislav Petkov, c0d1n61at3, David S. Miller, edumazet,
	Greg Kroah-Hartman, Hideaki YOSHIFUJI, H. Peter Anvin,
	Ingo Molnar, Jonathan Corbet, Josh Triplett, keescook,
	kernel-hardening, kernel-team, Lai Jiangshan, Len Brown,
	linux-acpi, linux-doc, linux-pci, linux-pm, Mathieu Desnoyers,
	neilb, netdev, Pavel Machek, peterz, Rafael J. Wysocki,
	Rasmus Villemoes, rcu, Steven Rostedt, Tejun Heo, Thomas Gleixner,
	will, maintainer:X86 ARCHITECTURE (32-BIT AND 64-BIT)
In-Reply-To: <20190714181053.GB34501@google.com>

On Sun, Jul 14, 2019 at 02:10:53PM -0400, Joel Fernandes wrote:
> On Sat, Jul 13, 2019 at 02:28:12PM -0700, Paul E. McKenney wrote:
[snip]
> > > > > > > > > 
> > > > > > > > > Cc: Oleg Nesterov <oleg@redhat.com>
> > > > > > > > > Signed-off-by: Joel Fernandes (Google) <joel@joelfernandes.org>
> > > > > > > > > ---
> > > > > > > > >  include/linux/rcu_sync.h | 4 +---
> > > > > > > > >  1 file changed, 1 insertion(+), 3 deletions(-)
> > > > > > > > > 
> > > > > > > > > diff --git a/include/linux/rcu_sync.h b/include/linux/rcu_sync.h
> > > > > > > > > index 9b83865d24f9..0027d4c8087c 100644
> > > > > > > > > --- a/include/linux/rcu_sync.h
> > > > > > > > > +++ b/include/linux/rcu_sync.h
> > > > > > > > > @@ -31,9 +31,7 @@ struct rcu_sync {
> > > > > > > > >   */
> > > > > > > > >  static inline bool rcu_sync_is_idle(struct rcu_sync *rsp)
> > > > > > > > >  {
> > > > > > > > > -	RCU_LOCKDEP_WARN(!rcu_read_lock_held() &&
> > > > > > > > > -			 !rcu_read_lock_bh_held() &&
> > > > > > > > > -			 !rcu_read_lock_sched_held(),
> > > > > > > > > +	RCU_LOCKDEP_WARN(!rcu_read_lock_any_held(),
> > > > > > > > 
> > > > > > > > I believe that replacing rcu_read_lock_sched_held() with preemptible()
> > > > > > > > in a CONFIG_PREEMPT=n kernel will give you false-positive splats here.
> > > > > > > > If you have not already done so, could you please give it a try?
> > > > > > > 
> > > > > > > Hi Paul,
> > > > > > > I don't think it will cause splats for !CONFIG_PREEMPT.
> > > > > > > 
> > > > > > > Currently, rcu_read_lock_any_held() introduced in this patch returns true if
> > > > > > > !preemptible(). This means that:
> > > > > > > 
> > > > > > > The following expression above:
> > > > > > > RCU_LOCKDEP_WARN(!rcu_read_lock_any_held(),...)
> > > > > > > 
> > > > > > > Becomes:
> > > > > > > RCU_LOCKDEP_WARN(preemptible(), ...)
> > > > > > > 
> > > > > > > For, CONFIG_PREEMPT=n kernels, this means:
> > > > > > > RCU_LOCKDEP_WARN(0, ...)
> > > > > > > 
> > > > > > > Which would mean no splats. Or, did I miss the point?
> > > > > > 
> > > > > > I suggest trying it out on a CONFIG_PREEMPT=n kernel.
> > > > > 
> > > > > Sure, will do, sorry did not try it out yet because was busy with weekend
> > > > > chores but will do soon, thanks!
> > > > 
> > > > I am not faulting you for taking the weekend off, actually.  ;-)
> > > 
> > > ;-) 
> > > 
> > > I tried doing RCU_LOCKDEP_WARN(preemptible(), ...) in this code path and I
> > > don't get any splats. I also disassembled the code and it seems to me
> > > RCU_LOCKDEP_WARN() becomes a NOOP which also the above reasoning confirms.
> > 
> > OK, very good.  Could you do the same thing for the RCU_LOCKDEP_WARN()
> > in synchronize_rcu()?  Why or why not?
> > 
> 
> Hi Paul,
> 
> Yes synchronize_rcu() can also make use of this technique since it is
> strictly illegal to call synchronize_rcu() within a reader section.
> 
> I will add this to the set of my patches as well and send them all out next
> week, along with the rcu-sync and bh clean ups we discussed.

After sending this email, it occurs to me it wont work in synchronize_rcu()
for !CONFIG_PREEMPT kernels. This is because in a !CONFIG_PREEMPT kernel,
executing in kernel mode itself looks like being in an RCU reader. So we
should leave that as is. However it will work fine for rcu_sync_is_idle (for
CONFIG_PREEMPT=n kernels) as I mentioned earlier.

Were trying to throw me a Quick-Quiz ? ;-) In that case, hope I passed!

thanks,

 - Joel


^ permalink raw reply

* Re: [PATCH] Documentation/security-bugs: provide more information about linux-distros
From: Solar Designer @ 2019-07-14 18:05 UTC (permalink / raw)
  To: Sasha Levin
  Cc: Will Deacon, Greg KH, corbet, keescook, peterz, tyhicks,
	linux-doc, linux-kernel
In-Reply-To: <20190711203500.GB10104@sasha-vm>

On Thu, Jul 11, 2019 at 04:35:00PM -0400, Sasha Levin wrote:
> On Thu, Jul 11, 2019 at 06:09:21PM +0100, Will Deacon wrote:
> >On Thu, Jul 11, 2019 at 07:07:32PM +0200, Greg KH wrote:
> >>On Thu, Jul 11, 2019 at 12:36:37PM -0400, Sasha Levin wrote:
> >>> Provide more information about how to interact with the linux-distros
> >>> mailing list for disclosing security bugs.
> >>>
> >>> First, clarify that the reporter must read and accept the linux-distros
> >>> policies prior to sending a report.
> >>>
> >>> Second, clarify that the reported must provide a tentative public
> >>> disclosure date and time in his first contact with linux-distros.
> >>>
> >>> Suggested-by: Solar Designer <solar@openwall.com>
> >>> Signed-off-by: Sasha Levin <sashal@kernel.org>
> >>> ---
> >>>  Documentation/admin-guide/security-bugs.rst | 21 +++++++++++++--------
> >>>  1 file changed, 13 insertions(+), 8 deletions(-)

Thanks.  Sasha's proposed changes do address the two issues I pointed
out, so are an improvement.  However:

> >>Do we really need to describe all of the information on how to use the
> >>distro list here?  That's why we included the link, as it has all of
> >>this well spelled out and described.  If anything, I would say we should
> >>say less in this document about what linux-distros do, as that is
> >>independent of the Linux security team.
> >
> >Agreed, and it also means that any changes linux-distros make to their
> >policy won't be reflecting in the numerous kernel trees out there, so a
> >link is much better imo.

I also agree with this.

> I agree that the 2nd part about embargo timelines is redundant, but I
> only addressed it because the document was already addressing embargos.
> 
> I only now realized that the link we had there was just going to the
> main wiki page by mistake: the tag it was trying to point to was removed
> from the wiki page. We should probably update that too.
> 
> With regards to the explicit instruction to agree with policies, I think
> we do need it there. Right now this section reads as "for embargoes work
> with linux-distros@vs.openwall.org, and btw they have a wiki which you
> may or may not need to read".

Yes, we should update the link, but maybe we should also drop the
posting e-mail address, which will ensure someone will have to check out
the link before they're able to post.  This should allow us to drop the
summary of linux-distros policy and posting instructions, although maybe
they're beneficial to keep if we're confident we'd be maintaining this
summary to reflect possible changes on the linked page.

> We probably do need to stress here that linux-distros has different
> policies than security@kernel.org.

OK.

Alexander

^ permalink raw reply

* Re: [PATCH v2 3/9] rcu/sync: Remove custom check for reader-section
From: Joel Fernandes @ 2019-07-14 18:10 UTC (permalink / raw)
  To: Paul E. McKenney
  Cc: linux-kernel, Oleg Nesterov, Alexey Kuznetsov, Bjorn Helgaas,
	Borislav Petkov, c0d1n61at3, David S. Miller, edumazet,
	Greg Kroah-Hartman, Hideaki YOSHIFUJI, H. Peter Anvin,
	Ingo Molnar, Jonathan Corbet, Josh Triplett, keescook,
	kernel-hardening, kernel-team, Lai Jiangshan, Len Brown,
	linux-acpi, linux-doc, linux-pci, linux-pm, Mathieu Desnoyers,
	neilb, netdev, Pavel Machek, peterz, Rafael J. Wysocki,
	Rasmus Villemoes, rcu, Steven Rostedt, Tejun Heo, Thomas Gleixner,
	will, maintainer:X86 ARCHITECTURE (32-BIT AND 64-BIT)
In-Reply-To: <20190713212812.GH26519@linux.ibm.com>

On Sat, Jul 13, 2019 at 02:28:12PM -0700, Paul E. McKenney wrote:
> On Sat, Jul 13, 2019 at 12:13:16PM -0400, Joel Fernandes wrote:
> > On Sat, Jul 13, 2019 at 08:50:10AM -0700, Paul E. McKenney wrote:
> > > On Sat, Jul 13, 2019 at 11:36:06AM -0400, Joel Fernandes wrote:
> > > > On Sat, Jul 13, 2019 at 07:41:08AM -0700, Paul E. McKenney wrote:
> > > > > On Sat, Jul 13, 2019 at 09:30:49AM -0400, Joel Fernandes wrote:
> > > > > > On Sat, Jul 13, 2019 at 01:21:14AM -0700, Paul E. McKenney wrote:
> > > > > > > On Fri, Jul 12, 2019 at 11:10:08PM -0400, Joel Fernandes wrote:
> > > > > > > > On Fri, Jul 12, 2019 at 11:01:50PM -0400, Joel Fernandes wrote:
> > > > > > > > > On Fri, Jul 12, 2019 at 04:32:06PM -0700, Paul E. McKenney wrote:
> > > > > > > > > > On Fri, Jul 12, 2019 at 05:35:59PM -0400, Joel Fernandes wrote:
> > > > > > > > > > > On Fri, Jul 12, 2019 at 01:00:18PM -0400, Joel Fernandes (Google) wrote:
> > > > > > > > > > > > The rcu/sync code was doing its own check whether we are in a reader
> > > > > > > > > > > > section. With RCU consolidating flavors and the generic helper added in
> > > > > > > > > > > > this series, this is no longer need. We can just use the generic helper
> > > > > > > > > > > > and it results in a nice cleanup.
> > > > > > > > > > > > 
> > > > > > > > > > > > Cc: Oleg Nesterov <oleg@redhat.com>
> > > > > > > > > > > > Signed-off-by: Joel Fernandes (Google) <joel@joelfernandes.org>
> > > > > > > > > > > 
> > > > > > > > > > > Hi Oleg,
> > > > > > > > > > > Slightly unrelated to the patch,
> > > > > > > > > > > I tried hard to understand this comment below in percpu_down_read() but no dice.
> > > > > > > > > > > 
> > > > > > > > > > > I do understand how rcu sync and percpu rwsem works, however the comment
> > > > > > > > > > > below didn't make much sense to me. For one, there's no readers_fast anymore
> > > > > > > > > > > so I did not follow what readers_fast means. Could the comment be updated to
> > > > > > > > > > > reflect latest changes?
> > > > > > > > > > > Also could you help understand how is a writer not able to change
> > > > > > > > > > > sem->state and count the per-cpu read counters at the same time as the
> > > > > > > > > > > comment tries to say?
> > > > > > > > > > > 
> > > > > > > > > > > 	/*
> > > > > > > > > > > 	 * We are in an RCU-sched read-side critical section, so the writer
> > > > > > > > > > > 	 * cannot both change sem->state from readers_fast and start checking
> > > > > > > > > > > 	 * counters while we are here. So if we see !sem->state, we know that
> > > > > > > > > > > 	 * the writer won't be checking until we're past the preempt_enable()
> > > > > > > > > > > 	 * and that once the synchronize_rcu() is done, the writer will see
> > > > > > > > > > > 	 * anything we did within this RCU-sched read-size critical section.
> > > > > > > > > > > 	 */
> > > > > > > > > > > 
> > > > > > > > > > > Also,
> > > > > > > > > > > I guess we could get rid of all of the gp_ops struct stuff now that since all
> > > > > > > > > > > the callbacks are the same now. I will post that as a follow-up patch to this
> > > > > > > > > > > series.
> > > > > > > > > > 
> > > > > > > > > > Hello, Joel,
> > > > > > > > > > 
> > > > > > > > > > Oleg has a set of patches updating this code that just hit mainline
> > > > > > > > > > this week.  These patches get rid of the code that previously handled
> > > > > > > > > > RCU's multiple flavors.  Or are you looking at current mainline and
> > > > > > > > > > me just missing your point?
> > > > > > > > > > 
> > > > > > > > > 
> > > > > > > > > Hi Paul,
> > > > > > > > > You are right on point. I have a bad habit of not rebasing my trees. In this
> > > > > > > > > case the feature branch of mine in concern was based on v5.1. Needless to
> > > > > > > > > say, I need to rebase my tree.
> > > > > > > > > 
> > > > > > > > > Yes, this sync clean up patch does conflict when I rebase, but other patches
> > > > > > > > > rebase just fine.
> > > > > > > > > 
> > > > > > > > > The 2 options I see are:
> > > > > > > > > 1. Let us drop this patch for now and I resend it later.
> > > > > > > > > 2. I resend all patches based on Linus's master branch.
> > > > > > > > 
> > > > > > > > Below is the updated patch based on Linus master branch:
> > > > > > > > 
> > > > > > > > ---8<-----------------------
> > > > > > > > 
> > > > > > > > >From 5f40c9a07fcf3d6dafc2189599d0ba9443097d0f Mon Sep 17 00:00:00 2001
> > > > > > > > From: "Joel Fernandes (Google)" <joel@joelfernandes.org>
> > > > > > > > Date: Fri, 12 Jul 2019 12:13:27 -0400
> > > > > > > > Subject: [PATCH v2.1 3/9] rcu/sync: Remove custom check for reader-section
> > > > > > > > 
> > > > > > > > The rcu/sync code was doing its own check whether we are in a reader
> > > > > > > > section. With RCU consolidating flavors and the generic helper added in
> > > > > > > > this series, this is no longer need. We can just use the generic helper
> > > > > > > > and it results in a nice cleanup.
> > > > > > > > 
> > > > > > > > Cc: Oleg Nesterov <oleg@redhat.com>
> > > > > > > > Signed-off-by: Joel Fernandes (Google) <joel@joelfernandes.org>
> > > > > > > > ---
> > > > > > > >  include/linux/rcu_sync.h | 4 +---
> > > > > > > >  1 file changed, 1 insertion(+), 3 deletions(-)
> > > > > > > > 
> > > > > > > > diff --git a/include/linux/rcu_sync.h b/include/linux/rcu_sync.h
> > > > > > > > index 9b83865d24f9..0027d4c8087c 100644
> > > > > > > > --- a/include/linux/rcu_sync.h
> > > > > > > > +++ b/include/linux/rcu_sync.h
> > > > > > > > @@ -31,9 +31,7 @@ struct rcu_sync {
> > > > > > > >   */
> > > > > > > >  static inline bool rcu_sync_is_idle(struct rcu_sync *rsp)
> > > > > > > >  {
> > > > > > > > -	RCU_LOCKDEP_WARN(!rcu_read_lock_held() &&
> > > > > > > > -			 !rcu_read_lock_bh_held() &&
> > > > > > > > -			 !rcu_read_lock_sched_held(),
> > > > > > > > +	RCU_LOCKDEP_WARN(!rcu_read_lock_any_held(),
> > > > > > > 
> > > > > > > I believe that replacing rcu_read_lock_sched_held() with preemptible()
> > > > > > > in a CONFIG_PREEMPT=n kernel will give you false-positive splats here.
> > > > > > > If you have not already done so, could you please give it a try?
> > > > > > 
> > > > > > Hi Paul,
> > > > > > I don't think it will cause splats for !CONFIG_PREEMPT.
> > > > > > 
> > > > > > Currently, rcu_read_lock_any_held() introduced in this patch returns true if
> > > > > > !preemptible(). This means that:
> > > > > > 
> > > > > > The following expression above:
> > > > > > RCU_LOCKDEP_WARN(!rcu_read_lock_any_held(),...)
> > > > > > 
> > > > > > Becomes:
> > > > > > RCU_LOCKDEP_WARN(preemptible(), ...)
> > > > > > 
> > > > > > For, CONFIG_PREEMPT=n kernels, this means:
> > > > > > RCU_LOCKDEP_WARN(0, ...)
> > > > > > 
> > > > > > Which would mean no splats. Or, did I miss the point?
> > > > > 
> > > > > I suggest trying it out on a CONFIG_PREEMPT=n kernel.
> > > > 
> > > > Sure, will do, sorry did not try it out yet because was busy with weekend
> > > > chores but will do soon, thanks!
> > > 
> > > I am not faulting you for taking the weekend off, actually.  ;-)
> > 
> > ;-) 
> > 
> > I tried doing RCU_LOCKDEP_WARN(preemptible(), ...) in this code path and I
> > don't get any splats. I also disassembled the code and it seems to me
> > RCU_LOCKDEP_WARN() becomes a NOOP which also the above reasoning confirms.
> 
> OK, very good.  Could you do the same thing for the RCU_LOCKDEP_WARN()
> in synchronize_rcu()?  Why or why not?
> 

Hi Paul,

Yes synchronize_rcu() can also make use of this technique since it is
strictly illegal to call synchronize_rcu() within a reader section.

I will add this to the set of my patches as well and send them all out next
week, along with the rcu-sync and bh clean ups we discussed.

thanks,

- Joel


^ permalink raw reply

* Re: [PATCH 5/5] docs: spi: convert to ReST and add it to the kABI bookset
From: Jonathan Cameron @ 2019-07-14 16:24 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, Mark Brown, Hartmut Knaack, Lars-Peter Clausen,
	Peter Meerwald-Stadler, linux-spi, linux-iio
In-Reply-To: <7895cce04cd4d140fb519a02315a8309c4c3ebb5.1561756511.git.mchehab+samsung@kernel.org>

On Fri, 28 Jun 2019 18:23:16 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:

> While there's one file there with briefily describes the uAPI,
> the documentation was written just like most subsystems: focused
> on kernel developers. So, add it together with driver-api books.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
For the minimal touch on IIO.
Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>

Thanks,

> ---
>  Documentation/index.rst                       |   1 +
>  .../spi/{butterfly => butterfly.rst}          |  44 ++++----
>  Documentation/spi/index.rst                   |  23 ++++
>  Documentation/spi/{pxa2xx => pxa2xx.rst}      |  94 ++++++++--------
>  .../spi/{spi-lm70llp => spi-lm70llp.rst}      |  17 ++-
>  .../spi/{spi-sc18is602 => spi-sc18is602.rst}  |   3 +
>  .../spi/{spi-summary => spi-summary.rst}      | 103 ++++++++++--------
>  Documentation/spi/{spidev => spidev.rst}      |  30 +++--
>  drivers/iio/dummy/iio_simple_dummy.c          |   2 +-
>  drivers/spi/Kconfig                           |   2 +-
>  drivers/spi/spi-butterfly.c                   |   2 +-
>  drivers/spi/spi-lm70llp.c                     |   2 +-
>  include/linux/platform_data/sc18is602.h       |   2 +-
>  13 files changed, 198 insertions(+), 127 deletions(-)
>  rename Documentation/spi/{butterfly => butterfly.rst} (71%)
>  create mode 100644 Documentation/spi/index.rst
>  rename Documentation/spi/{pxa2xx => pxa2xx.rst} (83%)
>  rename Documentation/spi/{spi-lm70llp => spi-lm70llp.rst} (88%)
>  rename Documentation/spi/{spi-sc18is602 => spi-sc18is602.rst} (97%)
>  rename Documentation/spi/{spi-summary => spi-summary.rst} (93%)
>  rename Documentation/spi/{spidev => spidev.rst} (90%)
> 
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index 38ece18f5d1e..bcaddbfa817f 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -115,6 +115,7 @@ needed).
>     power/index
>     target/index
>     timers/index
> +   spi/index
>     w1/index
>     watchdog/index
>     input/index
> diff --git a/Documentation/spi/butterfly b/Documentation/spi/butterfly.rst
> similarity index 71%
> rename from Documentation/spi/butterfly
> rename to Documentation/spi/butterfly.rst
> index 9927af7a629c..e614a589547c 100644
> --- a/Documentation/spi/butterfly
> +++ b/Documentation/spi/butterfly.rst
> @@ -1,3 +1,4 @@
> +===================================================
>  spi_butterfly - parport-to-butterfly adapter driver
>  ===================================================
>  
> @@ -27,25 +28,29 @@ need to reflash the firmware, and the pins are the standard Atmel "ISP"
>  connector pins (used also on non-Butterfly AVR boards).  On the parport
>  side this is like "sp12" programming cables.
>  
> +	======	  =============	  ===================
>  	Signal	  Butterfly	  Parport (DB-25)
> -	------	  ---------	  ---------------
> -	SCK	= J403.PB1/SCK	= pin 2/D0
> -	RESET	= J403.nRST	= pin 3/D1
> -	VCC	= J403.VCC_EXT	= pin 8/D6
> -	MOSI	= J403.PB2/MOSI	= pin 9/D7
> -	MISO	= J403.PB3/MISO	= pin 11/S7,nBUSY
> -	GND	= J403.GND	= pin 23/GND
> +	======	  =============	  ===================
> +	SCK	  J403.PB1/SCK	  pin 2/D0
> +	RESET	  J403.nRST	  pin 3/D1
> +	VCC	  J403.VCC_EXT	  pin 8/D6
> +	MOSI	  J403.PB2/MOSI	  pin 9/D7
> +	MISO	  J403.PB3/MISO	  pin 11/S7,nBUSY
> +	GND	  J403.GND	  pin 23/GND
> +	======	  =============	  ===================
>  
>  Then to let Linux master that bus to talk to the DataFlash chip, you must
>  (a) flash new firmware that disables SPI (set PRR.2, and disable pullups
>  by clearing PORTB.[0-3]); (b) configure the mtd_dataflash driver; and
>  (c) cable in the chipselect.
>  
> +	======	  ============	  ===================
>  	Signal	  Butterfly	  Parport (DB-25)
> -	------	  ---------	  ---------------
> -	VCC	= J400.VCC_EXT	= pin 7/D5
> -	SELECT	= J400.PB0/nSS	= pin 17/C3,nSELECT
> -	GND	= J400.GND	= pin 24/GND
> +	======	  ============	  ===================
> +	VCC	  J400.VCC_EXT	  pin 7/D5
> +	SELECT	  J400.PB0/nSS	  pin 17/C3,nSELECT
> +	GND	  J400.GND	  pin 24/GND
> +	======	  ============	  ===================
>  
>  Or you could flash firmware making the AVR into an SPI slave (keeping the
>  DataFlash in reset) and tweak the spi_butterfly driver to make it bind to
> @@ -56,13 +61,14 @@ That would let you talk to the AVR using custom SPI-with-USI firmware,
>  while letting either Linux or the AVR use the DataFlash.  There are plenty
>  of spare parport pins to wire this one up, such as:
>  
> +	======	  =============	  ===================
>  	Signal	  Butterfly	  Parport (DB-25)
> -	------	  ---------	  ---------------
> -	SCK	= J403.PE4/USCK	= pin 5/D3
> -	MOSI	= J403.PE5/DI	= pin 6/D4
> -	MISO	= J403.PE6/DO	= pin 12/S5,nPAPEROUT
> -	GND	= J403.GND	= pin 22/GND
> -
> -	IRQ	= J402.PF4	= pin 10/S6,ACK
> -	GND	= J402.GND(P2)	= pin 25/GND
> +	======	  =============	  ===================
> +	SCK	  J403.PE4/USCK	  pin 5/D3
> +	MOSI	  J403.PE5/DI	  pin 6/D4
> +	MISO	  J403.PE6/DO	  pin 12/S5,nPAPEROUT
> +	GND	  J403.GND	  pin 22/GND
>  
> +	IRQ	  J402.PF4	  pin 10/S6,ACK
> +	GND	  J402.GND(P2)	  pin 25/GND
> +	======	  =============	  ===================
> diff --git a/Documentation/spi/index.rst b/Documentation/spi/index.rst
> new file mode 100644
> index 000000000000..bad6259a7bb6
> --- /dev/null
> +++ b/Documentation/spi/index.rst
> @@ -0,0 +1,23 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=================================
> +Serial Peripheral Interface (SPI)
> +=================================
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   spi-summary
> +   spidev
> +   butterfly
> +   pxa2xx
> +   spi-lm70llp
> +   spi-sc18is602
> +
> +.. only::  subproject and html
> +
> +   Indices
> +   =======
> +
> +   * :ref:`genindex`
> +
> diff --git a/Documentation/spi/pxa2xx b/Documentation/spi/pxa2xx.rst
> similarity index 83%
> rename from Documentation/spi/pxa2xx
> rename to Documentation/spi/pxa2xx.rst
> index 551325b66b23..457faef8be74 100644
> --- a/Documentation/spi/pxa2xx
> +++ b/Documentation/spi/pxa2xx.rst
> @@ -1,8 +1,10 @@
> +==============================
>  PXA2xx SPI on SSP driver HOWTO
> -===================================================
> +==============================
> +
>  This a mini howto on the pxa2xx_spi driver.  The driver turns a PXA2xx
>  synchronous serial port into a SPI master controller
> -(see Documentation/spi/spi-summary). The driver has the following features
> +(see Documentation/spi/spi-summary.rst). The driver has the following features
>  
>  - Support for any PXA2xx SSP
>  - SSP PIO and SSP DMA data transfers.
> @@ -19,12 +21,12 @@ Declaring PXA2xx Master Controllers
>  -----------------------------------
>  Typically a SPI master is defined in the arch/.../mach-*/board-*.c as a
>  "platform device".  The master configuration is passed to the driver via a table
> -found in include/linux/spi/pxa2xx_spi.h:
> +found in include/linux/spi/pxa2xx_spi.h::
>  
> -struct pxa2xx_spi_controller {
> +  struct pxa2xx_spi_controller {
>  	u16 num_chipselect;
>  	u8 enable_dma;
> -};
> +  };
>  
>  The "pxa2xx_spi_controller.num_chipselect" field is used to determine the number of
>  slave device (chips) attached to this SPI master.
> @@ -36,9 +38,9 @@ See the "PXA2xx Developer Manual" section "DMA Controller".
>  
>  NSSP MASTER SAMPLE
>  ------------------
> -Below is a sample configuration using the PXA255 NSSP.
> +Below is a sample configuration using the PXA255 NSSP::
>  
> -static struct resource pxa_spi_nssp_resources[] = {
> +  static struct resource pxa_spi_nssp_resources[] = {
>  	[0] = {
>  		.start	= __PREG(SSCR0_P(2)), /* Start address of NSSP */
>  		.end	= __PREG(SSCR0_P(2)) + 0x2c, /* Range of registers */
> @@ -49,14 +51,14 @@ static struct resource pxa_spi_nssp_resources[] = {
>  		.end	= IRQ_NSSP,
>  		.flags	= IORESOURCE_IRQ,
>  	},
> -};
> +  };
>  
> -static struct pxa2xx_spi_controller pxa_nssp_master_info = {
> +  static struct pxa2xx_spi_controller pxa_nssp_master_info = {
>  	.num_chipselect = 1, /* Matches the number of chips attached to NSSP */
>  	.enable_dma = 1, /* Enables NSSP DMA */
> -};
> +  };
>  
> -static struct platform_device pxa_spi_nssp = {
> +  static struct platform_device pxa_spi_nssp = {
>  	.name = "pxa2xx-spi", /* MUST BE THIS VALUE, so device match driver */
>  	.id = 2, /* Bus number, MUST MATCH SSP number 1..n */
>  	.resource = pxa_spi_nssp_resources,
> @@ -64,22 +66,22 @@ static struct platform_device pxa_spi_nssp = {
>  	.dev = {
>  		.platform_data = &pxa_nssp_master_info, /* Passed to driver */
>  	},
> -};
> +  };
>  
> -static struct platform_device *devices[] __initdata = {
> +  static struct platform_device *devices[] __initdata = {
>  	&pxa_spi_nssp,
> -};
> +  };
>  
> -static void __init board_init(void)
> -{
> +  static void __init board_init(void)
> +  {
>  	(void)platform_add_device(devices, ARRAY_SIZE(devices));
> -}
> +  }
>  
>  Declaring Slave Devices
>  -----------------------
>  Typically each SPI slave (chip) is defined in the arch/.../mach-*/board-*.c
>  using the "spi_board_info" structure found in "linux/spi/spi.h". See
> -"Documentation/spi/spi-summary" for additional information.
> +"Documentation/spi/spi-summary.rst" for additional information.
>  
>  Each slave device attached to the PXA must provide slave specific configuration
>  information via the structure "pxa2xx_spi_chip" found in
> @@ -87,19 +89,21 @@ information via the structure "pxa2xx_spi_chip" found in
>  will uses the configuration whenever the driver communicates with the slave
>  device. All fields are optional.
>  
> -struct pxa2xx_spi_chip {
> +::
> +
> +  struct pxa2xx_spi_chip {
>  	u8 tx_threshold;
>  	u8 rx_threshold;
>  	u8 dma_burst_size;
>  	u32 timeout;
>  	u8 enable_loopback;
>  	void (*cs_control)(u32 command);
> -};
> +  };
>  
>  The "pxa2xx_spi_chip.tx_threshold" and "pxa2xx_spi_chip.rx_threshold" fields are
>  used to configure the SSP hardware fifo.  These fields are critical to the
>  performance of pxa2xx_spi driver and misconfiguration will result in rx
> -fifo overruns (especially in PIO mode transfers). Good default values are
> +fifo overruns (especially in PIO mode transfers). Good default values are::
>  
>  	.tx_threshold = 8,
>  	.rx_threshold = 8,
> @@ -141,41 +145,43 @@ The pxa2xx_spi_chip structure is passed to the pxa2xx_spi driver in the
>  "spi_board_info.controller_data" field. Below is a sample configuration using
>  the PXA255 NSSP.
>  
> -/* Chip Select control for the CS8415A SPI slave device */
> -static void cs8415a_cs_control(u32 command)
> -{
> +::
> +
> +  /* Chip Select control for the CS8415A SPI slave device */
> +  static void cs8415a_cs_control(u32 command)
> +  {
>  	if (command & PXA2XX_CS_ASSERT)
>  		GPCR(2) = GPIO_bit(2);
>  	else
>  		GPSR(2) = GPIO_bit(2);
> -}
> +  }
>  
> -/* Chip Select control for the CS8405A SPI slave device */
> -static void cs8405a_cs_control(u32 command)
> -{
> +  /* Chip Select control for the CS8405A SPI slave device */
> +  static void cs8405a_cs_control(u32 command)
> +  {
>  	if (command & PXA2XX_CS_ASSERT)
>  		GPCR(3) = GPIO_bit(3);
>  	else
>  		GPSR(3) = GPIO_bit(3);
> -}
> +  }
>  
> -static struct pxa2xx_spi_chip cs8415a_chip_info = {
> +  static struct pxa2xx_spi_chip cs8415a_chip_info = {
>  	.tx_threshold = 8, /* SSP hardward FIFO threshold */
>  	.rx_threshold = 8, /* SSP hardward FIFO threshold */
>  	.dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
>  	.timeout = 235, /* See Intel documentation */
>  	.cs_control = cs8415a_cs_control, /* Use external chip select */
> -};
> +  };
>  
> -static struct pxa2xx_spi_chip cs8405a_chip_info = {
> +  static struct pxa2xx_spi_chip cs8405a_chip_info = {
>  	.tx_threshold = 8, /* SSP hardward FIFO threshold */
>  	.rx_threshold = 8, /* SSP hardward FIFO threshold */
>  	.dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
>  	.timeout = 235, /* See Intel documentation */
>  	.cs_control = cs8405a_cs_control, /* Use external chip select */
> -};
> +  };
>  
> -static struct spi_board_info streetracer_spi_board_info[] __initdata = {
> +  static struct spi_board_info streetracer_spi_board_info[] __initdata = {
>  	{
>  		.modalias = "cs8415a", /* Name of spi_driver for this device */
>  		.max_speed_hz = 3686400, /* Run SSP as fast a possbile */
> @@ -193,13 +199,13 @@ static struct spi_board_info streetracer_spi_board_info[] __initdata = {
>  		.controller_data = &cs8405a_chip_info, /* Master chip config */
>  		.irq = STREETRACER_APCI_IRQ, /* Slave device interrupt */
>  	},
> -};
> +  };
>  
> -static void __init streetracer_init(void)
> -{
> +  static void __init streetracer_init(void)
> +  {
>  	spi_register_board_info(streetracer_spi_board_info,
>  				ARRAY_SIZE(streetracer_spi_board_info));
> -}
> +  }
>  
>  
>  DMA and PIO I/O Support
> @@ -210,22 +216,22 @@ by setting the "enable_dma" flag in the "pxa2xx_spi_controller" structure.  The
>  mode supports both coherent and stream based DMA mappings.
>  
>  The following logic is used to determine the type of I/O to be used on
> -a per "spi_transfer" basis:
> +a per "spi_transfer" basis::
>  
> -if !enable_dma then
> +  if !enable_dma then
>  	always use PIO transfers
>  
> -if spi_message.len > 8191 then
> +  if spi_message.len > 8191 then
>  	print "rate limited" warning
>  	use PIO transfers
>  
> -if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then
> +  if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then
>  	use coherent DMA mode
>  
> -if rx_buf and tx_buf are aligned on 8 byte boundary then
> +  if rx_buf and tx_buf are aligned on 8 byte boundary then
>  	use streaming DMA mode
>  
> -otherwise
> +  otherwise
>  	use PIO transfer
>  
>  THANKS TO
> diff --git a/Documentation/spi/spi-lm70llp b/Documentation/spi/spi-lm70llp.rst
> similarity index 88%
> rename from Documentation/spi/spi-lm70llp
> rename to Documentation/spi/spi-lm70llp.rst
> index 463f6d01fa15..07631aef4343 100644
> --- a/Documentation/spi/spi-lm70llp
> +++ b/Documentation/spi/spi-lm70llp.rst
> @@ -1,8 +1,11 @@
> +==============================================
>  spi_lm70llp :  LM70-LLP parport-to-SPI adapter
>  ==============================================
>  
>  Supported board/chip:
> +
>    * National Semiconductor LM70 LLP evaluation board
> +
>      Datasheet: http://www.national.com/pf/LM/LM70.html
>  
>  Author:
> @@ -29,9 +32,10 @@ available (on page 4) here:
>  
>  The hardware interfacing on the LM70 LLP eval board is as follows:
>  
> +   ======== == =========   ==========
>     Parallel                 LM70 LLP
> -     Port      Direction   JP2 Header
> -   ----------- --------- ----------------
> +     Port   .  Direction   JP2 Header
> +   ======== == =========   ==========
>        D0     2      -         -
>        D1     3     -->      V+   5
>        D2     4     -->      V+   5
> @@ -42,7 +46,7 @@ The hardware interfacing on the LM70 LLP eval board is as follows:
>        D7     9     -->      SI/O 5
>       GND    25      -       GND  7
>      Select  13     <--      SI/O 1
> -   ----------- --------- ----------------
> +   ======== == =========   ==========
>  
>  Note that since the LM70 uses a "3-wire" variant of SPI, the SI/SO pin
>  is connected to both pin D7 (as Master Out) and Select (as Master In)
> @@ -74,6 +78,7 @@ inverting the value read at pin 13.
>  
>  Thanks to
>  ---------
> -o David Brownell for mentoring the SPI-side driver development.
> -o Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version.
> -o Nadir Billimoria for help interpreting the circuit schematic.
> +
> +- David Brownell for mentoring the SPI-side driver development.
> +- Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version.
> +- Nadir Billimoria for help interpreting the circuit schematic.
> diff --git a/Documentation/spi/spi-sc18is602 b/Documentation/spi/spi-sc18is602.rst
> similarity index 97%
> rename from Documentation/spi/spi-sc18is602
> rename to Documentation/spi/spi-sc18is602.rst
> index 0feffd5af411..2a31dc722321 100644
> --- a/Documentation/spi/spi-sc18is602
> +++ b/Documentation/spi/spi-sc18is602.rst
> @@ -1,8 +1,11 @@
> +===========================
>  Kernel driver spi-sc18is602
>  ===========================
>  
>  Supported chips:
> +
>    * NXP SI18IS602/602B/603
> +
>      Datasheet: http://www.nxp.com/documents/data_sheet/SC18IS602_602B_603.pdf
>  
>  Author:
> diff --git a/Documentation/spi/spi-summary b/Documentation/spi/spi-summary.rst
> similarity index 93%
> rename from Documentation/spi/spi-summary
> rename to Documentation/spi/spi-summary.rst
> index 1a63194b74d7..96b3f8b8b3db 100644
> --- a/Documentation/spi/spi-summary
> +++ b/Documentation/spi/spi-summary.rst
> @@ -1,3 +1,4 @@
> +====================================
>  Overview of Linux kernel SPI support
>  ====================================
>  
> @@ -139,12 +140,14 @@ a command and then reading its response.
>  
>  There are two types of SPI driver, here called:
>  
> -  Controller drivers ... controllers may be built into System-On-Chip
> +  Controller drivers ...
> +        controllers may be built into System-On-Chip
>  	processors, and often support both Master and Slave roles.
>  	These drivers touch hardware registers and may use DMA.
>  	Or they can be PIO bitbangers, needing just GPIO pins.
>  
> -  Protocol drivers ... these pass messages through the controller
> +  Protocol drivers ...
> +        these pass messages through the controller
>  	driver to communicate with a Slave or Master device on the
>  	other side of an SPI link.
>  
> @@ -160,7 +163,7 @@ those two types of drivers.
>  There is a minimal core of SPI programming interfaces, focussing on
>  using the driver model to connect controller and protocol drivers using
>  device tables provided by board specific initialization code.  SPI
> -shows up in sysfs in several locations:
> +shows up in sysfs in several locations::
>  
>     /sys/devices/.../CTLR ... physical node for a given SPI controller
>  
> @@ -206,7 +209,8 @@ Linux needs several kinds of information to properly configure SPI devices.
>  That information is normally provided by board-specific code, even for
>  chips that do support some of automated discovery/enumeration.
>  
> -DECLARE CONTROLLERS
> +Declare Controllers
> +^^^^^^^^^^^^^^^^^^^
>  
>  The first kind of information is a list of what SPI controllers exist.
>  For System-on-Chip (SOC) based boards, these will usually be platform
> @@ -221,7 +225,7 @@ same basic controller setup code.  This is because most SOCs have several
>  SPI-capable controllers, and only the ones actually usable on a given
>  board should normally be set up and registered.
>  
> -So for example arch/.../mach-*/board-*.c files might have code like:
> +So for example arch/.../mach-*/board-*.c files might have code like::
>  
>  	#include <mach/spi.h>	/* for mysoc_spi_data */
>  
> @@ -238,7 +242,7 @@ So for example arch/.../mach-*/board-*.c files might have code like:
>  		...
>  	}
>  
> -And SOC-specific utility code might look something like:
> +And SOC-specific utility code might look something like::
>  
>  	#include <mach/spi.h>
>  
> @@ -269,8 +273,8 @@ same SOC controller is used.  For example, on one board SPI might use
>  an external clock, where another derives the SPI clock from current
>  settings of some master clock.
>  
> -
> -DECLARE SLAVE DEVICES
> +Declare Slave Devices
> +^^^^^^^^^^^^^^^^^^^^^
>  
>  The second kind of information is a list of what SPI slave devices exist
>  on the target board, often with some board-specific data needed for the
> @@ -278,7 +282,7 @@ driver to work correctly.
>  
>  Normally your arch/.../mach-*/board-*.c files would provide a small table
>  listing the SPI devices on each board.  (This would typically be only a
> -small handful.)  That might look like:
> +small handful.)  That might look like::
>  
>  	static struct ads7846_platform_data ads_info = {
>  		.vref_delay_usecs	= 100,
> @@ -316,7 +320,7 @@ not possible until the infrastructure knows how to deselect it.
>  
>  Then your board initialization code would register that table with the SPI
>  infrastructure, so that it's available later when the SPI master controller
> -driver is registered:
> +driver is registered::
>  
>  	spi_register_board_info(spi_board_info, ARRAY_SIZE(spi_board_info));
>  
> @@ -324,12 +328,13 @@ Like with other static board-specific setup, you won't unregister those.
>  
>  The widely used "card" style computers bundle memory, cpu, and little else
>  onto a card that's maybe just thirty square centimeters.  On such systems,
> -your arch/.../mach-.../board-*.c file would primarily provide information
> +your ``arch/.../mach-.../board-*.c`` file would primarily provide information
>  about the devices on the mainboard into which such a card is plugged.  That
>  certainly includes SPI devices hooked up through the card connectors!
>  
>  
> -NON-STATIC CONFIGURATIONS
> +Non-static Configurations
> +^^^^^^^^^^^^^^^^^^^^^^^^^
>  
>  Developer boards often play by different rules than product boards, and one
>  example is the potential need to hotplug SPI devices and/or controllers.
> @@ -349,7 +354,7 @@ How do I write an "SPI Protocol Driver"?
>  Most SPI drivers are currently kernel drivers, but there's also support
>  for userspace drivers.  Here we talk only about kernel drivers.
>  
> -SPI protocol drivers somewhat resemble platform device drivers:
> +SPI protocol drivers somewhat resemble platform device drivers::
>  
>  	static struct spi_driver CHIP_driver = {
>  		.driver = {
> @@ -367,6 +372,8 @@ device whose board_info gave a modalias of "CHIP".  Your probe() code
>  might look like this unless you're creating a device which is managing
>  a bus (appearing under /sys/class/spi_master).
>  
> +::
> +
>  	static int CHIP_probe(struct spi_device *spi)
>  	{
>  		struct CHIP			*chip;
> @@ -479,6 +486,8 @@ The main task of this type of driver is to provide an "spi_master".
>  Use spi_alloc_master() to allocate the master, and spi_master_get_devdata()
>  to get the driver-private data allocated for that device.
>  
> +::
> +
>  	struct spi_master	*master;
>  	struct CONTROLLER	*c;
>  
> @@ -503,7 +512,8 @@ If you need to remove your SPI controller driver, spi_unregister_master()
>  will reverse the effect of spi_register_master().
>  
>  
> -BUS NUMBERING
> +Bus Numbering
> +^^^^^^^^^^^^^
>  
>  Bus numbering is important, since that's how Linux identifies a given
>  SPI bus (shared SCK, MOSI, MISO).  Valid bus numbers start at zero.  On
> @@ -517,9 +527,10 @@ then be replaced by a dynamically assigned number. You'd then need to treat
>  this as a non-static configuration (see above).
>  
>  
> -SPI MASTER METHODS
> +SPI Master Methods
> +^^^^^^^^^^^^^^^^^^
>  
> -    master->setup(struct spi_device *spi)
> +``master->setup(struct spi_device *spi)``
>  	This sets up the device clock rate, SPI mode, and word sizes.
>  	Drivers may change the defaults provided by board_info, and then
>  	call spi_setup(spi) to invoke this routine.  It may sleep.
> @@ -528,37 +539,37 @@ SPI MASTER METHODS
>  	change them right away ... otherwise drivers could corrupt I/O
>  	that's in progress for other SPI devices.
>  
> -		** BUG ALERT:  for some reason the first version of
> -		** many spi_master drivers seems to get this wrong.
> -		** When you code setup(), ASSUME that the controller
> -		** is actively processing transfers for another device.
> +	.. note::
>  
> -    master->cleanup(struct spi_device *spi)
> +		BUG ALERT:  for some reason the first version of
> +		many spi_master drivers seems to get this wrong.
> +		When you code setup(), ASSUME that the controller
> +		is actively processing transfers for another device.
> +
> +``master->cleanup(struct spi_device *spi)``
>  	Your controller driver may use spi_device.controller_state to hold
>  	state it dynamically associates with that device.  If you do that,
>  	be sure to provide the cleanup() method to free that state.
>  
> -    master->prepare_transfer_hardware(struct spi_master *master)
> +``master->prepare_transfer_hardware(struct spi_master *master)``
>  	This will be called by the queue mechanism to signal to the driver
>  	that a message is coming in soon, so the subsystem requests the
>  	driver to prepare the transfer hardware by issuing this call.
>  	This may sleep.
>  
> -    master->unprepare_transfer_hardware(struct spi_master *master)
> +``master->unprepare_transfer_hardware(struct spi_master *master)``
>  	This will be called by the queue mechanism to signal to the driver
>  	that there are no more messages pending in the queue and it may
>  	relax the hardware (e.g. by power management calls). This may sleep.
>  
> -    master->transfer_one_message(struct spi_master *master,
> -				 struct spi_message *mesg)
> +``master->transfer_one_message(struct spi_master *master, struct spi_message *mesg)``
>  	The subsystem calls the driver to transfer a single message while
>  	queuing transfers that arrive in the meantime. When the driver is
>  	finished with this message, it must call
>  	spi_finalize_current_message() so the subsystem can issue the next
>  	message. This may sleep.
>  
> -    master->transfer_one(struct spi_master *master, struct spi_device *spi,
> -			 struct spi_transfer *transfer)
> +``master->transfer_one(struct spi_master *master, struct spi_device *spi, struct spi_transfer *transfer)``
>  	The subsystem calls the driver to transfer a single transfer while
>  	queuing transfers that arrive in the meantime. When the driver is
>  	finished with this transfer, it must call
> @@ -568,19 +579,20 @@ SPI MASTER METHODS
>  	not call your transfer_one callback.
>  
>  	Return values:
> -	negative errno: error
> -	0: transfer is finished
> -	1: transfer is still in progress
>  
> -    master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles,
> -			      u8 hold_clk_cycles, u8 inactive_clk_cycles)
> +	* negative errno: error
> +	* 0: transfer is finished
> +	* 1: transfer is still in progress
> +
> +``master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactive_clk_cycles)``
>  	This method allows SPI client drivers to request SPI master controller
>  	for configuring device specific CS setup, hold and inactive timing
>  	requirements.
>  
> -    DEPRECATED METHODS
> +Deprecated Methods
> +^^^^^^^^^^^^^^^^^^
>  
> -    master->transfer(struct spi_device *spi, struct spi_message *message)
> +``master->transfer(struct spi_device *spi, struct spi_message *message)``
>  	This must not sleep. Its responsibility is to arrange that the
>  	transfer happens and its complete() callback is issued. The two
>  	will normally happen later, after other transfers complete, and
> @@ -590,7 +602,8 @@ SPI MASTER METHODS
>  	implemented.
>  
>  
> -SPI MESSAGE QUEUE
> +SPI Message Queue
> +^^^^^^^^^^^^^^^^^
>  
>  If you are happy with the standard queueing mechanism provided by the
>  SPI subsystem, just implement the queued methods specified above. Using
> @@ -619,13 +632,13 @@ THANKS TO
>  Contributors to Linux-SPI discussions include (in alphabetical order,
>  by last name):
>  
> -Mark Brown
> -David Brownell
> -Russell King
> -Grant Likely
> -Dmitry Pervushin
> -Stephen Street
> -Mark Underwood
> -Andrew Victor
> -Linus Walleij
> -Vitaly Wool
> +- Mark Brown
> +- David Brownell
> +- Russell King
> +- Grant Likely
> +- Dmitry Pervushin
> +- Stephen Street
> +- Mark Underwood
> +- Andrew Victor
> +- Linus Walleij
> +- Vitaly Wool
> diff --git a/Documentation/spi/spidev b/Documentation/spi/spidev.rst
> similarity index 90%
> rename from Documentation/spi/spidev
> rename to Documentation/spi/spidev.rst
> index 3d14035b1766..f05dbc5ccdbc 100644
> --- a/Documentation/spi/spidev
> +++ b/Documentation/spi/spidev.rst
> @@ -1,7 +1,13 @@
> +=================
> +SPI userspace API
> +=================
> +
>  SPI devices have a limited userspace API, supporting basic half-duplex
>  read() and write() access to SPI slave devices.  Using ioctl() requests,
>  full duplex transfers and device I/O configuration are also available.
>  
> +::
> +
>  	#include <fcntl.h>
>  	#include <unistd.h>
>  	#include <sys/ioctl.h>
> @@ -39,14 +45,17 @@ device node with a "dev" attribute that will be understood by udev or mdev.
>  busybox; it's less featureful, but often enough.)  For a SPI device with
>  chipselect C on bus B, you should see:
>  
> -    /dev/spidevB.C ... character special device, major number 153 with
> +    /dev/spidevB.C ...
> +	character special device, major number 153 with
>  	a dynamically chosen minor device number.  This is the node
>  	that userspace programs will open, created by "udev" or "mdev".
>  
> -    /sys/devices/.../spiB.C ... as usual, the SPI device node will
> +    /sys/devices/.../spiB.C ...
> +	as usual, the SPI device node will
>  	be a child of its SPI master controller.
>  
> -    /sys/class/spidev/spidevB.C ... created when the "spidev" driver
> +    /sys/class/spidev/spidevB.C ...
> +	created when the "spidev" driver
>  	binds to that device.  (Directory or symlink, based on whether
>  	or not you enabled the "deprecated sysfs files" Kconfig option.)
>  
> @@ -80,7 +89,8 @@ the SPI_IOC_MESSAGE(N) request.
>  Several ioctl() requests let your driver read or override the device's current
>  settings for data transfer parameters:
>  
> -    SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ... pass a pointer to a byte which will
> +    SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ...
> +	pass a pointer to a byte which will
>  	return (RD) or assign (WR) the SPI transfer mode.  Use the constants
>  	SPI_MODE_0..SPI_MODE_3; or if you prefer you can combine SPI_CPOL
>  	(clock polarity, idle high iff this is set) or SPI_CPHA (clock phase,
> @@ -88,22 +98,26 @@ settings for data transfer parameters:
>  	Note that this request is limited to SPI mode flags that fit in a
>  	single byte.
>  
> -    SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ... pass a pointer to a uin32_t
> +    SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ...
> +	pass a pointer to a uin32_t
>  	which will return (RD) or assign (WR) the full SPI transfer mode,
>  	not limited to the bits that fit in one byte.
>  
> -    SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ... pass a pointer to a byte
> +    SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ...
> +	pass a pointer to a byte
>  	which will return (RD) or assign (WR) the bit justification used to
>  	transfer SPI words.  Zero indicates MSB-first; other values indicate
>  	the less common LSB-first encoding.  In both cases the specified value
>  	is right-justified in each word, so that unused (TX) or undefined (RX)
>  	bits are in the MSBs.
>  
> -    SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ... pass a pointer to
> +    SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ...
> +	pass a pointer to
>  	a byte which will return (RD) or assign (WR) the number of bits in
>  	each SPI transfer word.  The value zero signifies eight bits.
>  
> -    SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ... pass a pointer to a
> +    SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ...
> +	pass a pointer to a
>  	u32 which will return (RD) or assign (WR) the maximum SPI transfer
>  	speed, in Hz.  The controller can't necessarily assign that specific
>  	clock speed.
> diff --git a/drivers/iio/dummy/iio_simple_dummy.c b/drivers/iio/dummy/iio_simple_dummy.c
> index d28974ad9e0e..6cb02299a215 100644
> --- a/drivers/iio/dummy/iio_simple_dummy.c
> +++ b/drivers/iio/dummy/iio_simple_dummy.c
> @@ -695,7 +695,7 @@ static int iio_dummy_remove(struct iio_sw_device *swd)
>   * i2c:
>   * Documentation/i2c/writing-clients.rst
>   * spi:
> - * Documentation/spi/spi-summary
> + * Documentation/spi/spi-summary.rst
>   */
>  static const struct iio_sw_device_ops iio_dummy_device_ops = {
>  	.probe = iio_dummy_probe,
> diff --git a/drivers/spi/Kconfig b/drivers/spi/Kconfig
> index 3a1d8f1170de..d5a24fe983e7 100644
> --- a/drivers/spi/Kconfig
> +++ b/drivers/spi/Kconfig
> @@ -543,7 +543,7 @@ config SPI_PXA2XX
>  	help
>  	  This enables using a PXA2xx or Sodaville SSP port as a SPI master
>  	  controller. The driver can be configured to use any SSP port and
> -	  additional documentation can be found a Documentation/spi/pxa2xx.
> +	  additional documentation can be found a Documentation/spi/pxa2xx.rst.
>  
>  config SPI_PXA2XX_PCI
>  	def_tristate SPI_PXA2XX && PCI && COMMON_CLK
> diff --git a/drivers/spi/spi-butterfly.c b/drivers/spi/spi-butterfly.c
> index 8c77d1114ad3..7e71a351f3b7 100644
> --- a/drivers/spi/spi-butterfly.c
> +++ b/drivers/spi/spi-butterfly.c
> @@ -23,7 +23,7 @@
>   * with a battery powered AVR microcontroller and lots of goodies.  You
>   * can use GCC to develop firmware for this.
>   *
> - * See Documentation/spi/butterfly for information about how to build
> + * See Documentation/spi/butterfly.rst for information about how to build
>   * and use this custom parallel port cable.
>   */
>  
> diff --git a/drivers/spi/spi-lm70llp.c b/drivers/spi/spi-lm70llp.c
> index f18f912c9dea..174dba29b1dd 100644
> --- a/drivers/spi/spi-lm70llp.c
> +++ b/drivers/spi/spi-lm70llp.c
> @@ -34,7 +34,7 @@
>   * available (on page 4) here:
>   *  http://www.national.com/appinfo/tempsensors/files/LM70LLPEVALmanual.pdf
>   *
> - * Also see Documentation/spi/spi-lm70llp.  The SPI<->parport code here is
> + * Also see Documentation/spi/spi-lm70llp.rst.  The SPI<->parport code here is
>   * (heavily) based on spi-butterfly by David Brownell.
>   *
>   * The LM70 LLP connects to the PC parallel port in the following manner:
> diff --git a/include/linux/platform_data/sc18is602.h b/include/linux/platform_data/sc18is602.h
> index e066d3b0d6d8..0e91489edfe6 100644
> --- a/include/linux/platform_data/sc18is602.h
> +++ b/include/linux/platform_data/sc18is602.h
> @@ -4,7 +4,7 @@
>   *
>   * Copyright (C) 2012 Guenter Roeck <linux@roeck-us.net>
>   *
> - * For further information, see the Documentation/spi/spi-sc18is602 file.
> + * For further information, see the Documentation/spi/spi-sc18is602.rst file.
>   */
>  
>  /**


^ permalink raw reply

* Re: [PATCH 01/12] Documentation: move architectures together
From: Alex Shi @ 2019-07-14 15:21 UTC (permalink / raw)
  To: Jonathan Corbet
  Cc: linux-doc, linux-kernel, linux-stm32, linux-arm-kernel,
	linuxppc-dev, linux-riscv, linux-omap, linux-fbdev,
	linux-samsung-soc, linux-ia64, linux-mips, linux-parisc,
	linux-scsi, linux-s390, kvm, linux-sh
In-Reply-To: <20190712113427.62fa7ffc@lwn.net>

Hi Jon,

Thanks for quick response!

在 2019/7/13 上午1:34, Jonathan Corbet 写道:
> On Fri, 12 Jul 2019 10:20:07 +0800
> Alex Shi <alex.shi@linux.alibaba.com> wrote:
> 
>> There are many different archs in Documentation/ dir, it's better to
>> move them together in 'Documentation/arch' which follows from kernel source.
> 
> So this seems certain to collide badly with Mauro's RST-conversion monster
> patch set.

I don't mean that, sorry, and we can figure out if both of them are worthy to be picked up.

> 
> More to the point, though...if we are going to thrash up things this
> badly, we want to be sure that we're doing it right so we don't end up
> renaming everything again.  Grouping stuff into a new arch/ subdirectory
> adds a bit of order, but it doesn't do much toward trying to organize our
> documentation for its readers, and it doesn't help us to modernize the
> docs and get rid of the old, useless stuff.  A quick check shows that many
> of these files have seen no changes other than typo fixes since the
> beginning of the Git era.

Right, there is some docs which need to be update or even drop, and a reorder would be a timing to push each of arch maintainer to do something, isn't it? Anyway, reordering  documents like kernel source dir could be one of choices. :)

> 
> So, in my mind, this needs some thought.  Maybe we want a
> Documentation/arch in the end, but I'm not convinced that we should just
> create it and fill it with a snow shovel.  This might be a good thing to
> discuss at the kernel summit in September.

Thanks for considering, anyway, it could be a good start to get hands dirty whether the arch dir is needed. 

Thanks
Alex

^ permalink raw reply

* [PATCH 1/8] docs: conf.py: only use CJK if the font is available
From: Mauro Carvalho Chehab @ 2019-07-14 15:10 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet
In-Reply-To: <cover.1563115732.git.mchehab+samsung@kernel.org>

If we try to build a book with asian characters with XeLaTeX
and the font is not available, it will produce an error.

So, instead, add a logic at conf.py to detect if the proper
font is installed.

This will avoid an error while building the document, although
the result may not be readable.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/conf.py | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index fa0a42b47e62..a8fe845832bc 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -16,6 +16,8 @@ import sys
 import os
 import sphinx
 
+from subprocess import check_output
+
 # Get Sphinx version
 major, minor, patch = sphinx.version_info[:3]
 
@@ -276,13 +278,20 @@ latex_elements = {
         \\setsansfont{DejaVu Sans}
         \\setromanfont{DejaVu Serif}
         \\setmonofont{DejaVu Sans Mono}
+     '''
+}
 
+# At least one book (translations) may have Asian characters
+# with are only displayed if xeCJK is used
+
+cjk_cmd = check_output(['fc-list', '--format="%{family[0]}\n"']).decode('utf-8', 'ignore')
+if cjk_cmd.find("Noto Sans CJK SC") >= 0:
+    print ("enabling CJK for LaTeX builder")
+    latex_elements['preamble']  += '''
 	% This is needed for translations
         \\usepackage{xeCJK}
         \\setCJKmainfont{Noto Sans CJK SC}
-
      '''
-}
 
 # Fix reference escape troubles with Sphinx 1.4.x
 if major == 1 and minor > 3:
-- 
2.21.0


^ permalink raw reply related

* [PATCH 3/8] scripts/sphinx-pre-install: don't use LaTeX with CentOS 7
From: Mauro Carvalho Chehab @ 2019-07-14 15:10 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet
In-Reply-To: <cover.1563115732.git.mchehab+samsung@kernel.org>

There aren't enough texlive packages for LaTeX-based builds
to work on CentOS/RHEL <= 7.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 scripts/sphinx-pre-install | 68 ++++++++++++++++++++++++++++----------
 1 file changed, 50 insertions(+), 18 deletions(-)

diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index 101ddd00bf02..33efadd6c0b6 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -83,6 +83,17 @@ sub check_missing(%)
 	foreach my $prog (sort keys %missing) {
 		my $is_optional = $missing{$prog};
 
+		# At least on some LTS distros like CentOS 7, texlive doesn't
+		# provide all packages we need. When such distros are
+		# detected, we have to disable PDF output.
+		#
+		# So, we need to ignore the packages that distros would
+		# need for LaTeX to work
+		if ($is_optional == 2 && !$pdf) {
+			$optional--;
+			next;
+		}
+
 		if ($is_optional) {
 			print "Warning: better to also install \"$prog\".\n";
 		} else {
@@ -333,10 +344,10 @@ sub give_debian_hints()
 
 	if ($pdf) {
 		check_missing_file("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
-				   "fonts-dejavu", 1);
+				   "fonts-dejavu", 2);
 	}
 
-	check_program("dvipng", 1) if ($pdf);
+	check_program("dvipng", 2) if ($pdf);
 	check_missing(\%map);
 
 	return if (!$need && !$optional);
@@ -371,22 +382,40 @@ sub give_redhat_hints()
 	#
 	# Checks valid for RHEL/CentOS version 7.x.
 	#
+	my $old = 0;
+	my $rel;
+	$rel = $1 if ($system_release =~ /release\s+(\d+)/);
+
 	if (!($system_release =~ /Fedora/)) {
 		$map{"virtualenv"} = "python-virtualenv";
-	}
 
-	my $release;
+		if ($rel && $rel < 8) {
+			$old = 1;
+			$pdf = 0;
 
-	$release = $1 if ($system_release =~ /Fedora\s+release\s+(\d+)/);
+			printf("Note: texlive packages on RHEL/CENTOS <= 7 are incomplete. Can't support PDF output\n");
+			printf("If you want to build PDF, please read:\n");
+			printf("\thttps://www.systutorials.com/241660/how-to-install-tex-live-on-centos-7-linux/\n");
+		}
+	} else {
+		if ($rel && $rel < 26) {
+			$old = 1;
+		}
+	}
+	if (!$rel) {
+		printf("Couldn't identify release number\n");
+		$old = 1;
+		$pdf = 0;
+	}
 
-	check_rpm_missing(\@fedora26_opt_pkgs, 1) if ($pdf && $release >= 26);
-	check_rpm_missing(\@fedora_tex_pkgs, 1) if ($pdf);
-	check_missing_tex(1) if ($pdf);
+	check_rpm_missing(\@fedora26_opt_pkgs, 2) if ($pdf && !$old);
+	check_rpm_missing(\@fedora_tex_pkgs, 2) if ($pdf);
+	check_missing_tex(2) if ($pdf);
 	check_missing(\%map);
 
 	return if (!$need && !$optional);
 
-	if ($release >= 18) {
+	if (!$old) {
 		# dnf, for Fedora 18+
 		printf("You should run:\n\n\tsudo dnf install -y $install\n");
 	} else {
@@ -425,8 +454,8 @@ sub give_opensuse_hints()
 		"texlive-zapfding",
 	);
 
-	check_rpm_missing(\@suse_tex_pkgs, 1) if ($pdf);
-	check_missing_tex(1) if ($pdf);
+	check_rpm_missing(\@suse_tex_pkgs, 2) if ($pdf);
+	check_missing_tex(2) if ($pdf);
 	check_missing(\%map);
 
 	return if (!$need && !$optional);
@@ -450,7 +479,7 @@ sub give_mageia_hints()
 		"texlive-fontsextra",
 	);
 
-	check_rpm_missing(\@tex_pkgs, 1) if ($pdf);
+	check_rpm_missing(\@tex_pkgs, 2) if ($pdf);
 	check_missing(\%map);
 
 	return if (!$need && !$optional);
@@ -473,7 +502,8 @@ sub give_arch_linux_hints()
 		"texlive-latexextra",
 		"ttf-dejavu",
 	);
-	check_pacman_missing(\@archlinux_tex_pkgs, 1) if ($pdf);
+	check_pacman_missing(\@archlinux_tex_pkgs, 2) if ($pdf);
+
 	check_missing(\%map);
 
 	return if (!$need && !$optional);
@@ -492,7 +522,7 @@ sub give_gentoo_hints()
 	);
 
 	check_missing_file("/usr/share/fonts/dejavu/DejaVuSans.ttf",
-			   "media-fonts/dejavu", 1) if ($pdf);
+			   "media-fonts/dejavu", 2) if ($pdf);
 
 	check_missing(\%map);
 
@@ -560,7 +590,7 @@ sub check_distros()
 	my %map = (
 		"sphinx-build" => "sphinx"
 	);
-	check_missing_tex(1) if ($pdf);
+	check_missing_tex(2) if ($pdf);
 	check_missing(\%map);
 	print "I don't know distro $system_release.\n";
 	print "So, I can't provide you a hint with the install procedure.\n";
@@ -589,11 +619,13 @@ sub check_needs()
 	check_program("make", 0);
 	check_program("gcc", 0);
 	check_python_module("sphinx_rtd_theme", 1) if (!$virtualenv);
-	check_program("xelatex", 1) if ($pdf);
 	check_program("dot", 1);
 	check_program("convert", 1);
-	check_program("rsvg-convert", 1) if ($pdf);
-	check_program("latexmk", 1) if ($pdf);
+
+	# Extra PDF files - should use 2 for is_optional
+	check_program("xelatex", 2) if ($pdf);
+	check_program("rsvg-convert", 2) if ($pdf);
+	check_program("latexmk", 2) if ($pdf);
 
 	check_distros();
 
-- 
2.21.0


^ permalink raw reply related

* [PATCH 5/8] scripts/sphinx-pre-install: cleanup Gentoo checks
From: Mauro Carvalho Chehab @ 2019-07-14 15:10 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet
In-Reply-To: <cover.1563115732.git.mchehab+samsung@kernel.org>

On Gentoo, the portage changes for ImageMagick to work are
always suggested, even if already applied. While the two
extra commands should be harmless, add a check to avoid
reporting it without need.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 scripts/sphinx-pre-install | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index 8dc13fe95ffe..0a5c83aa5f44 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -533,8 +533,19 @@ sub give_gentoo_hints()
 	return if (!$need && !$optional);
 
 	printf("You should run:\n\n");
-	printf("\tsudo su -c 'echo \"media-gfx/imagemagick svg png\" > /etc/portage/package.use/imagemagick'\n");
-	printf("\tsudo su -c 'echo \"media-gfx/graphviz cairo pdf\" > /etc/portage/package.use/graphviz'\n");
+
+	my $imagemagick = "media-gfx/imagemagick svg png";
+	my $cairo = "media-gfx/graphviz cairo pdf";
+	my $portage_imagemagick = "/etc/portage/package.use/imagemagick";
+	my $portage_cairo = "/etc/portage/package.use/graphviz";
+
+	if (qx(cat $portage_imagemagick) ne "$imagemagick\n") {
+		printf("\tsudo su -c 'echo \"$imagemagick\" > $portage_imagemagick'\n")
+	}
+	if (qx(cat $portage_cairo) ne  "$cairo\n") {
+		printf("\tsudo su -c 'echo \"$cairo\" > $portage_cairo'\n");
+	}
+
 	printf("\tsudo emerge --ask $install\n");
 
 }
-- 
2.21.0


^ permalink raw reply related

* [PATCH 7/8] docs: load_config.py: avoid needing a conf.py just due to LaTeX docs
From: Mauro Carvalho Chehab @ 2019-07-14 15:10 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet
In-Reply-To: <cover.1563115732.git.mchehab+samsung@kernel.org>

Right now, for every directory that we need to have LaTeX output,
a conf.py file is required.

That causes an extra overhead and it is actually a hack, as
the latex_documents line there are usually a copy of the ones
that are there already at the main conf.py.

So, instead, re-use the global latex_documents var, just
adjusting the path to be relative ones.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/sphinx/load_config.py | 25 +++++++++++++++++++++++--
 1 file changed, 23 insertions(+), 2 deletions(-)

diff --git a/Documentation/sphinx/load_config.py b/Documentation/sphinx/load_config.py
index 301a21aa4f63..75f527ff4c95 100644
--- a/Documentation/sphinx/load_config.py
+++ b/Documentation/sphinx/load_config.py
@@ -21,6 +21,29 @@ def loadConfig(namespace):
         and os.path.normpath(namespace["__file__"]) != os.path.normpath(config_file) ):
         config_file = os.path.abspath(config_file)
 
+        # Let's avoid one conf.py file just due to latex_documents
+        start = config_file.find('Documentation/')
+	if start >= 0:
+	    start = config_file.find('/', start + 1)
+
+        end = config_file.rfind('/')
+        if start >= 0 and end > 0:
+            dir = config_file[start + 1:end]
+
+            print("source directory: %s" % dir)
+            new_latex_docs = []
+            latex_documents = namespace['latex_documents']
+
+            for l in latex_documents:
+                if l[0].find(dir) == 0:
+                    has = True
+                    fn = l[0][len(dir) + 1:]
+                    new_latex_docs.append((fn, l[1], l[2], l[3], l[4]))
+                    break
+
+            namespace['latex_documents'] = new_latex_docs
+
+        # If there is an extra conf.py file, load it
         if os.path.isfile(config_file):
             sys.stdout.write("load additional sphinx-config: %s\n" % config_file)
             config = namespace.copy()
@@ -28,5 +51,3 @@ def loadConfig(namespace):
             execfile_(config_file, config)
             del config['__file__']
             namespace.update(config)
-        else:
-            sys.stderr.write("WARNING: additional sphinx-config not found: %s\n" % config_file)
-- 
2.21.0


^ permalink raw reply related

* [PATCH 6/8] scripts/sphinx-pre-install: seek for Noto CJK fonts for pdf output
From: Mauro Carvalho Chehab @ 2019-07-14 15:10 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet
In-Reply-To: <cover.1563115732.git.mchehab+samsung@kernel.org>

The translations guide need Noto CJK fonts. So, add a logic that
would suggest its install for distros.

It also fix a few other issues while testing the script
with several distributions.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 scripts/sphinx-pre-install | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index 0a5c83aa5f44..3b638c0e1a4f 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -345,6 +345,9 @@ sub give_debian_hints()
 	if ($pdf) {
 		check_missing_file("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
 				   "fonts-dejavu", 2);
+
+		check_missing_file("/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc",
+				   "fonts-noto-cjk", 2);
 	}
 
 	check_program("dvipng", 2) if ($pdf);
@@ -374,6 +377,7 @@ sub give_redhat_hints()
 	my @fedora_tex_pkgs = (
 		"texlive-collection-fontsrecommended",
 		"texlive-collection-latex",
+		"texlive-xecjk",
 		"dejavu-sans-fonts",
 		"dejavu-serif-fonts",
 		"dejavu-sans-mono-fonts",
@@ -408,6 +412,11 @@ sub give_redhat_hints()
 		$pdf = 0;
 	}
 
+	if ($pdf) {
+		check_missing_file("/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc",
+				   "google-noto-sans-cjk-ttc-fonts", 2);
+	}
+
 	check_rpm_missing(\@fedora26_opt_pkgs, 2) if ($pdf && !$old);
 	check_rpm_missing(\@fedora_tex_pkgs, 2) if ($pdf);
 	check_missing_tex(2) if ($pdf);
@@ -456,6 +465,11 @@ sub give_opensuse_hints()
 
 	$map{"latexmk"} = "texlive-latexmk-bin";
 
+	# FIXME: add support for installing CJK fonts
+	#
+	# I tried hard, but was unable to find a way to install
+	# "Noto Sans CJK SC" on openSUSE
+
 	check_rpm_missing(\@suse_tex_pkgs, 2) if ($pdf);
 	check_missing_tex(2) if ($pdf);
 	check_missing(\%map);
@@ -483,6 +497,11 @@ sub give_mageia_hints()
 
 	$map{"latexmk"} = "texlive-collection-basic";
 
+	if ($pdf) {
+		check_missing_file("/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc",
+				   "google-noto-sans-cjk-ttc-fonts", 2);
+	}
+
 	check_rpm_missing(\@tex_pkgs, 2) if ($pdf);
 	check_missing(\%map);
 
@@ -508,6 +527,11 @@ sub give_arch_linux_hints()
 	);
 	check_pacman_missing(\@archlinux_tex_pkgs, 2) if ($pdf);
 
+	if ($pdf) {
+		check_missing_file("/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc",
+				   "noto-fonts-cjk", 2);
+	}
+
 	check_missing(\%map);
 
 	return if (!$need && !$optional);
@@ -528,6 +552,11 @@ sub give_gentoo_hints()
 	check_missing_file("/usr/share/fonts/dejavu/DejaVuSans.ttf",
 			   "media-fonts/dejavu", 2) if ($pdf);
 
+	if ($pdf) {
+		check_missing_file("/usr/share/fonts/noto-cjk/NotoSansCJKsc-Regular.otf",
+				   "media-fonts/noto-cjk", 2);
+	}
+
 	check_missing(\%map);
 
 	return if (!$need && !$optional);
-- 
2.21.0


^ permalink raw reply related

* [PATCH 8/8] docs: remove extra conf.py files
From: Mauro Carvalho Chehab @ 2019-07-14 15:10 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, Herbert Xu, David S. Miller, David Airlie,
	Daniel Vetter, Maarten Lankhorst, Maxime Ripard, Sean Paul,
	Dmitry Torokhov, Yoshinori Sato, Rich Felker, Jaroslav Kysela,
	Takashi Iwai, Thomas Gleixner, Ingo Molnar, Borislav Petkov,
	H. Peter Anvin, x86, linux-crypto, dri-devel, linux-input, netdev,
	linux-sh, alsa-devel
In-Reply-To: <cover.1563115732.git.mchehab+samsung@kernel.org>

Now that the latex_documents are handled automatically, we can
remove those extra conf.py files.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/admin-guide/conf.py      | 10 ----------
 Documentation/core-api/conf.py         | 10 ----------
 Documentation/crypto/conf.py           | 10 ----------
 Documentation/dev-tools/conf.py        | 10 ----------
 Documentation/doc-guide/conf.py        | 10 ----------
 Documentation/driver-api/80211/conf.py | 10 ----------
 Documentation/driver-api/conf.py       | 10 ----------
 Documentation/driver-api/pm/conf.py    | 10 ----------
 Documentation/filesystems/conf.py      | 10 ----------
 Documentation/gpu/conf.py              | 10 ----------
 Documentation/input/conf.py            | 10 ----------
 Documentation/kernel-hacking/conf.py   | 10 ----------
 Documentation/maintainer/conf.py       | 10 ----------
 Documentation/media/conf.py            | 12 ------------
 Documentation/networking/conf.py       | 10 ----------
 Documentation/process/conf.py          | 10 ----------
 Documentation/sh/conf.py               | 10 ----------
 Documentation/sound/conf.py            | 10 ----------
 Documentation/userspace-api/conf.py    | 10 ----------
 Documentation/vm/conf.py               | 10 ----------
 Documentation/x86/conf.py              | 10 ----------
 21 files changed, 212 deletions(-)
 delete mode 100644 Documentation/admin-guide/conf.py
 delete mode 100644 Documentation/core-api/conf.py
 delete mode 100644 Documentation/crypto/conf.py
 delete mode 100644 Documentation/dev-tools/conf.py
 delete mode 100644 Documentation/doc-guide/conf.py
 delete mode 100644 Documentation/driver-api/80211/conf.py
 delete mode 100644 Documentation/driver-api/conf.py
 delete mode 100644 Documentation/driver-api/pm/conf.py
 delete mode 100644 Documentation/filesystems/conf.py
 delete mode 100644 Documentation/gpu/conf.py
 delete mode 100644 Documentation/input/conf.py
 delete mode 100644 Documentation/kernel-hacking/conf.py
 delete mode 100644 Documentation/maintainer/conf.py
 delete mode 100644 Documentation/media/conf.py
 delete mode 100644 Documentation/networking/conf.py
 delete mode 100644 Documentation/process/conf.py
 delete mode 100644 Documentation/sh/conf.py
 delete mode 100644 Documentation/sound/conf.py
 delete mode 100644 Documentation/userspace-api/conf.py
 delete mode 100644 Documentation/vm/conf.py
 delete mode 100644 Documentation/x86/conf.py

diff --git a/Documentation/admin-guide/conf.py b/Documentation/admin-guide/conf.py
deleted file mode 100644
index 86f738953799..000000000000
--- a/Documentation/admin-guide/conf.py
+++ /dev/null
@@ -1,10 +0,0 @@
-# -*- coding: utf-8; mode: python -*-
-
-project = 'Linux Kernel User Documentation'
-
-tags.add("subproject")
-
-latex_documents = [
-    ('index', 'linux-user.tex', 'Linux Kernel User Documentation',
-     'The kernel development community', 'manual'),
-]
diff --git a/Documentation/core-api/conf.py b/Documentation/core-api/conf.py
deleted file mode 100644
index db1f7659f3da..000000000000
--- a/Documentation/core-api/conf.py
+++ /dev/null
@@ -1,10 +0,0 @@
-# -*- coding: utf-8; mode: python -*-
-
-project = "Core-API Documentation"
-
-tags.add("subproject")
-
-latex_documents = [
-    ('index', 'core-api.tex', project,
-     'The kernel development community', 'manual'),
-]
diff --git a/Documentation/crypto/conf.py b/Documentation/crypto/conf.py
deleted file mode 100644
index 4335d251ddf3..000000000000
--- a/Documentation/crypto/conf.py
+++ /dev/null
@@ -1,10 +0,0 @@
-# -*- coding: utf-8; mode: python -*-
-
-project = 'Linux Kernel Crypto API'
-
-tags.add("subproject")
-
-latex_documents = [
-    ('index', 'crypto-api.tex', 'Linux Kernel Crypto API manual',
-     'The kernel development community', 'manual'),
-]
diff --git a/Documentation/dev-tools/conf.py b/Documentation/dev-tools/conf.py
deleted file mode 100644
index 7faafa3f7888..000000000000
--- a/Documentation/dev-tools/conf.py
+++ /dev/null
@@ -1,10 +0,0 @@
-# -*- coding: utf-8; mode: python -*-
-
-project = "Development tools for the kernel"
-
-tags.add("subproject")
-
-latex_documents = [
-    ('index', 'dev-tools.tex', project,
-     'The kernel development community', 'manual'),
-]
diff --git a/Documentation/doc-guide/conf.py b/Documentation/doc-guide/conf.py
deleted file mode 100644
index fd3731182d5a..000000000000
--- a/Documentation/doc-guide/conf.py
+++ /dev/null
@@ -1,10 +0,0 @@
-# -*- coding: utf-8; mode: python -*-
-
-project = 'Linux Kernel Documentation Guide'
-
-tags.add("subproject")
-
-latex_documents = [
-    ('index', 'kernel-doc-guide.tex', 'Linux Kernel Documentation Guide',
-     'The kernel development community', 'manual'),
-]
diff --git a/Documentation/driver-api/80211/conf.py b/Documentation/driver-api/80211/conf.py
deleted file mode 100644
index 4424b4b0b9c3..000000000000
--- a/Documentation/driver-api/80211/conf.py
+++ /dev/null
@@ -1,10 +0,0 @@
-# -*- coding: utf-8; mode: python -*-
-
-project = "Linux 802.11 Driver Developer's Guide"
-
-tags.add("subproject")
-
-latex_documents = [
-    ('index', '80211.tex', project,
-     'The kernel development community', 'manual'),
-]
diff --git a/Documentation/driver-api/conf.py b/Documentation/driver-api/conf.py
deleted file mode 100644
index 202726d20088..000000000000
--- a/Documentation/driver-api/conf.py
+++ /dev/null
@@ -1,10 +0,0 @@
-# -*- coding: utf-8; mode: python -*-
-
-project = "The Linux driver implementer's API guide"
-
-tags.add("subproject")
-
-latex_documents = [
-    ('index', 'driver-api.tex', project,
-     'The kernel development community', 'manual'),
-]
diff --git a/Documentation/driver-api/pm/conf.py b/Documentation/driver-api/pm/conf.py
deleted file mode 100644
index a89fac11272f..000000000000
--- a/Documentation/driver-api/pm/conf.py
+++ /dev/null
@@ -1,10 +0,0 @@
-# -*- coding: utf-8; mode: python -*-
-
-project = "Device Power Management"
-
-tags.add("subproject")
-
-latex_documents = [
-    ('index', 'pm.tex', project,
-     'The kernel development community', 'manual'),
-]
diff --git a/Documentation/filesystems/conf.py b/Documentation/filesystems/conf.py
deleted file mode 100644
index ea44172af5c4..000000000000
--- a/Documentation/filesystems/conf.py
+++ /dev/null
@@ -1,10 +0,0 @@
-# -*- coding: utf-8; mode: python -*-
-
-project = "Linux Filesystems API"
-
-tags.add("subproject")
-
-latex_documents = [
-    ('index', 'filesystems.tex', project,
-     'The kernel development community', 'manual'),
-]
diff --git a/Documentation/gpu/conf.py b/Documentation/gpu/conf.py
deleted file mode 100644
index 1757b040fb32..000000000000
--- a/Documentation/gpu/conf.py
+++ /dev/null
@@ -1,10 +0,0 @@
-# -*- coding: utf-8; mode: python -*-
-
-project = "Linux GPU Driver Developer's Guide"
-
-tags.add("subproject")
-
-latex_documents = [
-    ('index', 'gpu.tex', project,
-     'The kernel development community', 'manual'),
-]
diff --git a/Documentation/input/conf.py b/Documentation/input/conf.py
deleted file mode 100644
index d2352fdc92ed..000000000000
--- a/Documentation/input/conf.py
+++ /dev/null
@@ -1,10 +0,0 @@
-# -*- coding: utf-8; mode: python -*-
-
-project = "The Linux input driver subsystem"
-
-tags.add("subproject")
-
-latex_documents = [
-    ('index', 'linux-input.tex', project,
-     'The kernel development community', 'manual'),
-]
diff --git a/Documentation/kernel-hacking/conf.py b/Documentation/kernel-hacking/conf.py
deleted file mode 100644
index 3d8acf0f33ad..000000000000
--- a/Documentation/kernel-hacking/conf.py
+++ /dev/null
@@ -1,10 +0,0 @@
-# -*- coding: utf-8; mode: python -*-
-
-project = "Kernel Hacking Guides"
-
-tags.add("subproject")
-
-latex_documents = [
-    ('index', 'kernel-hacking.tex', project,
-     'The kernel development community', 'manual'),
-]
diff --git a/Documentation/maintainer/conf.py b/Documentation/maintainer/conf.py
deleted file mode 100644
index 81e9eb7a7884..000000000000
--- a/Documentation/maintainer/conf.py
+++ /dev/null
@@ -1,10 +0,0 @@
-# -*- coding: utf-8; mode: python -*-
-
-project = 'Linux Kernel Development Documentation'
-
-tags.add("subproject")
-
-latex_documents = [
-    ('index', 'maintainer.tex', 'Linux Kernel Development Documentation',
-     'The kernel development community', 'manual'),
-]
diff --git a/Documentation/media/conf.py b/Documentation/media/conf.py
deleted file mode 100644
index 1f194fcd2cae..000000000000
--- a/Documentation/media/conf.py
+++ /dev/null
@@ -1,12 +0,0 @@
-# -*- coding: utf-8; mode: python -*-
-
-# SPDX-License-Identifier: GPL-2.0
-
-project = 'Linux Media Subsystem Documentation'
-
-tags.add("subproject")
-
-latex_documents = [
-    ('index', 'media.tex', 'Linux Media Subsystem Documentation',
-     'The kernel development community', 'manual'),
-]
diff --git a/Documentation/networking/conf.py b/Documentation/networking/conf.py
deleted file mode 100644
index 40f69e67a883..000000000000
--- a/Documentation/networking/conf.py
+++ /dev/null
@@ -1,10 +0,0 @@
-# -*- coding: utf-8; mode: python -*-
-
-project = "Linux Networking Documentation"
-
-tags.add("subproject")
-
-latex_documents = [
-    ('index', 'networking.tex', project,
-     'The kernel development community', 'manual'),
-]
diff --git a/Documentation/process/conf.py b/Documentation/process/conf.py
deleted file mode 100644
index 1b01a80ad9ce..000000000000
--- a/Documentation/process/conf.py
+++ /dev/null
@@ -1,10 +0,0 @@
-# -*- coding: utf-8; mode: python -*-
-
-project = 'Linux Kernel Development Documentation'
-
-tags.add("subproject")
-
-latex_documents = [
-    ('index', 'process.tex', 'Linux Kernel Development Documentation',
-     'The kernel development community', 'manual'),
-]
diff --git a/Documentation/sh/conf.py b/Documentation/sh/conf.py
deleted file mode 100644
index 1eb684a13ac8..000000000000
--- a/Documentation/sh/conf.py
+++ /dev/null
@@ -1,10 +0,0 @@
-# -*- coding: utf-8; mode: python -*-
-
-project = "SuperH architecture implementation manual"
-
-tags.add("subproject")
-
-latex_documents = [
-    ('index', 'sh.tex', project,
-     'The kernel development community', 'manual'),
-]
diff --git a/Documentation/sound/conf.py b/Documentation/sound/conf.py
deleted file mode 100644
index 3f1fc5e74e7b..000000000000
--- a/Documentation/sound/conf.py
+++ /dev/null
@@ -1,10 +0,0 @@
-# -*- coding: utf-8; mode: python -*-
-
-project = "Linux Sound Subsystem Documentation"
-
-tags.add("subproject")
-
-latex_documents = [
-    ('index', 'sound.tex', project,
-     'The kernel development community', 'manual'),
-]
diff --git a/Documentation/userspace-api/conf.py b/Documentation/userspace-api/conf.py
deleted file mode 100644
index 2eaf59f844e5..000000000000
--- a/Documentation/userspace-api/conf.py
+++ /dev/null
@@ -1,10 +0,0 @@
-# -*- coding: utf-8; mode: python -*-
-
-project = "The Linux kernel user-space API guide"
-
-tags.add("subproject")
-
-latex_documents = [
-    ('index', 'userspace-api.tex', project,
-     'The kernel development community', 'manual'),
-]
diff --git a/Documentation/vm/conf.py b/Documentation/vm/conf.py
deleted file mode 100644
index 3b0b601af558..000000000000
--- a/Documentation/vm/conf.py
+++ /dev/null
@@ -1,10 +0,0 @@
-# -*- coding: utf-8; mode: python -*-
-
-project = "Linux Memory Management Documentation"
-
-tags.add("subproject")
-
-latex_documents = [
-    ('index', 'memory-management.tex', project,
-     'The kernel development community', 'manual'),
-]
diff --git a/Documentation/x86/conf.py b/Documentation/x86/conf.py
deleted file mode 100644
index 33c5c3142e20..000000000000
--- a/Documentation/x86/conf.py
+++ /dev/null
@@ -1,10 +0,0 @@
-# -*- coding: utf-8; mode: python -*-
-
-project = "X86 architecture specific documentation"
-
-tags.add("subproject")
-
-latex_documents = [
-    ('index', 'x86.tex', project,
-     'The kernel development community', 'manual'),
-]
-- 
2.21.0


^ permalink raw reply related

* [PATCH 0/8] docs: some improvements when producing PDF files
From: Mauro Carvalho Chehab @ 2019-07-14 15:10 UTC (permalink / raw)
  To: Linux Doc Mailing List, Jonathan Corbet
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Herbert Xu, netdev, Sean Paul, Maarten Lankhorst, Rich Felker,
	Takashi Iwai, Daniel Vetter, x86, alsa-devel, Maxime Ripard,
	linux-sh, David Airlie, linux-crypto, Jaroslav Kysela, dri-devel,
	Yoshinori Sato, Ingo Molnar, Borislav Petkov, David S. Miller,
	linux-input, H. Peter Anvin, Dmitry Torokhov, Thomas Gleixner

Hi Jon,

This series addresses your concerns related to CJK fonts that are
needed for translations.pdf.

It touches only the documentation build system, not the docs
themselves.

It ended to be bigger than I originally foreseen, as I found several issues
when running "make pdfdocs" for the distros that are recognized by
the  scripts/sphinx-pre-install script.

It also took a lot of time, as I tested it with several VMs (each
one updated to latest packages):

- Fedora 30, CentOS 7, Mageia 7, ArchLinux, Ubuntu 18.04, Gentoo, 
  OpenSuse Tumbleweed.

Patch 1 addresses an issue that could be related to the fact that I
don't use openSUSE. Basically, I was unable to find the right package
for texlive to use CJK fonts on openSUSE. [1]. So, the first patch on this
series adds a workaround: if the needed CJK font is not found on a
system, conf.py won't use xeCjk extension. That sounds a good
thing to have, as other distros may not package it, or maybe the
one building the doc is not that interested on translations.pdf file;

[1] I actually found some, but they are not recognized with the
    font name conf.py is expecting ("Noto Sans CJK SC"). Perhaps
    SUSE uses a different name for those fonts?

Patch 2 fixes the logic with recognizes CentOS/RHEL;

Patch 3 is another workaround: CentOS 7 (and similar distros) don't
package all texlive packages we need. So, it just ignores PDF when
recommending packages on such distros, and point to a URL with
explains how to install TexLive outside distro-specific package
management (for the brave enough people);

Patch 4 fixes latexmk dependency on a few distros;

Patch 5 suppreses a Gentoo specific instruction if the user already
followed in the past;

Patch 6 is the one that actually does what you requested.

Patch 7 solves an issue when SPHINXDIRS is used with make pdfdocs:
right now, using it will produce a lot of warnings and won't do anything,
if a dir-specific conf.py file is not found. With the patch, latex_documents
are now properly updated when SPHINXDIRS is used.

Patch 8 is a cleanup: with patch 7 applied, we don't need to have anymore
any conf.py file due to pdfdocs. 

With regard to the load_config.py extension, It keeps accepting custom
configuration. That's helpful if someone wants, for example, to have
something like:

	Documentation/media/conf_nitpick.py

with would enable extra nitpick options if one wants that.

-

Jon,

Please let me know if you prefer if I submit those together with the big
pile of doc files I have, or if you prefer adding (some of?) them on your
tree after the merge window.

Regards,
Mauro

Mauro Carvalho Chehab (8):
  docs: conf.py: only use CJK if the font is available
  scripts/sphinx-pre-install: fix script for RHEL/CentOS
  scripts/sphinx-pre-install: don't use LaTeX with CentOS 7
  scripts/sphinx-pre-install: fix latexmk dependencies
  scripts/sphinx-pre-install: cleanup Gentoo checks
  scripts/sphinx-pre-install: seek for Noto CJK fonts for pdf output
  docs: load_config.py: avoid needing a conf.py just due to LaTeX docs
  docs: remove extra conf.py files

 Documentation/admin-guide/conf.py      |  10 ---
 Documentation/conf.py                  |  13 ++-
 Documentation/core-api/conf.py         |  10 ---
 Documentation/crypto/conf.py           |  10 ---
 Documentation/dev-tools/conf.py        |  10 ---
 Documentation/doc-guide/conf.py        |  10 ---
 Documentation/driver-api/80211/conf.py |  10 ---
 Documentation/driver-api/conf.py       |  10 ---
 Documentation/driver-api/pm/conf.py    |  10 ---
 Documentation/filesystems/conf.py      |  10 ---
 Documentation/gpu/conf.py              |  10 ---
 Documentation/input/conf.py            |  10 ---
 Documentation/kernel-hacking/conf.py   |  10 ---
 Documentation/maintainer/conf.py       |  10 ---
 Documentation/media/conf.py            |  12 ---
 Documentation/networking/conf.py       |  10 ---
 Documentation/process/conf.py          |  10 ---
 Documentation/sh/conf.py               |  10 ---
 Documentation/sound/conf.py            |  10 ---
 Documentation/sphinx/load_config.py    |  25 +++++-
 Documentation/userspace-api/conf.py    |  10 ---
 Documentation/vm/conf.py               |  10 ---
 Documentation/x86/conf.py              |  10 ---
 scripts/sphinx-pre-install             | 118 ++++++++++++++++++++-----
 24 files changed, 131 insertions(+), 237 deletions(-)
 delete mode 100644 Documentation/admin-guide/conf.py
 delete mode 100644 Documentation/core-api/conf.py
 delete mode 100644 Documentation/crypto/conf.py
 delete mode 100644 Documentation/dev-tools/conf.py
 delete mode 100644 Documentation/doc-guide/conf.py
 delete mode 100644 Documentation/driver-api/80211/conf.py
 delete mode 100644 Documentation/driver-api/conf.py
 delete mode 100644 Documentation/driver-api/pm/conf.py
 delete mode 100644 Documentation/filesystems/conf.py
 delete mode 100644 Documentation/gpu/conf.py
 delete mode 100644 Documentation/input/conf.py
 delete mode 100644 Documentation/kernel-hacking/conf.py
 delete mode 100644 Documentation/maintainer/conf.py
 delete mode 100644 Documentation/media/conf.py
 delete mode 100644 Documentation/networking/conf.py
 delete mode 100644 Documentation/process/conf.py
 delete mode 100644 Documentation/sh/conf.py
 delete mode 100644 Documentation/sound/conf.py
 delete mode 100644 Documentation/userspace-api/conf.py
 delete mode 100644 Documentation/vm/conf.py
 delete mode 100644 Documentation/x86/conf.py

-- 
2.21.0

^ permalink raw reply

* [PATCH 2/8] scripts/sphinx-pre-install: fix script for RHEL/CentOS
From: Mauro Carvalho Chehab @ 2019-07-14 15:10 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet
In-Reply-To: <cover.1563115732.git.mchehab+samsung@kernel.org>

There's a missing parenthesis at the script, with causes it to
fail to detect non-Fedora releases (e. g. RHEL/CentOS).

Tested with Centos 7.6.1810.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 scripts/sphinx-pre-install | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index f230e65329a2..101ddd00bf02 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -371,7 +371,7 @@ sub give_redhat_hints()
 	#
 	# Checks valid for RHEL/CentOS version 7.x.
 	#
-	if (! $system_release =~ /Fedora/) {
+	if (!($system_release =~ /Fedora/)) {
 		$map{"virtualenv"} = "python-virtualenv";
 	}
 
-- 
2.21.0


^ permalink raw reply related

* [PATCH 4/8] scripts/sphinx-pre-install: fix latexmk dependencies
From: Mauro Carvalho Chehab @ 2019-07-14 15:10 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet
In-Reply-To: <cover.1563115732.git.mchehab+samsung@kernel.org>

The name of the package with carries latexmk is different
on two distros:

- On OpenSUSE, latexmk is packaged as "texlive-latexmk-bin"
- On Mageia, latexmk is packaged at "texlive-collection-basic"

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 scripts/sphinx-pre-install | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index 33efadd6c0b6..8dc13fe95ffe 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -454,6 +454,8 @@ sub give_opensuse_hints()
 		"texlive-zapfding",
 	);
 
+	$map{"latexmk"} = "texlive-latexmk-bin";
+
 	check_rpm_missing(\@suse_tex_pkgs, 2) if ($pdf);
 	check_missing_tex(2) if ($pdf);
 	check_missing(\%map);
@@ -479,6 +481,8 @@ sub give_mageia_hints()
 		"texlive-fontsextra",
 	);
 
+	$map{"latexmk"} = "texlive-collection-basic";
+
 	check_rpm_missing(\@tex_pkgs, 2) if ($pdf);
 	check_missing(\%map);
 
-- 
2.21.0


^ permalink raw reply related

* Re: [PATCH v8] Documentation: filesystem: Convert xfs.txt to ReST
From: Sheriff Esseson @ 2019-07-14 12:58 UTC (permalink / raw)
  To: skhan
  Cc: darrick.wong, linux-xfs, corbet, linux-doc, linux-kernel,
	linux-kernel-mentees, sheriffesseson

Move xfs.txt to admin-guide, convert xfs.txt to ReST and broken references

Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
---

changes in v8:
	- fix table of Deprecated and Removed options.

 Documentation/admin-guide/index.rst           |   1 +
 .../xfs.txt => admin-guide/xfs.rst}           | 132 +++++++++---------
 Documentation/filesystems/dax.txt             |   2 +-
 MAINTAINERS                                   |   2 +-
 4 files changed, 67 insertions(+), 70 deletions(-)
 rename Documentation/{filesystems/xfs.txt => admin-guide/xfs.rst} (80%)

diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 24fbe0568eff..0615ea3a744c 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -70,6 +70,7 @@ configure specific aspects of kernel behavior to your liking.
    ras
    bcache
    ext4
+   xfs
    binderfs
    pm/index
    thunderbolt
diff --git a/Documentation/filesystems/xfs.txt b/Documentation/admin-guide/xfs.rst
similarity index 80%
rename from Documentation/filesystems/xfs.txt
rename to Documentation/admin-guide/xfs.rst
index a5cbb5e0e3db..e76665a8f2f2 100644
--- a/Documentation/filesystems/xfs.txt
+++ b/Documentation/admin-guide/xfs.rst
@@ -1,4 +1,6 @@
+.. SPDX-License-Identifier: GPL-2.0
 
+======================
 The SGI XFS Filesystem
 ======================
 
@@ -18,8 +20,6 @@ Mount Options
 =============
 
 When mounting an XFS filesystem, the following options are accepted.
-For boolean mount options, the names with the (*) suffix is the
-default behaviour.
 
   allocsize=size
 	Sets the buffered I/O end-of-file preallocation size when
@@ -31,46 +31,43 @@ default behaviour.
 	preallocation size, which uses a set of heuristics to
 	optimise the preallocation size based on the current
 	allocation patterns within the file and the access patterns
-	to the file. Specifying a fixed allocsize value turns off
+	to the file. Specifying a fixed ``allocsize`` value turns off
 	the dynamic behaviour.
 
-  attr2
-  noattr2
+  attr2 or noattr2
 	The options enable/disable an "opportunistic" improvement to
 	be made in the way inline extended attributes are stored
 	on-disk.  When the new form is used for the first time when
-	attr2 is selected (either when setting or removing extended
+	``attr2`` is selected (either when setting or removing extended
 	attributes) the on-disk superblock feature bit field will be
 	updated to reflect this format being in use.
 
 	The default behaviour is determined by the on-disk feature
-	bit indicating that attr2 behaviour is active. If either
-	mount option it set, then that becomes the new default used
+	bit indicating that ``attr2`` behaviour is active. If either
+	mount option is set, then that becomes the new default used
 	by the filesystem.
 
-	CRC enabled filesystems always use the attr2 format, and so
-	will reject the noattr2 mount option if it is set.
+	CRC enabled filesystems always use the ``attr2`` format, and so
+	will reject the ``noattr2`` mount option if it is set.
 
-  discard
-  nodiscard (*)
+  discard or nodiscard (default)
 	Enable/disable the issuing of commands to let the block
 	device reclaim space freed by the filesystem.  This is
 	useful for SSD devices, thinly provisioned LUNs and virtual
 	machine images, but may have a performance impact.
 
-	Note: It is currently recommended that you use the fstrim
-	application to discard unused blocks rather than the discard
+	Note: It is currently recommended that you use the ``fstrim``
+	application to ``discard`` unused blocks rather than the ``discard``
 	mount option because the performance impact of this option
 	is quite severe.
 
-  grpid/bsdgroups
-  nogrpid/sysvgroups (*)
+  grpid/bsdgroups or nogrpid/sysvgroups (default)
 	These options define what group ID a newly created file
-	gets.  When grpid is set, it takes the group ID of the
+	gets.  When ``grpid`` is set, it takes the group ID of the
 	directory in which it is created; otherwise it takes the
-	fsgid of the current process, unless the directory has the
-	setgid bit set, in which case it takes the gid from the
-	parent directory, and also gets the setgid bit set if it is
+	``fsgid`` of the current process, unless the directory has the
+	``setgid`` bit set, in which case it takes the ``gid`` from the
+	parent directory, and also gets the ``setgid`` bit set if it is
 	a directory itself.
 
   filestreams
@@ -78,46 +75,42 @@ default behaviour.
 	across the entire filesystem rather than just on directories
 	configured to use it.
 
-  ikeep
-  noikeep (*)
-	When ikeep is specified, XFS does not delete empty inode
-	clusters and keeps them around on disk.  When noikeep is
+  ikeep or noikeep (default)
+	When ``ikeep`` is specified, XFS does not delete empty inode
+	clusters and keeps them around on disk.  When ``noikeep`` is
 	specified, empty inode clusters are returned to the free
 	space pool.
 
-  inode32
-  inode64 (*)
-	When inode32 is specified, it indicates that XFS limits
+  inode32 or inode64 (default)
+	When ``inode32`` is specified, it indicates that XFS limits
 	inode creation to locations which will not result in inode
 	numbers with more than 32 bits of significance.
 
-	When inode64 is specified, it indicates that XFS is allowed
+	When ``inode64`` is specified, it indicates that XFS is allowed
 	to create inodes at any location in the filesystem,
 	including those which will result in inode numbers occupying
-	more than 32 bits of significance. 
+	more than 32 bits of significance.
 
-	inode32 is provided for backwards compatibility with older
+	``inode32`` is provided for backwards compatibility with older
 	systems and applications, since 64 bits inode numbers might
 	cause problems for some applications that cannot handle
 	large inode numbers.  If applications are in use which do
-	not handle inode numbers bigger than 32 bits, the inode32
+	not handle inode numbers bigger than 32 bits, the ``inode32``
 	option should be specified.
 
-
-  largeio
-  nolargeio (*)
-	If "nolargeio" is specified, the optimal I/O reported in
-	st_blksize by stat(2) will be as small as possible to allow
+  largeio or nolargeio (default)
+	If ``nolargeio`` is specified, the optimal I/O reported in
+	``st_blksize`` by **stat(2)** will be as small as possible to allow
 	user applications to avoid inefficient read/modify/write
 	I/O.  This is typically the page size of the machine, as
 	this is the granularity of the page cache.
 
-	If "largeio" specified, a filesystem that was created with a
-	"swidth" specified will return the "swidth" value (in bytes)
-	in st_blksize. If the filesystem does not have a "swidth"
-	specified but does specify an "allocsize" then "allocsize"
+	If ``largeio`` is specified, a filesystem that was created with a
+	``swidth`` specified will return the ``swidth`` value (in bytes)
+	in ``st_blksize``. If the filesystem does not have a ``swidth``
+	specified but does specify an ``allocsize`` then ``allocsize``
 	(in bytes) will be returned instead. Otherwise the behaviour
-	is the same as if "nolargeio" was specified.
+	is the same as if ``nolargeio`` was specified.
 
   logbufs=value
 	Set the number of in-memory log buffers.  Valid numbers
@@ -127,7 +120,7 @@ default behaviour.
 
 	If the memory cost of 8 log buffers is too high on small
 	systems, then it may be reduced at some cost to performance
-	on metadata intensive workloads. The logbsize option below
+	on metadata intensive workloads. The ``logbsize`` option below
 	controls the size of each buffer and so is also relevant to
 	this case.
 
@@ -138,7 +131,7 @@ default behaviour.
 	and 32768 (32k).  Valid sizes for version 2 logs also
 	include 65536 (64k), 131072 (128k) and 262144 (256k). The
 	logbsize must be an integer multiple of the log
-	stripe unit configured at mkfs time.
+	stripe unit configured at **mkfs(8)** time.
 
 	The default value for for version 1 logs is 32768, while the
 	default value for version 2 logs is MAX(32768, log_sunit).
@@ -153,21 +146,21 @@ default behaviour.
   noalign
 	Data allocations will not be aligned at stripe unit
 	boundaries. This is only relevant to filesystems created
-	with non-zero data alignment parameters (sunit, swidth) by
-	mkfs.
+	with non-zero data alignment parameters (``sunit``, ``swidth``) by
+	**mkfs(8)**.
 
   norecovery
 	The filesystem will be mounted without running log recovery.
 	If the filesystem was not cleanly unmounted, it is likely to
-	be inconsistent when mounted in "norecovery" mode.
+	be inconsistent when mounted in ``norecovery`` mode.
 	Some files or directories may not be accessible because of this.
-	Filesystems mounted "norecovery" must be mounted read-only or
+	Filesystems mounted ``norecovery`` must be mounted read-only or
 	the mount will fail.
 
   nouuid
 	Don't check for double mounted file systems using the file
-	system uuid.  This is useful to mount LVM snapshot volumes,
-	and often used in combination with "norecovery" for mounting
+	system ``uuid``.  This is useful to mount LVM snapshot volumes,
+	and often used in combination with ``norecovery`` for mounting
 	read-only snapshots.
 
   noquota
@@ -176,15 +169,15 @@ default behaviour.
 
   uquota/usrquota/uqnoenforce/quota
 	User disk quota accounting enabled, and limits (optionally)
-	enforced.  Refer to xfs_quota(8) for further details.
+	enforced.  Refer to **xfs_quota(8)** for further details.
 
   gquota/grpquota/gqnoenforce
 	Group disk quota accounting enabled and limits (optionally)
-	enforced.  Refer to xfs_quota(8) for further details.
+	enforced.  Refer to **xfs_quota(8)** for further details.
 
   pquota/prjquota/pqnoenforce
 	Project disk quota accounting enabled and limits (optionally)
-	enforced.  Refer to xfs_quota(8) for further details.
+	enforced.  Refer to **xfs_quota(8)** for further details.
 
   sunit=value and swidth=value
 	Used to specify the stripe unit and width for a RAID device
@@ -192,11 +185,11 @@ default behaviour.
 	block units. These options are only relevant to filesystems
 	that were created with non-zero data alignment parameters.
 
-	The sunit and swidth parameters specified must be compatible
+	The ``sunit`` and ``swidth`` parameters specified must be compatible
 	with the existing filesystem alignment characteristics.  In
-	general, that means the only valid changes to sunit are
-	increasing it by a power-of-2 multiple. Valid swidth values
-	are any integer multiple of a valid sunit value.
+	general, that means the only valid changes to ``sunit`` are
+	increasing it by a power-of-2 multiple. Valid ``swidth`` values
+	are any integer multiple of a valid ``sunit`` value.
 
 	Typically the only time these mount options are necessary if
 	after an underlying RAID device has had it's geometry
@@ -221,22 +214,25 @@ default behaviour.
 Deprecated Mount Options
 ========================
 
+===========================     ================
   Name				Removal Schedule
-  ----				----------------
+===========================     ================
+===========================     ================
 
 
 Removed Mount Options
 =====================
 
+===========================     =======
   Name				Removed
-  ----				-------
+===========================	=======
   delaylog/nodelaylog		v4.0
   ihashsize			v4.0
   irixsgid			v4.0
   osyncisdsync/osyncisosync	v4.0
   barrier			v4.19
   nobarrier			v4.19
-
+===========================     =======
 
 sysctls
 =======
@@ -302,27 +298,27 @@ The following sysctls are available for the XFS filesystem:
 
   fs.xfs.inherit_sync		(Min: 0  Default: 1  Max: 1)
 	Setting this to "1" will cause the "sync" flag set
-	by the xfs_io(8) chattr command on a directory to be
+	by the **xfs_io(8)** chattr command on a directory to be
 	inherited by files in that directory.
 
   fs.xfs.inherit_nodump		(Min: 0  Default: 1  Max: 1)
 	Setting this to "1" will cause the "nodump" flag set
-	by the xfs_io(8) chattr command on a directory to be
+	by the **xfs_io(8)** chattr command on a directory to be
 	inherited by files in that directory.
 
   fs.xfs.inherit_noatime	(Min: 0  Default: 1  Max: 1)
 	Setting this to "1" will cause the "noatime" flag set
-	by the xfs_io(8) chattr command on a directory to be
+	by the **xfs_io(8)** chattr command on a directory to be
 	inherited by files in that directory.
 
   fs.xfs.inherit_nosymlinks	(Min: 0  Default: 1  Max: 1)
 	Setting this to "1" will cause the "nosymlinks" flag set
-	by the xfs_io(8) chattr command on a directory to be
+	by the **xfs_io(8)** chattr command on a directory to be
 	inherited by files in that directory.
 
   fs.xfs.inherit_nodefrag	(Min: 0  Default: 1  Max: 1)
 	Setting this to "1" will cause the "nodefrag" flag set
-	by the xfs_io(8) chattr command on a directory to be
+	by the **xfs_io(8)** chattr command on a directory to be
 	inherited by files in that directory.
 
   fs.xfs.rotorstep		(Min: 1  Default: 1  Max: 256)
@@ -368,7 +364,7 @@ handler:
  -error handlers:
 	Defines the behavior for a specific error.
 
-The filesystem behavior during an error can be set via sysfs files. Each
+The filesystem behavior during an error can be set via ``sysfs`` files. Each
 error handler works independently - the first condition met by an error handler
 for a specific class will cause the error to be propagated rather than reset and
 retried.
@@ -419,7 +415,7 @@ level directory:
 	handler configurations.
 
 	Note: there is no guarantee that fail_at_unmount can be set while an
-	unmount is in progress. It is possible that the sysfs entries are
+	unmount is in progress. It is possible that the ``sysfs`` entries are
 	removed by the unmounting filesystem before a "retry forever" error
 	handler configuration causes unmount to hang, and hence the filesystem
 	must be configured appropriately before unmount begins to prevent
@@ -428,7 +424,7 @@ level directory:
 Each filesystem has specific error class handlers that define the error
 propagation behaviour for specific errors. There is also a "default" error
 handler defined, which defines the behaviour for all errors that don't have
-specific handlers defined. Where multiple retry constraints are configuredi for
+specific handlers defined. Where multiple retry constraints are configured for
 a single error, the first retry configuration that expires will cause the error
 to be propagated. The handler configurations are found in the directory:
 
@@ -463,7 +459,7 @@ to be propagated. The handler configurations are found in the directory:
 	Setting the value to "N" (where 0 < N < Max) will allow XFS to retry the
 	operation for up to "N" seconds before propagating the error.
 
-Note: The default behaviour for a specific error handler is dependent on both
+**Note:** The default behaviour for a specific error handler is dependent on both
 the class and error context. For example, the default values for
 "metadata/ENODEV" are "0" rather than "-1" so that this error handler defaults
 to "fail immediately" behaviour. This is done because ENODEV is a fatal,
diff --git a/Documentation/filesystems/dax.txt b/Documentation/filesystems/dax.txt
index 6d2c0d340dea..679729442fd2 100644
--- a/Documentation/filesystems/dax.txt
+++ b/Documentation/filesystems/dax.txt
@@ -76,7 +76,7 @@ exposure of uninitialized data through mmap.
 These filesystems may be used for inspiration:
 - ext2: see Documentation/filesystems/ext2.txt
 - ext4: see Documentation/filesystems/ext4/
-- xfs:  see Documentation/filesystems/xfs.txt
+- xfs:  see Documentation/admin-guide/xfs.rst
 
 
 Handling Media Errors
diff --git a/MAINTAINERS b/MAINTAINERS
index 43ca94856944..3b6e0b6d8cbd 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -17453,7 +17453,7 @@ L:	linux-xfs@vger.kernel.org
 W:	http://xfs.org/
 T:	git git://git.kernel.org/pub/scm/fs/xfs/xfs-linux.git
 S:	Supported
-F:	Documentation/filesystems/xfs.txt
+F:	Documentation/admin-guide/xfs.rst
 F:	fs/xfs/
 
 XILINX AXI ETHERNET DRIVER
-- 
2.22.0


^ permalink raw reply related

* [PATCH 4/4] Documentation:kernel-per-CPU-kthreads.txt: Remove reference to elevator=
From: Marcos Paulo de Souza @ 2019-07-14  5:34 UTC (permalink / raw)
  To: linux-kernel
  Cc: linux-block, linux-doc, Marcos Paulo de Souza, Jonathan Corbet
In-Reply-To: <20190714053453.1655-1-marcos.souza.org@gmail.com>

This argument was not being considered since blk-mq was set by default,
so removed this documentation to avoid confusion.

Signed-off-by: Marcos Paulo de Souza <marcos.souza.org@gmail.com>
---
 Documentation/kernel-per-CPU-kthreads.txt | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/Documentation/kernel-per-CPU-kthreads.txt b/Documentation/kernel-per-CPU-kthreads.txt
index 5623b9916411..c68c6c8c26a4 100644
--- a/Documentation/kernel-per-CPU-kthreads.txt
+++ b/Documentation/kernel-per-CPU-kthreads.txt
@@ -274,9 +274,7 @@ To reduce its OS jitter, do any of the following:
 		(based on an earlier one from Gilad Ben-Yossef) that
 		reduces or even eliminates vmstat overhead for some
 		workloads at https://lkml.org/lkml/2013/9/4/379.
-	e.	Boot with "elevator=noop" to avoid workqueue use by
-		the block layer.
-	f.	If running on high-end powerpc servers, build with
+	e.	If running on high-end powerpc servers, build with
 		CONFIG_PPC_RTAS_DAEMON=n.  This prevents the RTAS
 		daemon from running on each CPU every second or so.
 		(This will require editing Kconfig files and will defeat
@@ -284,12 +282,12 @@ To reduce its OS jitter, do any of the following:
 		due to the rtas_event_scan() function.
 		WARNING:  Please check your CPU specifications to
 		make sure that this is safe on your particular system.
-	g.	If running on Cell Processor, build your kernel with
+	f.	If running on Cell Processor, build your kernel with
 		CBE_CPUFREQ_SPU_GOVERNOR=n to avoid OS jitter from
 		spu_gov_work().
 		WARNING:  Please check your CPU specifications to
 		make sure that this is safe on your particular system.
-	h.	If running on PowerMAC, build your kernel with
+	g.	If running on PowerMAC, build your kernel with
 		CONFIG_PMAC_RACKMETER=n to disable the CPU-meter,
 		avoiding OS jitter from rackmeter_do_timer().
 
-- 
2.22.0


^ permalink raw reply related

* [PATCH 3/4] Documenation: switching-sched: Remove notes about elevator argument
From: Marcos Paulo de Souza @ 2019-07-14  5:34 UTC (permalink / raw)
  To: linux-kernel
  Cc: linux-block, linux-doc, Marcos Paulo de Souza, Jonathan Corbet,
	Jens Axboe, Andreas Herrmann
In-Reply-To: <20190714053453.1655-1-marcos.souza.org@gmail.com>

This argument was ignored since blk-mq was set as default, so remove it
from documentation.

Signed-off-by: Marcos Paulo de Souza <marcos.souza.org@gmail.com>
---
 Documentation/block/switching-sched.txt | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/Documentation/block/switching-sched.txt b/Documentation/block/switching-sched.txt
index 7977f6fb8b20..431d56471227 100644
--- a/Documentation/block/switching-sched.txt
+++ b/Documentation/block/switching-sched.txt
@@ -1,7 +1,3 @@
-To choose IO schedulers at boot time, use the argument 'elevator=deadline'.
-'noop' and 'cfq' (the default) are also available. IO schedulers are assigned
-globally at boot time only presently.
-
 Each io queue has a set of io scheduler tunables associated with it. These
 tunables control how the io scheduler works. You can find these entries
 in:
-- 
2.22.0


^ permalink raw reply related

* [PATCH 2/4] kernel-parameters.txt: Remove elevator argument
From: Marcos Paulo de Souza @ 2019-07-14  5:34 UTC (permalink / raw)
  To: linux-kernel
  Cc: linux-block, linux-doc, Marcos Paulo de Souza, Jonathan Corbet,
	Thomas Gleixner, Kees Cook, Andrew Morton, Ingo Molnar,
	Mauro Carvalho Chehab, Paul E. McKenney, Josh Poimboeuf,
	Logan Gunthorpe, Lu Baolu, Andy Lutomirski
In-Reply-To: <20190714053453.1655-1-marcos.souza.org@gmail.com>

This argument was not being used since the legacy IO path was removed,
when blk-mq was enabled by default. So removed it from the kernel
parameters documentation.

Signed-off-by: Marcos Paulo de Souza <marcos.souza.org@gmail.com>
---
 Documentation/admin-guide/kernel-parameters.txt | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 099c5a4be95b..2f47b20ee413 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -1197,12 +1197,6 @@
 			See comment before function elanfreq_setup() in
 			arch/x86/kernel/cpu/cpufreq/elanfreq.c.
 
-	elevator=	[IOSCHED]
-			Format: { "mq-deadline" | "kyber" | "bfq" }
-			See Documentation/block/deadline-iosched.txt,
-			Documentation/block/kyber-iosched.txt and
-			Documentation/block/bfq-iosched.txt for details.
-
 	elfcorehdr=[size[KMG]@]offset[KMG] [IA64,PPC,SH,X86,S390]
 			Specifies physical address of start of kernel core
 			image elf header and optionally the size. Generally
-- 
2.22.0


^ permalink raw reply related

* [PATCH 1/4] block: elevator.c: Remove now unused elevator= argument
From: Marcos Paulo de Souza @ 2019-07-14  5:34 UTC (permalink / raw)
  To: linux-kernel; +Cc: linux-block, linux-doc, Marcos Paulo de Souza, Jens Axboe
In-Reply-To: <20190714053453.1655-1-marcos.souza.org@gmail.com>

Since the inclusion of blk-mq, elevator argument was not being
considered anymore, and it's utility died long with the legacy IO path,
now removed too.

Signed-off-by: Marcos Paulo de Souza <marcos.souza.org@gmail.com>
---
 block/elevator.c | 14 --------------
 1 file changed, 14 deletions(-)

diff --git a/block/elevator.c b/block/elevator.c
index 2f17d66d0e61..f56d9c7d5cbc 100644
--- a/block/elevator.c
+++ b/block/elevator.c
@@ -135,20 +135,6 @@ static struct elevator_type *elevator_get(struct request_queue *q,
 	return e;
 }
 
-static char chosen_elevator[ELV_NAME_MAX];
-
-static int __init elevator_setup(char *str)
-{
-	/*
-	 * Be backwards-compatible with previous kernels, so users
-	 * won't get the wrong elevator.
-	 */
-	strncpy(chosen_elevator, str, sizeof(chosen_elevator) - 1);
-	return 1;
-}
-
-__setup("elevator=", elevator_setup);
-
 static struct kobj_type elv_ktype;
 
 struct elevator_queue *elevator_alloc(struct request_queue *q,
-- 
2.22.0


^ permalink raw reply related

* [PATCH 0/4] Remove elevator kernel parameter
From: Marcos Paulo de Souza @ 2019-07-14  5:34 UTC (permalink / raw)
  To: linux-kernel; +Cc: linux-block, linux-doc, Marcos Paulo de Souza

After the first patch sent[1], together with some background from Jens[2], this
patchset aims to remove completely elevator kernel parameter, since it is not
being used since blk-mq was set by default.

Along with elevator code, some documentation was also updated to remove elevator
references.

Please review, thanks.

[1]: https://lkml.org/lkml/2019/7/12/1008
[2]: https://lkml.org/lkml/2019/7/13/232

Marcos Paulo de Souza (4):
  block: elevator.c: Remove now unused elevator= argument
  kernel-parameters.txt: Remove elevator argument
  Documenation: switching-sched: Remove notes about elevator argument
  Documentation:kernel-per-CPU-kthreads.txt: Remove reference to
    elevator=

 Documentation/admin-guide/kernel-parameters.txt |  6 ------
 Documentation/block/switching-sched.txt         |  4 ----
 Documentation/kernel-per-CPU-kthreads.txt       |  8 +++-----
 block/elevator.c                                | 14 --------------
 4 files changed, 3 insertions(+), 29 deletions(-)

-- 
2.22.0


^ permalink raw reply

* Re: [PATCH v2 3/9] rcu/sync: Remove custom check for reader-section
From: Paul E. McKenney @ 2019-07-13 21:28 UTC (permalink / raw)
  To: Joel Fernandes
  Cc: linux-kernel, Oleg Nesterov, Alexey Kuznetsov, Bjorn Helgaas,
	Borislav Petkov, c0d1n61at3, David S. Miller, edumazet,
	Greg Kroah-Hartman, Hideaki YOSHIFUJI, H. Peter Anvin,
	Ingo Molnar, Jonathan Corbet, Josh Triplett, keescook,
	kernel-hardening, kernel-team, Lai Jiangshan, Len Brown,
	linux-acpi, linux-doc, linux-pci, linux-pm, Mathieu Desnoyers,
	neilb, netdev, Pavel Machek, peterz, Rafael J. Wysocki,
	Rasmus Villemoes, rcu, Steven Rostedt, Tejun Heo, Thomas Gleixner,
	will, maintainer:X86 ARCHITECTURE (32-BIT AND 64-BIT)
In-Reply-To: <20190713161316.GA39321@google.com>

On Sat, Jul 13, 2019 at 12:13:16PM -0400, Joel Fernandes wrote:
> On Sat, Jul 13, 2019 at 08:50:10AM -0700, Paul E. McKenney wrote:
> > On Sat, Jul 13, 2019 at 11:36:06AM -0400, Joel Fernandes wrote:
> > > On Sat, Jul 13, 2019 at 07:41:08AM -0700, Paul E. McKenney wrote:
> > > > On Sat, Jul 13, 2019 at 09:30:49AM -0400, Joel Fernandes wrote:
> > > > > On Sat, Jul 13, 2019 at 01:21:14AM -0700, Paul E. McKenney wrote:
> > > > > > On Fri, Jul 12, 2019 at 11:10:08PM -0400, Joel Fernandes wrote:
> > > > > > > On Fri, Jul 12, 2019 at 11:01:50PM -0400, Joel Fernandes wrote:
> > > > > > > > On Fri, Jul 12, 2019 at 04:32:06PM -0700, Paul E. McKenney wrote:
> > > > > > > > > On Fri, Jul 12, 2019 at 05:35:59PM -0400, Joel Fernandes wrote:
> > > > > > > > > > On Fri, Jul 12, 2019 at 01:00:18PM -0400, Joel Fernandes (Google) wrote:
> > > > > > > > > > > The rcu/sync code was doing its own check whether we are in a reader
> > > > > > > > > > > section. With RCU consolidating flavors and the generic helper added in
> > > > > > > > > > > this series, this is no longer need. We can just use the generic helper
> > > > > > > > > > > and it results in a nice cleanup.
> > > > > > > > > > > 
> > > > > > > > > > > Cc: Oleg Nesterov <oleg@redhat.com>
> > > > > > > > > > > Signed-off-by: Joel Fernandes (Google) <joel@joelfernandes.org>
> > > > > > > > > > 
> > > > > > > > > > Hi Oleg,
> > > > > > > > > > Slightly unrelated to the patch,
> > > > > > > > > > I tried hard to understand this comment below in percpu_down_read() but no dice.
> > > > > > > > > > 
> > > > > > > > > > I do understand how rcu sync and percpu rwsem works, however the comment
> > > > > > > > > > below didn't make much sense to me. For one, there's no readers_fast anymore
> > > > > > > > > > so I did not follow what readers_fast means. Could the comment be updated to
> > > > > > > > > > reflect latest changes?
> > > > > > > > > > Also could you help understand how is a writer not able to change
> > > > > > > > > > sem->state and count the per-cpu read counters at the same time as the
> > > > > > > > > > comment tries to say?
> > > > > > > > > > 
> > > > > > > > > > 	/*
> > > > > > > > > > 	 * We are in an RCU-sched read-side critical section, so the writer
> > > > > > > > > > 	 * cannot both change sem->state from readers_fast and start checking
> > > > > > > > > > 	 * counters while we are here. So if we see !sem->state, we know that
> > > > > > > > > > 	 * the writer won't be checking until we're past the preempt_enable()
> > > > > > > > > > 	 * and that once the synchronize_rcu() is done, the writer will see
> > > > > > > > > > 	 * anything we did within this RCU-sched read-size critical section.
> > > > > > > > > > 	 */
> > > > > > > > > > 
> > > > > > > > > > Also,
> > > > > > > > > > I guess we could get rid of all of the gp_ops struct stuff now that since all
> > > > > > > > > > the callbacks are the same now. I will post that as a follow-up patch to this
> > > > > > > > > > series.
> > > > > > > > > 
> > > > > > > > > Hello, Joel,
> > > > > > > > > 
> > > > > > > > > Oleg has a set of patches updating this code that just hit mainline
> > > > > > > > > this week.  These patches get rid of the code that previously handled
> > > > > > > > > RCU's multiple flavors.  Or are you looking at current mainline and
> > > > > > > > > me just missing your point?
> > > > > > > > > 
> > > > > > > > 
> > > > > > > > Hi Paul,
> > > > > > > > You are right on point. I have a bad habit of not rebasing my trees. In this
> > > > > > > > case the feature branch of mine in concern was based on v5.1. Needless to
> > > > > > > > say, I need to rebase my tree.
> > > > > > > > 
> > > > > > > > Yes, this sync clean up patch does conflict when I rebase, but other patches
> > > > > > > > rebase just fine.
> > > > > > > > 
> > > > > > > > The 2 options I see are:
> > > > > > > > 1. Let us drop this patch for now and I resend it later.
> > > > > > > > 2. I resend all patches based on Linus's master branch.
> > > > > > > 
> > > > > > > Below is the updated patch based on Linus master branch:
> > > > > > > 
> > > > > > > ---8<-----------------------
> > > > > > > 
> > > > > > > >From 5f40c9a07fcf3d6dafc2189599d0ba9443097d0f Mon Sep 17 00:00:00 2001
> > > > > > > From: "Joel Fernandes (Google)" <joel@joelfernandes.org>
> > > > > > > Date: Fri, 12 Jul 2019 12:13:27 -0400
> > > > > > > Subject: [PATCH v2.1 3/9] rcu/sync: Remove custom check for reader-section
> > > > > > > 
> > > > > > > The rcu/sync code was doing its own check whether we are in a reader
> > > > > > > section. With RCU consolidating flavors and the generic helper added in
> > > > > > > this series, this is no longer need. We can just use the generic helper
> > > > > > > and it results in a nice cleanup.
> > > > > > > 
> > > > > > > Cc: Oleg Nesterov <oleg@redhat.com>
> > > > > > > Signed-off-by: Joel Fernandes (Google) <joel@joelfernandes.org>
> > > > > > > ---
> > > > > > >  include/linux/rcu_sync.h | 4 +---
> > > > > > >  1 file changed, 1 insertion(+), 3 deletions(-)
> > > > > > > 
> > > > > > > diff --git a/include/linux/rcu_sync.h b/include/linux/rcu_sync.h
> > > > > > > index 9b83865d24f9..0027d4c8087c 100644
> > > > > > > --- a/include/linux/rcu_sync.h
> > > > > > > +++ b/include/linux/rcu_sync.h
> > > > > > > @@ -31,9 +31,7 @@ struct rcu_sync {
> > > > > > >   */
> > > > > > >  static inline bool rcu_sync_is_idle(struct rcu_sync *rsp)
> > > > > > >  {
> > > > > > > -	RCU_LOCKDEP_WARN(!rcu_read_lock_held() &&
> > > > > > > -			 !rcu_read_lock_bh_held() &&
> > > > > > > -			 !rcu_read_lock_sched_held(),
> > > > > > > +	RCU_LOCKDEP_WARN(!rcu_read_lock_any_held(),
> > > > > > 
> > > > > > I believe that replacing rcu_read_lock_sched_held() with preemptible()
> > > > > > in a CONFIG_PREEMPT=n kernel will give you false-positive splats here.
> > > > > > If you have not already done so, could you please give it a try?
> > > > > 
> > > > > Hi Paul,
> > > > > I don't think it will cause splats for !CONFIG_PREEMPT.
> > > > > 
> > > > > Currently, rcu_read_lock_any_held() introduced in this patch returns true if
> > > > > !preemptible(). This means that:
> > > > > 
> > > > > The following expression above:
> > > > > RCU_LOCKDEP_WARN(!rcu_read_lock_any_held(),...)
> > > > > 
> > > > > Becomes:
> > > > > RCU_LOCKDEP_WARN(preemptible(), ...)
> > > > > 
> > > > > For, CONFIG_PREEMPT=n kernels, this means:
> > > > > RCU_LOCKDEP_WARN(0, ...)
> > > > > 
> > > > > Which would mean no splats. Or, did I miss the point?
> > > > 
> > > > I suggest trying it out on a CONFIG_PREEMPT=n kernel.
> > > 
> > > Sure, will do, sorry did not try it out yet because was busy with weekend
> > > chores but will do soon, thanks!
> > 
> > I am not faulting you for taking the weekend off, actually.  ;-)
> 
> ;-) 
> 
> I tried doing RCU_LOCKDEP_WARN(preemptible(), ...) in this code path and I
> don't get any splats. I also disassembled the code and it seems to me
> RCU_LOCKDEP_WARN() becomes a NOOP which also the above reasoning confirms.

OK, very good.  Could you do the same thing for the RCU_LOCKDEP_WARN()
in synchronize_rcu()?  Why or why not?

(No need to work this on your Sunday.)

							Thanx, Paul

^ permalink raw reply

* Re: [PATCH v2 3/9] rcu/sync: Remove custom check for reader-section
From: Joel Fernandes @ 2019-07-13 16:13 UTC (permalink / raw)
  To: Paul E. McKenney
  Cc: linux-kernel, Oleg Nesterov, Alexey Kuznetsov, Bjorn Helgaas,
	Borislav Petkov, c0d1n61at3, David S. Miller, edumazet,
	Greg Kroah-Hartman, Hideaki YOSHIFUJI, H. Peter Anvin,
	Ingo Molnar, Jonathan Corbet, Josh Triplett, keescook,
	kernel-hardening, kernel-team, Lai Jiangshan, Len Brown,
	linux-acpi, linux-doc, linux-pci, linux-pm, Mathieu Desnoyers,
	neilb, netdev, Pavel Machek, peterz, Rafael J. Wysocki,
	Rasmus Villemoes, rcu, Steven Rostedt, Tejun Heo, Thomas Gleixner,
	will, maintainer:X86 ARCHITECTURE (32-BIT AND 64-BIT)
In-Reply-To: <20190713155010.GF26519@linux.ibm.com>

On Sat, Jul 13, 2019 at 08:50:10AM -0700, Paul E. McKenney wrote:
> On Sat, Jul 13, 2019 at 11:36:06AM -0400, Joel Fernandes wrote:
> > On Sat, Jul 13, 2019 at 07:41:08AM -0700, Paul E. McKenney wrote:
> > > On Sat, Jul 13, 2019 at 09:30:49AM -0400, Joel Fernandes wrote:
> > > > On Sat, Jul 13, 2019 at 01:21:14AM -0700, Paul E. McKenney wrote:
> > > > > On Fri, Jul 12, 2019 at 11:10:08PM -0400, Joel Fernandes wrote:
> > > > > > On Fri, Jul 12, 2019 at 11:01:50PM -0400, Joel Fernandes wrote:
> > > > > > > On Fri, Jul 12, 2019 at 04:32:06PM -0700, Paul E. McKenney wrote:
> > > > > > > > On Fri, Jul 12, 2019 at 05:35:59PM -0400, Joel Fernandes wrote:
> > > > > > > > > On Fri, Jul 12, 2019 at 01:00:18PM -0400, Joel Fernandes (Google) wrote:
> > > > > > > > > > The rcu/sync code was doing its own check whether we are in a reader
> > > > > > > > > > section. With RCU consolidating flavors and the generic helper added in
> > > > > > > > > > this series, this is no longer need. We can just use the generic helper
> > > > > > > > > > and it results in a nice cleanup.
> > > > > > > > > > 
> > > > > > > > > > Cc: Oleg Nesterov <oleg@redhat.com>
> > > > > > > > > > Signed-off-by: Joel Fernandes (Google) <joel@joelfernandes.org>
> > > > > > > > > 
> > > > > > > > > Hi Oleg,
> > > > > > > > > Slightly unrelated to the patch,
> > > > > > > > > I tried hard to understand this comment below in percpu_down_read() but no dice.
> > > > > > > > > 
> > > > > > > > > I do understand how rcu sync and percpu rwsem works, however the comment
> > > > > > > > > below didn't make much sense to me. For one, there's no readers_fast anymore
> > > > > > > > > so I did not follow what readers_fast means. Could the comment be updated to
> > > > > > > > > reflect latest changes?
> > > > > > > > > Also could you help understand how is a writer not able to change
> > > > > > > > > sem->state and count the per-cpu read counters at the same time as the
> > > > > > > > > comment tries to say?
> > > > > > > > > 
> > > > > > > > > 	/*
> > > > > > > > > 	 * We are in an RCU-sched read-side critical section, so the writer
> > > > > > > > > 	 * cannot both change sem->state from readers_fast and start checking
> > > > > > > > > 	 * counters while we are here. So if we see !sem->state, we know that
> > > > > > > > > 	 * the writer won't be checking until we're past the preempt_enable()
> > > > > > > > > 	 * and that once the synchronize_rcu() is done, the writer will see
> > > > > > > > > 	 * anything we did within this RCU-sched read-size critical section.
> > > > > > > > > 	 */
> > > > > > > > > 
> > > > > > > > > Also,
> > > > > > > > > I guess we could get rid of all of the gp_ops struct stuff now that since all
> > > > > > > > > the callbacks are the same now. I will post that as a follow-up patch to this
> > > > > > > > > series.
> > > > > > > > 
> > > > > > > > Hello, Joel,
> > > > > > > > 
> > > > > > > > Oleg has a set of patches updating this code that just hit mainline
> > > > > > > > this week.  These patches get rid of the code that previously handled
> > > > > > > > RCU's multiple flavors.  Or are you looking at current mainline and
> > > > > > > > me just missing your point?
> > > > > > > > 
> > > > > > > 
> > > > > > > Hi Paul,
> > > > > > > You are right on point. I have a bad habit of not rebasing my trees. In this
> > > > > > > case the feature branch of mine in concern was based on v5.1. Needless to
> > > > > > > say, I need to rebase my tree.
> > > > > > > 
> > > > > > > Yes, this sync clean up patch does conflict when I rebase, but other patches
> > > > > > > rebase just fine.
> > > > > > > 
> > > > > > > The 2 options I see are:
> > > > > > > 1. Let us drop this patch for now and I resend it later.
> > > > > > > 2. I resend all patches based on Linus's master branch.
> > > > > > 
> > > > > > Below is the updated patch based on Linus master branch:
> > > > > > 
> > > > > > ---8<-----------------------
> > > > > > 
> > > > > > >From 5f40c9a07fcf3d6dafc2189599d0ba9443097d0f Mon Sep 17 00:00:00 2001
> > > > > > From: "Joel Fernandes (Google)" <joel@joelfernandes.org>
> > > > > > Date: Fri, 12 Jul 2019 12:13:27 -0400
> > > > > > Subject: [PATCH v2.1 3/9] rcu/sync: Remove custom check for reader-section
> > > > > > 
> > > > > > The rcu/sync code was doing its own check whether we are in a reader
> > > > > > section. With RCU consolidating flavors and the generic helper added in
> > > > > > this series, this is no longer need. We can just use the generic helper
> > > > > > and it results in a nice cleanup.
> > > > > > 
> > > > > > Cc: Oleg Nesterov <oleg@redhat.com>
> > > > > > Signed-off-by: Joel Fernandes (Google) <joel@joelfernandes.org>
> > > > > > ---
> > > > > >  include/linux/rcu_sync.h | 4 +---
> > > > > >  1 file changed, 1 insertion(+), 3 deletions(-)
> > > > > > 
> > > > > > diff --git a/include/linux/rcu_sync.h b/include/linux/rcu_sync.h
> > > > > > index 9b83865d24f9..0027d4c8087c 100644
> > > > > > --- a/include/linux/rcu_sync.h
> > > > > > +++ b/include/linux/rcu_sync.h
> > > > > > @@ -31,9 +31,7 @@ struct rcu_sync {
> > > > > >   */
> > > > > >  static inline bool rcu_sync_is_idle(struct rcu_sync *rsp)
> > > > > >  {
> > > > > > -	RCU_LOCKDEP_WARN(!rcu_read_lock_held() &&
> > > > > > -			 !rcu_read_lock_bh_held() &&
> > > > > > -			 !rcu_read_lock_sched_held(),
> > > > > > +	RCU_LOCKDEP_WARN(!rcu_read_lock_any_held(),
> > > > > 
> > > > > I believe that replacing rcu_read_lock_sched_held() with preemptible()
> > > > > in a CONFIG_PREEMPT=n kernel will give you false-positive splats here.
> > > > > If you have not already done so, could you please give it a try?
> > > > 
> > > > Hi Paul,
> > > > I don't think it will cause splats for !CONFIG_PREEMPT.
> > > > 
> > > > Currently, rcu_read_lock_any_held() introduced in this patch returns true if
> > > > !preemptible(). This means that:
> > > > 
> > > > The following expression above:
> > > > RCU_LOCKDEP_WARN(!rcu_read_lock_any_held(),...)
> > > > 
> > > > Becomes:
> > > > RCU_LOCKDEP_WARN(preemptible(), ...)
> > > > 
> > > > For, CONFIG_PREEMPT=n kernels, this means:
> > > > RCU_LOCKDEP_WARN(0, ...)
> > > > 
> > > > Which would mean no splats. Or, did I miss the point?
> > > 
> > > I suggest trying it out on a CONFIG_PREEMPT=n kernel.
> > 
> > Sure, will do, sorry did not try it out yet because was busy with weekend
> > chores but will do soon, thanks!
> 
> I am not faulting you for taking the weekend off, actually.  ;-)

;-) 

I tried doing RCU_LOCKDEP_WARN(preemptible(), ...) in this code path and I
don't get any splats. I also disassembled the code and it seems to me
RCU_LOCKDEP_WARN() becomes a NOOP which also the above reasoning confirms.

thanks,

 - Joel


^ permalink raw reply

* Re: [PATCH v2 3/9] rcu/sync: Remove custom check for reader-section
From: Paul E. McKenney @ 2019-07-13 15:50 UTC (permalink / raw)
  To: Joel Fernandes
  Cc: linux-kernel, Oleg Nesterov, Alexey Kuznetsov, Bjorn Helgaas,
	Borislav Petkov, c0d1n61at3, David S. Miller, edumazet,
	Greg Kroah-Hartman, Hideaki YOSHIFUJI, H. Peter Anvin,
	Ingo Molnar, Jonathan Corbet, Josh Triplett, keescook,
	kernel-hardening, kernel-team, Lai Jiangshan, Len Brown,
	linux-acpi, linux-doc, linux-pci, linux-pm, Mathieu Desnoyers,
	neilb, netdev, Pavel Machek, peterz, Rafael J. Wysocki,
	Rasmus Villemoes, rcu, Steven Rostedt, Tejun Heo, Thomas Gleixner,
	will, maintainer:X86 ARCHITECTURE (32-BIT AND 64-BIT)
In-Reply-To: <20190713153606.GD133650@google.com>

On Sat, Jul 13, 2019 at 11:36:06AM -0400, Joel Fernandes wrote:
> On Sat, Jul 13, 2019 at 07:41:08AM -0700, Paul E. McKenney wrote:
> > On Sat, Jul 13, 2019 at 09:30:49AM -0400, Joel Fernandes wrote:
> > > On Sat, Jul 13, 2019 at 01:21:14AM -0700, Paul E. McKenney wrote:
> > > > On Fri, Jul 12, 2019 at 11:10:08PM -0400, Joel Fernandes wrote:
> > > > > On Fri, Jul 12, 2019 at 11:01:50PM -0400, Joel Fernandes wrote:
> > > > > > On Fri, Jul 12, 2019 at 04:32:06PM -0700, Paul E. McKenney wrote:
> > > > > > > On Fri, Jul 12, 2019 at 05:35:59PM -0400, Joel Fernandes wrote:
> > > > > > > > On Fri, Jul 12, 2019 at 01:00:18PM -0400, Joel Fernandes (Google) wrote:
> > > > > > > > > The rcu/sync code was doing its own check whether we are in a reader
> > > > > > > > > section. With RCU consolidating flavors and the generic helper added in
> > > > > > > > > this series, this is no longer need. We can just use the generic helper
> > > > > > > > > and it results in a nice cleanup.
> > > > > > > > > 
> > > > > > > > > Cc: Oleg Nesterov <oleg@redhat.com>
> > > > > > > > > Signed-off-by: Joel Fernandes (Google) <joel@joelfernandes.org>
> > > > > > > > 
> > > > > > > > Hi Oleg,
> > > > > > > > Slightly unrelated to the patch,
> > > > > > > > I tried hard to understand this comment below in percpu_down_read() but no dice.
> > > > > > > > 
> > > > > > > > I do understand how rcu sync and percpu rwsem works, however the comment
> > > > > > > > below didn't make much sense to me. For one, there's no readers_fast anymore
> > > > > > > > so I did not follow what readers_fast means. Could the comment be updated to
> > > > > > > > reflect latest changes?
> > > > > > > > Also could you help understand how is a writer not able to change
> > > > > > > > sem->state and count the per-cpu read counters at the same time as the
> > > > > > > > comment tries to say?
> > > > > > > > 
> > > > > > > > 	/*
> > > > > > > > 	 * We are in an RCU-sched read-side critical section, so the writer
> > > > > > > > 	 * cannot both change sem->state from readers_fast and start checking
> > > > > > > > 	 * counters while we are here. So if we see !sem->state, we know that
> > > > > > > > 	 * the writer won't be checking until we're past the preempt_enable()
> > > > > > > > 	 * and that once the synchronize_rcu() is done, the writer will see
> > > > > > > > 	 * anything we did within this RCU-sched read-size critical section.
> > > > > > > > 	 */
> > > > > > > > 
> > > > > > > > Also,
> > > > > > > > I guess we could get rid of all of the gp_ops struct stuff now that since all
> > > > > > > > the callbacks are the same now. I will post that as a follow-up patch to this
> > > > > > > > series.
> > > > > > > 
> > > > > > > Hello, Joel,
> > > > > > > 
> > > > > > > Oleg has a set of patches updating this code that just hit mainline
> > > > > > > this week.  These patches get rid of the code that previously handled
> > > > > > > RCU's multiple flavors.  Or are you looking at current mainline and
> > > > > > > me just missing your point?
> > > > > > > 
> > > > > > 
> > > > > > Hi Paul,
> > > > > > You are right on point. I have a bad habit of not rebasing my trees. In this
> > > > > > case the feature branch of mine in concern was based on v5.1. Needless to
> > > > > > say, I need to rebase my tree.
> > > > > > 
> > > > > > Yes, this sync clean up patch does conflict when I rebase, but other patches
> > > > > > rebase just fine.
> > > > > > 
> > > > > > The 2 options I see are:
> > > > > > 1. Let us drop this patch for now and I resend it later.
> > > > > > 2. I resend all patches based on Linus's master branch.
> > > > > 
> > > > > Below is the updated patch based on Linus master branch:
> > > > > 
> > > > > ---8<-----------------------
> > > > > 
> > > > > >From 5f40c9a07fcf3d6dafc2189599d0ba9443097d0f Mon Sep 17 00:00:00 2001
> > > > > From: "Joel Fernandes (Google)" <joel@joelfernandes.org>
> > > > > Date: Fri, 12 Jul 2019 12:13:27 -0400
> > > > > Subject: [PATCH v2.1 3/9] rcu/sync: Remove custom check for reader-section
> > > > > 
> > > > > The rcu/sync code was doing its own check whether we are in a reader
> > > > > section. With RCU consolidating flavors and the generic helper added in
> > > > > this series, this is no longer need. We can just use the generic helper
> > > > > and it results in a nice cleanup.
> > > > > 
> > > > > Cc: Oleg Nesterov <oleg@redhat.com>
> > > > > Signed-off-by: Joel Fernandes (Google) <joel@joelfernandes.org>
> > > > > ---
> > > > >  include/linux/rcu_sync.h | 4 +---
> > > > >  1 file changed, 1 insertion(+), 3 deletions(-)
> > > > > 
> > > > > diff --git a/include/linux/rcu_sync.h b/include/linux/rcu_sync.h
> > > > > index 9b83865d24f9..0027d4c8087c 100644
> > > > > --- a/include/linux/rcu_sync.h
> > > > > +++ b/include/linux/rcu_sync.h
> > > > > @@ -31,9 +31,7 @@ struct rcu_sync {
> > > > >   */
> > > > >  static inline bool rcu_sync_is_idle(struct rcu_sync *rsp)
> > > > >  {
> > > > > -	RCU_LOCKDEP_WARN(!rcu_read_lock_held() &&
> > > > > -			 !rcu_read_lock_bh_held() &&
> > > > > -			 !rcu_read_lock_sched_held(),
> > > > > +	RCU_LOCKDEP_WARN(!rcu_read_lock_any_held(),
> > > > 
> > > > I believe that replacing rcu_read_lock_sched_held() with preemptible()
> > > > in a CONFIG_PREEMPT=n kernel will give you false-positive splats here.
> > > > If you have not already done so, could you please give it a try?
> > > 
> > > Hi Paul,
> > > I don't think it will cause splats for !CONFIG_PREEMPT.
> > > 
> > > Currently, rcu_read_lock_any_held() introduced in this patch returns true if
> > > !preemptible(). This means that:
> > > 
> > > The following expression above:
> > > RCU_LOCKDEP_WARN(!rcu_read_lock_any_held(),...)
> > > 
> > > Becomes:
> > > RCU_LOCKDEP_WARN(preemptible(), ...)
> > > 
> > > For, CONFIG_PREEMPT=n kernels, this means:
> > > RCU_LOCKDEP_WARN(0, ...)
> > > 
> > > Which would mean no splats. Or, did I miss the point?
> > 
> > I suggest trying it out on a CONFIG_PREEMPT=n kernel.
> 
> Sure, will do, sorry did not try it out yet because was busy with weekend
> chores but will do soon, thanks!

I am not faulting you for taking the weekend off, actually.  ;-)

							Thanx, Paul


^ permalink raw reply

* Re: [PATCH v2 3/9] rcu/sync: Remove custom check for reader-section
From: Joel Fernandes @ 2019-07-13 15:36 UTC (permalink / raw)
  To: Paul E. McKenney
  Cc: linux-kernel, Oleg Nesterov, Alexey Kuznetsov, Bjorn Helgaas,
	Borislav Petkov, c0d1n61at3, David S. Miller, edumazet,
	Greg Kroah-Hartman, Hideaki YOSHIFUJI, H. Peter Anvin,
	Ingo Molnar, Jonathan Corbet, Josh Triplett, keescook,
	kernel-hardening, kernel-team, Lai Jiangshan, Len Brown,
	linux-acpi, linux-doc, linux-pci, linux-pm, Mathieu Desnoyers,
	neilb, netdev, Pavel Machek, peterz, Rafael J. Wysocki,
	Rasmus Villemoes, rcu, Steven Rostedt, Tejun Heo, Thomas Gleixner,
	will, maintainer:X86 ARCHITECTURE (32-BIT AND 64-BIT)
In-Reply-To: <20190713144108.GD26519@linux.ibm.com>

On Sat, Jul 13, 2019 at 07:41:08AM -0700, Paul E. McKenney wrote:
> On Sat, Jul 13, 2019 at 09:30:49AM -0400, Joel Fernandes wrote:
> > On Sat, Jul 13, 2019 at 01:21:14AM -0700, Paul E. McKenney wrote:
> > > On Fri, Jul 12, 2019 at 11:10:08PM -0400, Joel Fernandes wrote:
> > > > On Fri, Jul 12, 2019 at 11:01:50PM -0400, Joel Fernandes wrote:
> > > > > On Fri, Jul 12, 2019 at 04:32:06PM -0700, Paul E. McKenney wrote:
> > > > > > On Fri, Jul 12, 2019 at 05:35:59PM -0400, Joel Fernandes wrote:
> > > > > > > On Fri, Jul 12, 2019 at 01:00:18PM -0400, Joel Fernandes (Google) wrote:
> > > > > > > > The rcu/sync code was doing its own check whether we are in a reader
> > > > > > > > section. With RCU consolidating flavors and the generic helper added in
> > > > > > > > this series, this is no longer need. We can just use the generic helper
> > > > > > > > and it results in a nice cleanup.
> > > > > > > > 
> > > > > > > > Cc: Oleg Nesterov <oleg@redhat.com>
> > > > > > > > Signed-off-by: Joel Fernandes (Google) <joel@joelfernandes.org>
> > > > > > > 
> > > > > > > Hi Oleg,
> > > > > > > Slightly unrelated to the patch,
> > > > > > > I tried hard to understand this comment below in percpu_down_read() but no dice.
> > > > > > > 
> > > > > > > I do understand how rcu sync and percpu rwsem works, however the comment
> > > > > > > below didn't make much sense to me. For one, there's no readers_fast anymore
> > > > > > > so I did not follow what readers_fast means. Could the comment be updated to
> > > > > > > reflect latest changes?
> > > > > > > Also could you help understand how is a writer not able to change
> > > > > > > sem->state and count the per-cpu read counters at the same time as the
> > > > > > > comment tries to say?
> > > > > > > 
> > > > > > > 	/*
> > > > > > > 	 * We are in an RCU-sched read-side critical section, so the writer
> > > > > > > 	 * cannot both change sem->state from readers_fast and start checking
> > > > > > > 	 * counters while we are here. So if we see !sem->state, we know that
> > > > > > > 	 * the writer won't be checking until we're past the preempt_enable()
> > > > > > > 	 * and that once the synchronize_rcu() is done, the writer will see
> > > > > > > 	 * anything we did within this RCU-sched read-size critical section.
> > > > > > > 	 */
> > > > > > > 
> > > > > > > Also,
> > > > > > > I guess we could get rid of all of the gp_ops struct stuff now that since all
> > > > > > > the callbacks are the same now. I will post that as a follow-up patch to this
> > > > > > > series.
> > > > > > 
> > > > > > Hello, Joel,
> > > > > > 
> > > > > > Oleg has a set of patches updating this code that just hit mainline
> > > > > > this week.  These patches get rid of the code that previously handled
> > > > > > RCU's multiple flavors.  Or are you looking at current mainline and
> > > > > > me just missing your point?
> > > > > > 
> > > > > 
> > > > > Hi Paul,
> > > > > You are right on point. I have a bad habit of not rebasing my trees. In this
> > > > > case the feature branch of mine in concern was based on v5.1. Needless to
> > > > > say, I need to rebase my tree.
> > > > > 
> > > > > Yes, this sync clean up patch does conflict when I rebase, but other patches
> > > > > rebase just fine.
> > > > > 
> > > > > The 2 options I see are:
> > > > > 1. Let us drop this patch for now and I resend it later.
> > > > > 2. I resend all patches based on Linus's master branch.
> > > > 
> > > > Below is the updated patch based on Linus master branch:
> > > > 
> > > > ---8<-----------------------
> > > > 
> > > > >From 5f40c9a07fcf3d6dafc2189599d0ba9443097d0f Mon Sep 17 00:00:00 2001
> > > > From: "Joel Fernandes (Google)" <joel@joelfernandes.org>
> > > > Date: Fri, 12 Jul 2019 12:13:27 -0400
> > > > Subject: [PATCH v2.1 3/9] rcu/sync: Remove custom check for reader-section
> > > > 
> > > > The rcu/sync code was doing its own check whether we are in a reader
> > > > section. With RCU consolidating flavors and the generic helper added in
> > > > this series, this is no longer need. We can just use the generic helper
> > > > and it results in a nice cleanup.
> > > > 
> > > > Cc: Oleg Nesterov <oleg@redhat.com>
> > > > Signed-off-by: Joel Fernandes (Google) <joel@joelfernandes.org>
> > > > ---
> > > >  include/linux/rcu_sync.h | 4 +---
> > > >  1 file changed, 1 insertion(+), 3 deletions(-)
> > > > 
> > > > diff --git a/include/linux/rcu_sync.h b/include/linux/rcu_sync.h
> > > > index 9b83865d24f9..0027d4c8087c 100644
> > > > --- a/include/linux/rcu_sync.h
> > > > +++ b/include/linux/rcu_sync.h
> > > > @@ -31,9 +31,7 @@ struct rcu_sync {
> > > >   */
> > > >  static inline bool rcu_sync_is_idle(struct rcu_sync *rsp)
> > > >  {
> > > > -	RCU_LOCKDEP_WARN(!rcu_read_lock_held() &&
> > > > -			 !rcu_read_lock_bh_held() &&
> > > > -			 !rcu_read_lock_sched_held(),
> > > > +	RCU_LOCKDEP_WARN(!rcu_read_lock_any_held(),
> > > 
> > > I believe that replacing rcu_read_lock_sched_held() with preemptible()
> > > in a CONFIG_PREEMPT=n kernel will give you false-positive splats here.
> > > If you have not already done so, could you please give it a try?
> > 
> > Hi Paul,
> > I don't think it will cause splats for !CONFIG_PREEMPT.
> > 
> > Currently, rcu_read_lock_any_held() introduced in this patch returns true if
> > !preemptible(). This means that:
> > 
> > The following expression above:
> > RCU_LOCKDEP_WARN(!rcu_read_lock_any_held(),...)
> > 
> > Becomes:
> > RCU_LOCKDEP_WARN(preemptible(), ...)
> > 
> > For, CONFIG_PREEMPT=n kernels, this means:
> > RCU_LOCKDEP_WARN(0, ...)
> > 
> > Which would mean no splats. Or, did I miss the point?
> 
> I suggest trying it out on a CONFIG_PREEMPT=n kernel.

Sure, will do, sorry did not try it out yet because was busy with weekend
chores but will do soon, thanks!


^ permalink raw reply

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