Re: linux-next: manual merge of the jc_docs tree with the fscrypt tree

2018-12-06 Thread Jonathan Corbet
On Fri, 7 Dec 2018 11:53:40 +1100
Stephen Rothwell  wrote:

> Today's linux-next merge of the jc_docs tree got a conflict in:
> 
>   Documentation/filesystems/index.rst
> 
> between commit:
> 
>   1b71a6809f96 ("fs-verity: add a documentation file")
> 
> from the fscrypt tree and commit:
> 
>   7bbfd9ad8eb2 ("Documentation: convert path-lookup from markdown to 
> resturctured text")
> 
> from the jc_docs tree.
> 
> I fixed it up (see below) and can carry the fix as necessary. This
> is now fixed as far as linux-next is concerned, but any non trivial
> conflicts should be mentioned to your upstream maintainer when your tree
> is submitted for merging.  You may also want to consider cooperating
> with the maintainer of the conflicting tree to minimise any particularly
> complex conflicts.

That fix is as good as any, thanks.

jon


Re: [PATCH] x86, boot: documentation whitespace fixup

2018-12-06 Thread Jonathan Corbet
On Fri, 30 Nov 2018 09:22:17 -0500
"Michael S. Tsirkin"  wrote:

> Fix an extra space that sneaked in with commit 09c205afd "(x86, boot:
> Define the 2.12 bzImage boot protocol").
> 
> Signed-off-by: Michael S. Tsirkin 

Applied, thanks.

jon


Re: [PATCH RFC 14/15] lib: replace **** with a hug

2018-11-30 Thread Jonathan Corbet
On Fri, 30 Nov 2018 14:41:11 -0500
Steven Rostedt  wrote:

> > - * Wirzenius wrote this portably, Torvalds fucked it up :-)
> > + * Wirzenius wrote this portably, Torvalds hugged it up :-)  
> 
> Since the code has been greatly modified since that comment was added,
> I would say the comment is simply out of date.
> 
> Just nuke the comment, and that will be an accurate change with or
> without CoC.

For both patches, actually, I'd much rather see either deletion or a
rewrite over bleeping out words that somebody might not like.

jon


Re: Official Linux system wrapper library?

2018-11-12 Thread Jonathan Corbet
On Sun, 11 Nov 2018 18:36:30 -0800
Greg KH  wrote:

> We should have a checklist.  That's a great idea.  Now to find someone
> to write it... :)

Do we think the LPC session might have the right people to create such a
thing?  If so, I can try to put together a coherent presentation of the
result.

jon


Re: [RFC PATCH v4 01/13] ktask: add documentation

2018-11-08 Thread Jonathan Corbet
On Thu, 8 Nov 2018 11:15:53 -0800
Daniel Jordan  wrote:

> > - You have kerneldoc comments for the API functions, but you don't pull
> >   those into the documentation itself.  Adding some kernel-doc directives
> >   could help to fill things out nicely with little effort.  
> 
> I thought this part of ktask.rst handled that, or am I not doing it right?
> 
> Interface
> =
> 
> .. kernel-doc:: include/linux/ktask.h

Sigh, no, you're doing it just fine, and I clearly wasn't sufficiently
caffeinated.  Apologies for the noise.

jon


Re: [RFC PATCH v4 01/13] ktask: add documentation

2018-11-08 Thread Jonathan Corbet
On Mon,  5 Nov 2018 11:55:46 -0500
Daniel Jordan  wrote:

> Motivates and explains the ktask API for kernel clients.

A couple of quick thoughts:

- Agree with Peter on the use of "task"; something like "job" would be far
  less likely to create confusion.  Maybe you could even call it a "batch
  job" to give us old-timers warm fuzzies...:)

- You have kerneldoc comments for the API functions, but you don't pull
  those into the documentation itself.  Adding some kernel-doc directives
  could help to fill things out nicely with little effort.

Thanks,

jon


Re: [patch 0/2] Documentation/process: Add subsystem/tree handbook

2018-11-08 Thread Jonathan Corbet
On Thu, 8 Nov 2018 11:21:33 -0500
"Theodore Y. Ts'o"  wrote:

> I thought there was a slot already scheduled on the refereed track,
> "Towards a Linux Kernel Mainainer Handbook" (Tuesday at 4:45pm) for
> this purpose?

My expectation is that this will be an actual talk; it seemed rude to
assume that Dan had penciled in a block of time for open arguments about
the tip-tree handbook :)  That said, I'm not feeling a groundswell of
support for scheduling another session at this point...

jon


Re: [patch 0/2] Documentation/process: Add subsystem/tree handbook

2018-11-08 Thread Jonathan Corbet
On Thu, 8 Nov 2018 16:05:17 +0100
Peter Zijlstra  wrote:

> On Thu, Nov 08, 2018 at 07:49:20AM -0700, Jonathan Corbet wrote:
> > Might it be worth asking Ted for a kernel summit slot to talk about this
> > next week?  
> 
> Ah, on that, let me complain :-)
> 
> My plumbers schedule is already 100% booked with MCs and other things.
> There is no kernel-summit schedule details available as of yet, but it
> is already almost certain that I will not have time for anything in that
> track anyway :/

But surely you can find a few minutes to drop by and throw catchboxes at
the docs maintainer? :)

I do understand, though, it's going to be a crazy week.

jon


Re: [patch 0/2] Documentation/process: Add subsystem/tree handbook

2018-11-08 Thread Jonathan Corbet
On Wed, 7 Nov 2018 21:51:38 +0100 (CET)
Thomas Gleixner  wrote:

> So I agree with Dan, that we should collect as much documentation from
> subsystems/maintainers and get it into the tree so we can:
> 
>- give contributors immediate access to subsystem/maintainer specific
>  quirks
> 
>- extract common views and move them into the general guidelines
> 
>- have a clear idea which kind of things need to be discussed and agreed
>  on and what might be left in the susbsystem/maintainer specific
>  interpretation/expectation realm.

Ah, but Dan said:

> Not at all, and this is one of the thrusts of my talk next week at
> Plumbers. I *do* want to propose that sub-systems document all their
> local quirks. 

My concern is that you're going far beyond "local quirks" here, and
actually hiding the real quirks in the process. Just one example from
Ingo's email storm this (US/Mountain) morning:

> Even after a decade of introducing Git I still see Signed-off-by used as 
> an Acked-by or Reviewed-by substitutes, so I'd suggest adding this small 
> explanation as well:
> 
>   +   SOB chains should reflect the *real* route a patch took as it was 
>   +   propagated to us, with the first SOB entry signalling primary
>   +   authorship of a single author. Acks should be given as Acked-by 
>   +   lines and review approvals as Reviewed-by lines.

If SOB means anything like what it's supposed to mean, this *can't* be a
"local quirk" - we have to agree on it globally.

If you want to push this into the tree in something like its current form,
I'm not going to resist too hard - far be it from me to say we don't want
more documentation!  But allow me to complain a little.

Suppose I came along with my nifty new architecture, and it dragged in a
whole new set of timer and interrupt subsystems that duplicated a lot of
what's in the kernel now, but buried a few "local quirks" deep in the
middle.  "Don't worry", I say, "we'll factor out the common stuff later
once we figure out what it is; I'd rather not deal with the bikeshedding
now". Correct me if I'm wrong, but I suspect I might just get a response
back from you.  That's not how we normally do things.

This proposal takes a similar approach to the documentation.  Changelog
rules, your comment rules (other than tail comments), brace rules, line
breaks, etc. are common stuff; if they are not well-enough documented in
the global docs, the fix should really be applied there.  If it lands in
the current form, you know as well as I do that it will almost certainly
stay there for years, if not indefinitely.

IMO, the subsystem-specific documentation should be something that an
existing kernel developer can use to quickly learn how to avoid surprises
when wandering into a different subsystem.  So it should be concise and
strongly focused on the local customs.  If we don't start that way, I'm
afraid we'll never have that.  Then developers will miss the important
information, and we'll reinforce the image of the kernel project as a
collection of little fiefdoms that one wanders into at one's own risk.
And Documentation/ will continue to be a painful mess.



Might it be worth asking Ted for a kernel summit slot to talk about this
next week?

(And thanks again for doing this!  I like the material and think we
definitely want it.)

jon


Re: [patch 0/2] Documentation/process: Add subsystem/tree handbook

2018-11-07 Thread Jonathan Corbet
On Wed, 07 Nov 2018 18:10:10 +0100
Thomas Gleixner  wrote:

> Mark recently suggested in one of the ksummit discussions to add subsystem
> or tree specific maintainer handbooks to document subsystem/tree specific
> development process information.
> 
> The following series adds the general section and the tip tree specific
> handbook.

So this is an idea that has gone around for a while; developers often get
into trouble when wandering into an unfamiliar part of the kernel, so
documenting the quaint local customs might help.  Assuming people actually
read the documentation, of course.

What's here seems generally good, but I do have an overall worry that we
may want to consider:

  - How much do we want to support and document subsystem-specific quirks
vs. promoting reasonable and consistent rules kernel-wide?

There is a *lot* of stuff in the new tip manual.  Much of it, regarding
coding style and the writing of changelogs, really seems like it should be
global; if we need better documentation of that stuff, I'd really rather
see that advice folded into the central documents.  Having two (or more)
extensive coding-style documents doesn't seem like it's going to help us.

The stuff that is truly specific to tip seems fairly minimal:

  - what goes into tip
  - the reverse fir tree thing
  - tail comments, or the distaste thereabouts
  - subject-line prefixes

Having a tip-specific document that contains only those (plus whatever
else I forgot to list) would, IMO, make it much more likely that readers
would actually notice (and follow) the stuff that's specific to tip.

See what I'm getting at here?  Am I totally out to lunch on this?

Thanks,

jon

P.S. There is the separate issue of whether having subsystem-specific
 coding-style rules is a good thing overall.  I think we should try to
 be one big kernel project rather than 100 small ones, but perhaps
 that's just me.


Re: [PATCH 0/2] Docs/EDID: Fixed and improved EDID documentation

2018-11-06 Thread Jonathan Corbet
On Mon, 5 Nov 2018 09:48:33 +0100
Christoph Niedermaier  wrote:

> A problem was found when EDID data sets for displays other
> than the provided samples were generated. The patch series has
> no effect on the provided samples that still match the data
> used in drivers/gpu/drm/drm_edid_load.c.
> The provided samples use small values for XOFFSET, XPULSE,
> YOFFSET and YPULSE, where the error doesn't occur. This fix
> corrects the use of that values in case of high values, because
> the most significant bits were treated incorrectly.
> 
> The previous version made it necessary to first generate an
> EDID data set without correct CRC and then to fix the CRC in
> a second step. This patch series adds the CRC calculation to the
> makefile in such a way that a correct EDID data set is generated
> in a single build step.

This seems reasonable, I guess; I've applied both.  It seems to me, though,
that this stuff is in the wrong place.  Perhaps we should go one step
further and move it to tools/ ?

Thanks,

jon


Re: [PATCH] docs: Fix typos in histogram.rst

2018-10-18 Thread Jonathan Corbet
On Sat, 13 Oct 2018 10:30:57 +0900
Masanari Iida  wrote:

> This patch fixes some spelling typos.
> 
> Signed-off-by: Masanari Iida 

Applied, thanks.

jon


Re: [RFC PATCH 00/30] softirq: Make softirqs soft-interruptible (+ per vector disablement)

2018-10-16 Thread Jonathan Corbet
On Thu, 11 Oct 2018 01:11:47 +0200
Frederic Weisbecker  wrote:

> 945 files changed, 13857 insertions(+), 9767 deletions(-)

Impressive :)

I have to ask a dumb question, though.  Might it not be better to add a
new set of functions like:

local_softirq_disable(mask);
spin_lock_softirq(lock, mask);

Then just define the existing functions to call the new ones with
SOFTIRQ_ALL_MASK?  It would achieve something like the same result with
far less churn and conflict potential; then individual call sites could be
changed at leisure?  For extra credit, somebody could do a checkpatch rule
to keep new calls to the _bh functions from being added.

Thanks,

jon


Re: [PATCH v2 2/2] LICENSES: Add ISC license text

2018-10-12 Thread Jonathan Corbet
On Wed, 10 Oct 2018 22:15:09 +0200
Hans de Goede  wrote:

> Add the full text of the ISC license to the kernel tree. It was copied
> directly from:
> 
>https://spdx.org/licenses/ISC.html
> 
> With the mention of "ISC" in the warranty disclaimer replaced with
> "THE AUTHOR" as done in the ISC license headers used in the ath10k and
> brcmfmac wifi drivers.
> 
> Cc: Kalle Valo 
> Signed-off-by: Hans de Goede 

Applied this one too, thanks.

jon


Re: [PATCH v2 1/2] LICENSES: Add note to CDDL-1.0 license that it should not be used

2018-10-12 Thread Jonathan Corbet
On Wed, 10 Oct 2018 22:15:08 +0200
Hans de Goede  wrote:

> The only reason we have the CDDL-1.0 license text around is for some
> dual-licensed files from virtualbox. New code should not use this license.
> 
> Add a note about this and change the example tag to be dual-licensed.
> 
> Signed-off-by: Hans de Goede 

Applied, thanks.

jon


Re: linux-next: manual merge of the akpm tree with the jc_docs tree

2018-10-08 Thread Jonathan Corbet
On Mon, 8 Oct 2018 10:38:29 +0200
David Hildenbrand  wrote:

> > I can do the renaming and add the patch
> > 
> >   "memory-hotplug.txt: add some details about locking internals"
> > 
> > on top of the jc_docs tree.
> > 
> > Does it sound Ok?
> >   
> 
> Fine with me.

Works for me too.

Andrew, what is your preference for mm docs patches going forward?  It
seems we should try to focus them on one tree or the other.  My preference
would be to keep carrying them to avoid conflicts elsewhere, but I can
certainly direct them youward if you'd rather they went that way.

Thanks,

jon


Re: Code of Conduct: Let's revamp it.

2018-09-19 Thread Jonathan Corbet
On Wed, 19 Sep 2018 07:00:26 +0100
Edward Cree  wrote:

> By placing a corporate body (the LF) in
>   the position of arbiter, an avenue is opened for commercial pressure to be
>   applied; and the legalistic phrasing of the Code practically invites 
> rules-
>   lawyering whereby the most abusive may twist it into a weapon to further
>   their abuse.

I'd like to address just this part, speaking only for myself.

The LF is not in the position of arbitrating anything here.  The body
charged with that is the LF Technical Advisory Board, which is a
different thing.  It's currently this motley crowd:

  https://www.linuxfoundation.org/about/technical-advisory-board/

I think most of us would agree that those folks lack the desire to go
around harassing developers, and they lack the time to do so in any
case.

The TAB is chosen by a vote of developers at the kernel summit; that will
happen in Vancouver in November.  

jon


Re: [PATCH] efi_stub: update documentation on dtb= parameter

2018-09-06 Thread Jonathan Corbet
On Wed,  5 Sep 2018 20:07:50 +0100
Grant Likely  wrote:

> The dtb= parameter is no longer the primary mechanism for providing a
> devicetree to the kernel. Now either firmware or the boot selector (ex.
> Grub) should provide the devicetree and dtb= should only be used for
> debug or when using firmware that doesn't understand DT.
> Update the EFI stub documentation to reflect the current usage.

So I hate to be obnoxious, but...

> IMPORTANT NOTICE: The contents of this email and any attachments are
> confidential and may also be privileged. If you are not the intended
> recipient, please notify the sender immediately and do not disclose the
> contents to any other person, use it for any purpose, or store or copy
> the information in any medium. Thank you.

Can I get a version of the patch without this language?  Then I'll be glad
to apply it.

Thanks,

jon


Re: linux-next: error fetching the jc_docs tree

2018-09-03 Thread Jonathan Corbet
On Tue, 4 Sep 2018 09:30:49 +1000
Stephen Rothwell  wrote:

> Fetching the jc_docs tree (git://git.lwn.net/linux.git#docs-next) today
> produced this error:
> 
> fatal: remote error: access denied or repository not exported: /linux.git

Funny what happens when you switch to a new server...all should be fixed
now.  Sorry for the trouble,

jon


Re: [PATCH] docs: fix typo in table describing 4.16 development cycle

2018-08-31 Thread Jonathan Corbet
On Sat, 18 Aug 2018 02:33:30 +0900
Akinobu Mita  wrote:

> Fix s/4.17/4.16/ typo.
> 
> Fixes: 8962e40c1993 ("docs: update kernel versions and dates in tables")
> Cc: Tim Bird 
> Cc: Jonathan Corbet 
> Signed-off-by: Akinobu Mita 
> ---
>  Documentation/process/2.Process.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/process/2.Process.rst 
> b/Documentation/process/2.Process.rst
> index 51d0349..ae020d8 100644
> --- a/Documentation/process/2.Process.rst
> +++ b/Documentation/process/2.Process.rst
> @@ -82,7 +82,7 @@ As an example, here is how the 4.16 development cycle went 
> (all dates in
>   March 114.16-rc5
>   March 184.16-rc6
>   March 254.16-rc7
> - April 1 4.17 stable release
> + April 1 4.16 stable release

Oops...  applied, thanks.

jon


Re: [PATCH] Revert "Permit silencing of __deprecated warnings."

2018-08-19 Thread Jonathan Corbet
On Fri, 17 Aug 2018 20:45:06 -0600
Jason Gunthorpe  wrote:

> Jonathan: I'm not sure if you prefer diffs to documentation to be
> minimal like this, or if should reflow the paragraph?

I guess I've never really thought to develop a strong preference.  But,
in the end, the docs are meant to be read in their source form, so we
want to keep them readable.  If a paragraph needs to be refilled due to
significant changes, just go ahead and do it...

jon


Re: [PATCH] mtd: nand: fix spelling in driver api documentation

2018-07-25 Thread Jonathan Corbet
On Wed, 25 Jul 2018 09:29:28 +0200
Miquel Raynal  wrote:

> > > That's not a spelling mistake, that's a factual change.  I'll apply the
> > > patch since it appears to be correct, but will be tweaking the changelog. 
> > >
> > 
> > I think Miquel had planned to apply this patch to the NAND tree, but we
> > don't seem to have conflicting changes on this file, so feel free to
> > take it in the doc tree.
> > 
> > Acked-by: Boris Brezillon   
> 
> Can you confirm you will take this patch?

Yeah, that's what the "I'll apply the patch" part above means :)  It's
already in docs-next.

Thanks,

jon


Re: [PATCH net-next 0/2] docs: net: Convert netdev-FAQ to RST

2018-07-25 Thread Jonathan Corbet
On Wed, 25 Jul 2018 13:28:10 +1000
"Tobin C. Harding"  wrote:

> Since I've already botched it can I ask for guidance here.  The problem
> is updating the links means making changes that will cause merge
> conflicts if they go through net-dev tree (since most references are in
> Documentation/*.rst).  But we can't go through docs tree either since
> that could lead to merge conflicts later as well.

Merge conflicts are a way of life in Documentation/ - everybody messes
with it.  They are usually pretty easy to resolve.

I only see a handful of references to netdev-FAQ.txt in the tree; I would
suggest just making the change and being done with it.  There shouldn't be
any need to do a more complicated dance than that.

And to answer your other question, yes of course it's fine (and expected)
for this to go through Dave's tree.

Thanks,

jon


Re: [PATCH v2] Documentation: proc.txt: Adding 'HardwareCorrupted' field and description.

2018-07-23 Thread Jonathan Corbet
On Fri, 13 Jul 2018 22:58:06 +0530
Prashant Dhamdhere  wrote:

> This patch talks about the 'HardwareCorrupted' field currently missing from
> the 'meminfo' section of 'proc.txt' file. It also includes short description
> of 'HardwareCorrupted' field.

I've gone ahead and applied this.  Please note, though, that the "this
patch..." style of changelogging strongly irritates some developers;
please use an imperative style in the future.  I rewrote the changelog to:

Documentation: proc.txt: Adding 'HardwareCorrupted' field and
description. 

Fill in missing documentation for the HardwareCorrupted field in
proc.txt.

Thanks,

jon


Re: [PATCH 24/32] vfs: syscall: Add fsopen() to prepare for superblock creation [ver #9]

2018-07-11 Thread Jonathan Corbet
On Tue, 10 Jul 2018 23:44:09 +0100
David Howells  wrote:

>   sfd = fsopen("ext4", FSOPEN_CLOEXEC);
>   write(sfd, "s /dev/sdb1"); // note I'm ignoring write's length arg
>   write(sfd, "o noatime");
>   write(sfd, "o acl");
>   write(sfd, "o user_attr");
>   write(sfd, "o iversion");
>   write(sfd, "o ");
>   write(sfd, "r /my/container"); // root inside the fs
>   write(sfd, "x create"); // create the superblock

A minor detail but ... the "r" operation mentioned above is not actually
implemented in this system call.

jon


Re: [PATCH] Documentation: admin-guide: Adding sysrq-key combination for System Z/S390 arch.

2018-07-10 Thread Jonathan Corbet
On Tue, 3 Jul 2018 23:04:47 +0530
Prashant Dhamdhere  wrote:

> Signed-off-by: Prashant Dhamdhere 

Thanks for working to improve the docs.  I do have some requests, though,
starting with: please provide a changelog for all of your patches.

> ---
>  Documentation/admin-guide/sysrq.rst | 5 +
>  1 file changed, 5 insertions(+)
> 
> diff --git a/Documentation/admin-guide/sysrq.rst
> b/Documentation/admin-guide/sysrq.rst
> index 7b9035c01a2e..21deab9e542c 100644
> --- a/Documentation/admin-guide/sysrq.rst
> +++ b/Documentation/admin-guide/sysrq.rst
> @@ -68,6 +68,11 @@ On PowerPC
> Press :kbd:`ALT - Print Screen` (or :kbd:`F13`) - :kbd:` key>`,  
>  :kbd:`Print Screen` (or :kbd:`F13`) - :kbd:`` may
> suffice.
> 
> +On System Z - Press 'CTRL-O-' on the hvc0 console.'CTRL-O'
> means
> +  pressing 'O' (not zero) while holding down the 'CTRL' key.

This patch has been line-wrapped by your mailer.  Please email a patch to
yourself and be sure that you can apply it before trying again.  You can
check Documentation/process/email-clients.rst for information on taming
email clients.

Also, please put spaces after periods.

Readers of this document will know what "CTRL-O" (or "^O") means, that does
not need to be spelled out.

> For
> +  3270 console or line-mode HMC console: Pass '^-'
> +  Here, '^-' means cap and dash characters.

This, though, is rather less clear.  What does "pass" mean in this context?
We all know what ^ and - are.  But what do we do with them?  Just type them
in sequence?  If so, please say so.  Do they have to be after a newline or
anything like that?

> +
>  On other
> If you know of the key combos for other architectures, please
>  let me know so I can add them to this section.

Also, please format the docs with "make htmldocs" or the like and make sure
the right thing happens with your changes.

Thanks,

jon


Re: [PATCH v2] doc: dev-tools: kselftest.rst: update contributing new tests

2018-06-29 Thread Jonathan Corbet
On Fri, 29 Jun 2018 14:52:01 +0200
Anders Roxell  wrote:

> Add a description that kernel config options should be added into a
> config file that is placed next to the newly added test.
> 
> Signed-off-by: Anders Roxell 

Applied, thanks.

jon


Re: [PATCH] doc: add description to dirtytime_expire_seconds

2018-06-26 Thread Jonathan Corbet
On Thu, 31 May 2018 07:56:53 +0800
Yang Shi  wrote:

> commit 1efff914afac8a965ad63817ecf8861a927c2ace ("fs: add
> dirtytime_expire_seconds sysctl") introduced dirtytime_expire_seconds
> knob, but there is not description about it in
> Documentation/sysctl/vm.txt.
> 
> Add the description for it.

Applied to the docs tree, sorry for taking so long to get to it.

Thanks,

jon


Re: [PATCH] docs/admin-guide/mm: add high level concepts overview

2018-05-29 Thread Jonathan Corbet
On Tue, 29 May 2018 14:37:25 +0300
Mike Rapoport  wrote:

> The are terms that seem obvious to the mm developers, but may be somewhat
> obscure for, say, less involved readers.
> 
> The concepts overview can be seen as an "extended glossary" that introduces
> such terms to the readers of the kernel documentation.

So as I read through this I thought of all kinds of ways it could be
improved, but I suspect that will always be the case.  It's a good intro
as-is, so I've applied it.  Thanks!

jon


Re: [PATCH v2] doc: document scope NOFS, NOIO APIs

2018-05-29 Thread Jonathan Corbet
On Tue, 29 May 2018 10:26:44 +0200
Michal Hocko  wrote:

> Although the api is documented in the source code Ted has pointed out
> that there is no mention in the core-api Documentation and there are
> people looking there to find answers how to use a specific API.

So, I still think that this:

> +The traditional way to avoid this deadlock problem is to clear __GFP_FS
> +respectively __GFP_IO (note the latter implies clearing the first as well) in

doesn't read the way you intend it to.  But we've sent you in more
than enough circles on this already, so I went ahead and applied it;
wording can always be tweaked later.

You added the kerneldoc comments, but didn't bring them into your new
document.  I'm going to tack this on afterward, hopefully nobody will
object.

Thanks,

jon

---
docs: Use the kerneldoc comments for memalloc_no*()

Now that we have kerneldoc comments for
memalloc_no{fs,io}_{save_restore}(), go ahead and pull them into the docs.

Signed-off-by: Jonathan Corbet 
---
 Documentation/core-api/gfp_mask-from-fs-io.rst | 5 +
 1 file changed, 5 insertions(+)

diff --git a/Documentation/core-api/gfp_mask-from-fs-io.rst 
b/Documentation/core-api/gfp_mask-from-fs-io.rst
index 2dc442b04a77..e0df8f416582 100644
--- a/Documentation/core-api/gfp_mask-from-fs-io.rst
+++ b/Documentation/core-api/gfp_mask-from-fs-io.rst
@@ -33,6 +33,11 @@ section from a filesystem or I/O point of view. Any 
allocation from that
 scope will inherently drop __GFP_FS respectively __GFP_IO from the given
 mask so no memory allocation can recurse back in the FS/IO.
 
+.. kernel-doc:: include/linux/sched/mm.h
+   :functions: memalloc_nofs_save memalloc_nofs_restore
+.. kernel-doc:: include/linux/sched/mm.h
+   :functions: memalloc_noio_save memalloc_noio_restore
+
 FS/IO code then simply calls the appropriate save function before
 any critical section with respect to the reclaim is started - e.g.
 lock shared with the reclaim context or when a transaction context
-- 
2.14.3



Re: doc: Italian translation

2018-05-28 Thread Jonathan Corbet
On Sun, 27 May 2018 16:55:55 +0200
Federico Vaga  wrote:

> here the doc-guide translated in Italian. This set of patches includes
> some minor changes to the main one. The idea of this first set of patches
> is also to adjust the structure and our expectations.

I've only done a quick scan so far.  It looks reasonable, but I have a
couple of requests:

 - Please include a proper changelog with each patch describing what the
   patch does and why.  Otherwise I'll have to fill them in, and that
   makes me grumpy...:)

 - You might as well add a MAINTAINERS entry.  The other translations
   don't have them, but they should.

 - For extra credit: it's time to move the translations out of the
   top-level index into an index.rst in the translations directory.  Then
   the top-level file can have a single pointer to the translations.

> We tried to translate everything in **Italian**; which means that we avoided
> imported English words wherever there is the possibility to use the Italian
> ones. Of course, this is not always possible, or worst doing the translation
> make it less clear, for example the word "file".

"We"?  Is there somebody else's work represented here too?  If so, they
should appear in the signoff chain (or as a Co-developed-by credit).

> Another point. I noticed that the disclaimer for other translations is
> in English, so I did the same. But actually shouldn't be in Italian, since
> that page will be read by Italian speakers?

Perhaps, though part of the idea is to give the English speakers, too,
some vague clue of what they're looking at.

Thanks,

jon


Re: [PATCH] doc: document scope NOFS, NOIO APIs

2018-05-24 Thread Jonathan Corbet
On Thu, 24 May 2018 13:43:41 +0200
Michal Hocko  wrote:

> From: Michal Hocko 
> 
> Although the api is documented in the source code Ted has pointed out
> that there is no mention in the core-api Documentation and there are
> people looking there to find answers how to use a specific API.
> 
> Cc: "Darrick J. Wong" 
> Cc: David Sterba 
> Requested-by: "Theodore Y. Ts'o" 
> Signed-off-by: Michal Hocko 
> ---
> 
> Hi Johnatan,
> Ted has proposed this at LSFMM and then we discussed that briefly on the
> mailing list [1]. I received some useful feedback from Darrick and Dave
> which has been (hopefully) integrated. Then the thing fall off my radar
> rediscovering it now when doing some cleanup. Could you take the patch
> please?
> 
> [1] http://lkml.kernel.org/r/20180424183536.gf30...@thunk.org
>  .../core-api/gfp_mask-from-fs-io.rst  | 55 +++
>  1 file changed, 55 insertions(+)
>  create mode 100644 Documentation/core-api/gfp_mask-from-fs-io.rst

So you create the rst file, but don't add it in index.rst; that means it
won't be a part of the docs build and Sphinx will complain.

> diff --git a/Documentation/core-api/gfp_mask-from-fs-io.rst 
> b/Documentation/core-api/gfp_mask-from-fs-io.rst
> new file mode 100644
> index ..e8b2678e959b
> --- /dev/null
> +++ b/Documentation/core-api/gfp_mask-from-fs-io.rst
> @@ -0,0 +1,55 @@
> +=
> +GFP masks used from FS/IO context
> +=
> +
> +:Date: Mapy, 2018

Ah...the wonderful month of Mapy:)

> +:Author: Michal Hocko 
> +
> +Introduction
> +
> +
> +Code paths in the filesystem and IO stacks must be careful when
> +allocating memory to prevent recursion deadlocks caused by direct
> +memory reclaim calling back into the FS or IO paths and blocking on
> +already held resources (e.g. locks - most commonly those used for the
> +transaction context).
> +
> +The traditional way to avoid this deadlock problem is to clear __GFP_FS
> +resp. __GFP_IO (note the later implies clearing the first as well) in

"resp." is indeed a bit terse.  Even spelled out as "respectively", though,
I'm not sure what the word is intended to mean here.  Did you mean "or"?

> +the gfp mask when calling an allocator. GFP_NOFS resp. GFP_NOIO can be

Here too.

> +used as shortcut. It turned out though that above approach has led to
> +abuses when the restricted gfp mask is used "just in case" without a
> +deeper consideration which leads to problems because an excessive use
> +of GFP_NOFS/GFP_NOIO can lead to memory over-reclaim or other memory
> +reclaim issues.
> +
> +New API
> +
> +
> +Since 4.12 we do have a generic scope API for both NOFS and NOIO context
> +``memalloc_nofs_save``, ``memalloc_nofs_restore`` resp. 
> ``memalloc_noio_save``,
> +``memalloc_noio_restore`` which allow to mark a scope to be a critical
> +section from the memory reclaim recursion into FS/IO POV. Any allocation

"from a filesystem or I/O point of view" ?

> +from that scope will inherently drop __GFP_FS resp. __GFP_IO from the given
> +mask so no memory allocation can recurse back in the FS/IO.

Wouldn't it be nice if those functions had kerneldoc comments that could be
pulled in here! :)

> +FS/IO code then simply calls the appropriate save function right at the
> +layer where a lock taken from the reclaim context (e.g. shrinker) and

where a lock *is* taken ?

> +the corresponding restore function when the lock is released. All that
> +ideally along with an explanation what is the reclaim context for easier
> +maintenance.
> +
> +What about __vmalloc(GFP_NOFS)
> +==
> +
> +vmalloc doesn't support GFP_NOFS semantic because there are hardcoded
> +GFP_KERNEL allocations deep inside the allocator which are quite non-trivial
> +to fix up. That means that calling ``vmalloc`` with GFP_NOFS/GFP_NOIO is
> +almost always a bug. The good news is that the NOFS/NOIO semantic can be
> +achieved by the scope api.

Agree with others on "API"

> +In the ideal world, upper layers should already mark dangerous contexts
> +and so no special care is required and vmalloc should be called without
> +any problems. Sometimes if the context is not really clear or there are
> +layering violations then the recommended way around that is to wrap 
> ``vmalloc``
> +by the scope API with a comment explaining the problem.

Thanks,

jon


Re: [PATCH] docs: update kernel versions and dates in tables

2018-05-23 Thread Jonathan Corbet
On Wed, 23 May 2018 15:20:14 -0700
Tim Bird  wrote:

> Every once in a while, we should update the examples
> to reflect more recent kernel versions.
> 
> Update the tables describing kernel releases, the merge window,
> and current longterm maintained kernel, from 2.6-era kernels
> to 4.x.

I dunno...it's only been since 2011...aren't you being a little hasty?

:)

Applied, thanks.

jon


Re: [PATCH 6/6] Drop flex_arrays

2018-05-23 Thread Jonathan Corbet
On Tue, 22 May 2018 21:18:21 -0400
Kent Overstreet  wrote:

> All existing users have been converted to generic radix trees
> 
> Signed-off-by: Kent Overstreet 
> ---
>  Documentation/core-api/flexible-arrays.rst | 130 ---
>  Documentation/flexible-arrays.txt  | 123 ---
>  include/linux/flex_array.h | 149 
>  include/linux/poison.h |   3 -
>  lib/Makefile   |   2 +-
>  lib/flex_array.c   | 398 -
>  tools/include/linux/poison.h   |   3 -
>  7 files changed, 1 insertion(+), 807 deletions(-)
>  delete mode 100644 Documentation/core-api/flexible-arrays.rst
>  delete mode 100644 Documentation/flexible-arrays.txt
>  delete mode 100644 include/linux/flex_array.h
>  delete mode 100644 lib/flex_array.c

Interesting, I didn't realize that flexible-arrays.txt was still there;
that should go regardless (and 00-INDEX adjusted accordingly).  If you zap
the RST file, though, you should also fix Documentation/core-api/index.rst
or you'll break the docs build.

Thanks,

jon


Re: [PATCH 0/3] docs/vm: transhuge: split userspace bits to admin-guide/mm

2018-05-21 Thread Jonathan Corbet
On Mon, 14 May 2018 11:13:37 +0300
Mike Rapoport  wrote:

> Here are minor updates to transparent hugepage docs. Except from minor
> formatting and spelling updates, these patches re-arrange the transhuge.rst
> so that userspace interface description will not be interleaved with the
> implementation details and it would be possible to split the userspace
> related bits to Documentation/admin-guide/mm, which is done by the third
> patch.

Looks good, I've applied the set, after adding a changelog for #3.

Thanks,

jon


Re: [PATCH v2] coresight: documentation: update sysfs section

2018-05-16 Thread Jonathan Corbet
On Mon, 14 May 2018 12:19:59 -0500
Kim Phillips  wrote:

> - Align and show updated ls devices output from the TC2, based on
>   current driver
> 
> - Provide an example from an ETMv4 based system (Juno)
> 
> - Reflect changes to the way the RAM write pointer is accessed since
>   it got changed in commit 7d83d17795ef ("coresight: tmc: adding sysFS
>   management entries").

So I was going to apply this, but it's been pretty badly corrupted by
your mailer.  Could I ask you to retry, please?

Thanks,

jon


Re: [PATCH] Documentation: arm: clean up Marvell Berlin family info

2018-05-16 Thread Jonathan Corbet
On Mon, 14 May 2018 17:55:10 -0400
Thomas Hebb  wrote:

> Remove dead links, make spacing consistent, and note that the family was
> acquired by Synaptics in 2017.
> 
> Signed-off-by: Thomas Hebb 

Applied to the docs tree, thanks.

jon


Re: [PATCH] Documentation: gpio: driver: Fix a typo and some odd grammar

2018-05-16 Thread Jonathan Corbet
On Wed, 16 May 2018 14:08:00 +0200
Jonathan Neuschäfer  wrote:

> Signed-off-by: Jonathan Neuschäfer 

Applied, thanks.

jon


Re: linux-next: Signed-off-by missing for commit in the jc_docs tree

2018-05-10 Thread Jonathan Corbet
On Fri, 11 May 2018 07:40:49 +1000
Stephen Rothwell  wrote:

> Commit
> 
>   5a779c40a8ad ("Revert "Documentation/features/vm: Remove arch support 
> status file for 'pte_special'"")
> 
> is missing a Signed-off-by from its author and committer.  Reverts are
> commits too. ;-)

Argh.  I'm really not having a good time with this.

I've rebase-fixed it, I doubt anybody (except you! :) has pulled my tree
in the half-hour it was there...apologies if I'm wrong.

Thanks,

jon


Re: [PATCH v2 00/11] Fix some doc build warnings/errors and broken links

2018-05-10 Thread Jonathan Corbet
On Wed,  9 May 2018 10:18:43 -0300
Mauro Carvalho Chehab  wrote:

> Patches 1 to 5 on this series contain the patches that weren't yet
> applied from the past patch series and touch only at Documentation.
> There are two changes there:
>   patch 2: fixed the description and added a c/c to cgroup maintainers;
>   patch 4: rewritten according with Louis request, droping several hunks.

Of these, I've applied 2, 4, and 6.  The networking and crypto folks like
to apply their own documentation fixes; I assume they'll pick these up.

> Patch 6 rewrites scripts/documentation-file-ref-check on Perl,
> adding an auto-fix feature.

Applied this one.

> Patches 7 and 8 fix things that would cause troubles for the
> automatic autocorrection tool.

#7 is applied.  #8 doesn't apply, though; I'm not sure which tree you made
it against?  In any case, I've stopped here for now.

> Patch 9 touches a lot of random places (including MAINTAINERS)
> that contain broken links and can be auto-fixed. It could be
> broken into one patch per touched file, but I think that is
> overkill. 

Let's keep this one (and the ones that follow) aside.  I'm happy to apply
them, but I think they are best applied as an end-of-merge-window thing.  I
envision lots of conflicts, and I already have a pile of those to explain
to Linus this time around.

Sound good?

Thanks,

jon


Re: [PATCH -mm] mm, THP, doc: Add document for thp_swpout/thp_swpout_fallback

2018-05-10 Thread Jonathan Corbet
On Wed,  9 May 2018 16:23:41 +0800
"Huang, Ying"  wrote:

> From: Huang Ying 
> 
> Add document for newly added thp_swpout, thp_swpout_fallback fields in
> /proc/vmstat.
> 
> Signed-off-by: "Huang, Ying" 
> Cc: "Kirill A. Shutemov" 
> Cc: Andrea Arcangeli 
> Cc: Johannes Weiner 

Applied, thanks.

jon


Re: [PATCH] Documentation/process/posting: wrap text at 80 cols

2018-05-10 Thread Jonathan Corbet
On Thu, 10 May 2018 20:37:37 +0100
Justin Skists  wrote:

> Trivial patch to adjust the text formatting to wrap at 80 columns. No
> actual content has changed.
> 
> Signed-off-by: Justin Skists 

Applied, thanks.

jon


Re: [PATCH v2 02/11] docs: admin-guide: add cgroup-v2 documentation

2018-05-10 Thread Jonathan Corbet
On Thu, 10 May 2018 11:40:18 -0700
Tejun Heo  wrote:

> On Wed, May 09, 2018 at 10:18:45AM -0300, Mauro Carvalho Chehab wrote:
> > The cgroup-v2.txt is already in ReST format. So, move it to the
> > admin-guide, where it belongs.
> > 
> > Cc: Tejun Heo 
> > Cc: Li Zefan 
> > Cc: Johannes Weiner 
> > Signed-off-by: Mauro Carvalho Chehab   
> 
> Acked-by: Tejun Heo 

Applied to the docs tree, thanks.

jon


Re: [RFC PATCH 1/2] scripts/kernel-doc: Auto-detect common code-blocks

2018-05-10 Thread Jonathan Corbet
On Thu, 10 May 2018 09:34:56 -0700
Matthew Wilcox  wrote:

> I think this is a bit fragile.  Why not just search for ':\n'?  Is
> there ever a case where we want to write:
> 
> /**
>  * foo is a bar:
>  * wibble
>  */
> and have wibble not be a code-block?

Yeah, we might want to write something like:

 - Leading off a bulleted list

 1) or a numbered list

for example.  That's why I was thinking of looking for explicit markers
for such lists.

It'll take some playing around with to have a hope of getting right,
methinks.

jon


Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

2018-05-10 Thread Jonathan Corbet
On Thu, 10 May 2018 11:21:13 -0300
Mauro Carvalho Chehab  wrote:

> The problem with a hint-based mechanism is that it will generate
> false hints. If added, we may end by needing to add extra tags to
> disable the hints mechanism where it gets wrong, or to periodically
> do code changes at kernel-doc comments in order to make the hints
> logic happy.
> 
> So, IMO, we should provide non-hints based mechanism, like forcing the
> string that prepends the colon to have a keyword that will make it to
> parse the block as literal, where expressions like:
> 
>   See the code-block foo:
>   See the following code example:
>   See the following flow diagram:
>   See the following artwork:
> 
> Is the best alternative to avoid "::", as on the enclosed patch.

But this, too, is a hint-based mechanism.  Thanks for the patches, I'll
keep them around, but I would like an opportunity to try to do better
before applying them.  I fear that using magic words in this way will
lead to a constant stream of surprises, and I'd like to avoid that if
possible...

Thanks,

jon


Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

2018-05-10 Thread Jonathan Corbet
On Thu, 10 May 2018 07:30:12 -0600
Jonathan Corbet <cor...@lwn.net> wrote:

> > (Peter said):  
> > > Independent of any philosophical discussion not allowing a setence to
> > > end with a single ':' is completely idiotic.  Please fix the tooling
> > > instead to allow it, as it is very important for being able to just
> > > write understandable comments.

*Sigh*.  Of course, Christoph said that, not Peter.  Time for more coffee.

jon


Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

2018-05-10 Thread Jonathan Corbet
On Thu, 10 May 2018 06:38:05 -0300
Mauro Carvalho Chehab  wrote:

> (Peter said):
> > Independent of any philosophical discussion not allowing a setence to
> > end with a single ':' is completely idiotic.  Please fix the tooling
> > instead to allow it, as it is very important for being able to just
> > write understandable comments.  

FWIW, there's no problem with a sentence ending with a single colon.
It's only an issue if you want to flag a special interpretation for the
text that follows that sentence.  Just to be precise.

> Patches are welcome, although I don't see any easy way to solve it.

I could envision some sort of heuristic that would recognize an indented
block containing code.  Probably we could go simpler and force the
"literal block" treatment for any indented block that lacks explicit
enumeration markers.  So:

this->would_be("a literal block");

but:

  - This would not be

Such a thing would likely be a bit fragile (people feel, rightly, that
they can put anything into normal text) but it might just work well
enough.  For best results, it should probably be done as part of Sphinx
itself, rather than yet another ugly hack in the kerneldoc script.

This particular problem may be solvable, and I'll look into it, but not
right away.  The offline world is being rather insistently obnoxious
these days...

jon


Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

2018-05-10 Thread Jonathan Corbet
On Thu, 10 May 2018 14:23:35 +0200
Andrea Parri  wrote:

> only
> remember that other people (including some developers running into the
> "disadventure" of opening an RST doc. from their preferred text editor
> and being brought to conclude:  "WTH!  I need to open a web browser, I
> guess...") _use_ such doc. and _do care_ about it, and that what might
> be an improvement for some people might look as "vandalizing" to others.

If you have an example of a place where use of a web browser has been
made mandatory, please point it out.  Avoiding that was at the top of the
list of explicit requirements.  Surely an extra colon is not going to
force you to run screaming to the protective embrace of Firefox...?

Thanks,

jon


Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

2018-05-09 Thread Jonathan Corbet
On Wed, 9 May 2018 17:20:26 +0200
Peter Zijlstra  wrote:

> The whole rst wankery is detrimental to that interface in order to
> pander to something else.. I don't see the value. I've objected before,
> and I suppose I'll object again.

One person's wankery is another's integrated, browsable, and searchable
documentation that shows some signs of having actually been thought about,
I guess.

> > It's a simple colon.  It goes along with the /** marker for kerneldoc
> > comments and the @ markers found within them, both of which you seem to
> > have found a way to live with.  
> 
> Barely, and personally I tend to not bother with kerneldoc much. Most of
> the comments I write lack the extra *, and I note that the other fix to
> this problem it to drop that spurious * here as well.

Perhaps you'd like to post a patch removing the kerneldoc mechanism?  It
would make my life a lot easier...:)

> The @arg thing is okay, it clearly distinguishes arguments/variable
> names from regular text. But "::" is the C++ class member syntax, not
> the start of an English enumeration or the like.

Not sure what C++ has to do with anything, unless we want to bring in
$LANGUAGE_WE_DISRESPECT spuriously.  I'm sure it's the Perl
do-five-different-things-magically syntax too.  It's probably an entire
natural-language processing system in Haskell.  It also happens to be the
Sphinx "start literal block" syntax.

> > You're not the only consumer of the docs.  You may not appreciate the
> > improvements that have come, but others certainly do.  I do hope that you
> > can find it in youself to avoid vandalizing things for everybody else ...?  
> 
> Why should I care for people not using text editors to write code?

The set of "people using text editors to write code" is a superset
of the set containing only Peter Zijlstra.  Many of the people who have
used text editors to write the very code we all work on find a minimally
structured documentation system to be useful.  Out of respect for them, if
nothing else, I'll ask again, please, that you suffer the substantial
cognitive drain of skipping over an extra colon.

Thanks,

jon


Re: linux-next: manual merge of the akpm-current tree with the jc_docs tree

2018-05-09 Thread Jonathan Corbet
On Wed, 9 May 2018 18:53:28 +0200
Andrea Parri  wrote:

> > Now that I look a little closer, I think the real issue is that the
> > "features" documentation assumes that there's a Kconfig option for each,
> > but there isn't in this case.  The lack of a Kconfig option does not,
> > this time around, imply that the feature has gone away.
> > 
> > I think that I should probably revert this patch in the short term.
> > Longer-term, it would be good to have an alternative syntax for "variable
> > set in the arch headers" to describe situations like this.  
> 
> Both matters were discussed during v1:
> 
>   
> http://lkml.kernel.org/r/1522774551-9503-1-git-send-email-andrea.pa...@amarulasolutions.com
> 
> ... (and the glory details are documented in features-refresh.sh ;-) ).

So I'll admit to being confused, since I don't see discussion of the
actual topic at hand.

> As I suggested above, simply reverting this patch will leave this file,
> (and only this file!) out-of-date (and won't resolve the conflict with
> Laurent's patch ...).

Reverting this patch retains the updates from earlier in the series, and
does indeed make the conflict go away, so I'm still confused.  What am I
missing?

Thanks,

jon


Re: linux-next: manual merge of the akpm-current tree with the jc_docs tree

2018-05-09 Thread Jonathan Corbet
On Wed, 9 May 2018 15:28:24 +0200
Andrea Parri  wrote:

> > BTW, it would be nice if the the question "Why was this file removed?" was
> > answered by that jc_docs commit message ...  I actually wonder if this
> > file needs to return (I have no way of knowing).  
> 
> My bad; thanks for pointing this out.
> 
> Mmh... "why" would have been something like "the feature has no Kconfig". ;-)
> 
> I defer to your (community) decision regarding "if this file needs to return"
> (Cc-ing Ingo, who created the file and also suggested its removal); I remain
> available for preparing the patch to restore (and refresh) this file, should
> you agree with this approach.

So I'll confess that I balked on the lack of a changelog, but then decided
to proceed with the patch (and the other removal as well) due to the lack
of the Kconfig option.

Now that I look a little closer, I think the real issue is that the
"features" documentation assumes that there's a Kconfig option for each,
but there isn't in this case.  The lack of a Kconfig option does not,
this time around, imply that the feature has gone away.

I think that I should probably revert this patch in the short term.
Longer-term, it would be good to have an alternative syntax for "variable
set in the arch headers" to describe situations like this.

Make sense?

Thanks,

jon


Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

2018-05-09 Thread Jonathan Corbet
On Wed, 9 May 2018 10:41:20 +0200
Peter Zijlstra  wrote:

> > This is easily done by using "::" instead of just ":".  
> 
> And I'll voice my objection once again. This makes a regular comment
> worse. This rst stuff is utter shit for making normal text files less
> readable in your favourite text editor.
> 
> If this gets merged, I'll simply remove that spurious ':' the next time
> I'm near that comment.

Seriously, Peter?

It's a simple colon.  It goes along with the /** marker for kerneldoc
comments and the @ markers found within them, both of which you seem to
have found a way to live with.

The RST work was discussed for a year before we even started.  It has
brought in the efforts of a large number of developers, all of whom see
the value in actually caring about our documentation and making it
accessible to a much larger group of readers.  And it has all happened
while preserving the primacy of the plain-text documentation.

You're not the only consumer of the docs.  You may not appreciate the
improvements that have come, but others certainly do.  I do hope that you
can find it in youself to avoid vandalizing things for everybody else ...?

Thanks,

jon


Re: [PATCH 18/18] w1: w1_io.c: fix a kernel-doc warning

2018-05-09 Thread Jonathan Corbet
On Wed, 9 May 2018 09:32:18 -0300
Mauro Carvalho Chehab  wrote:

> > Looks good to me, thank you!
> > What tree should this be forwarded to, or folks from linux doc will pick it 
> > up?
> > 
> > Acked-by: Evgeniy Polyakov   
> 
> Jon prefers if this could go via the usual maintainer's tree.
> 
> So, could you send it via yours?

With the ack I can pick it up, no worries.  I somehow missed this when I
went through the set.

Thanks,

jon


Re: [PATCH] Documentation: refcount-vs-atomic: Update reference to LKMM doc.

2018-05-08 Thread Jonathan Corbet
On Fri,  4 May 2018 23:11:49 +0200
Andrea Parri  wrote:

> The LKMM project has moved to 'tools/memory-model/'.
> 
> Signed-off-by: Andrea Parri 

Applied, thanks.

jon


Re: [PATCH 00/18] Fix some build warnings/errors with Sphinx

2018-05-08 Thread Jonathan Corbet
On Mon,  7 May 2018 06:35:36 -0300
Mauro Carvalho Chehab  wrote:

> I decided to give a try with Sphinx last stable version
> (1.17.4), and noticed several issues. The worse one was
> with the networking book: a non-standard footnote there
> with [*] instead of a number causes it to break PDF building.
> 
> So, I took some spare time to address some warnings all over
> the tree, and moved a few text documents to a book. 

OK, I've applied the ones that seem to make sense for me to take now.
There's comments on the firmware one, and I'd rather have Tejun's OK for
the cgroup one.  The code-comment changes should probably go via the
usual maintainers.

> I with
> I had more time to move the other ones and to solve other
> warnings.

You and me both - but each step helps!

Thanks,

jon


Re: [PATCH 08/18] docs: driver-api: add clk documentation

2018-05-08 Thread Jonathan Corbet
On Mon,  7 May 2018 06:35:44 -0300
Mauro Carvalho Chehab  wrote:

> The clk.rst is already in ReST format. So, move it to the
> driver-api guide, where it belongs.
> 
> Signed-off-by: Mauro Carvalho Chehab 

Applied, thanks.

jon


Re: [PATCH 07/18] docs: core-api: add circular-buffers documentation

2018-05-08 Thread Jonathan Corbet
On Mon,  7 May 2018 06:35:43 -0300
Mauro Carvalho Chehab  wrote:

> The circular-buffers.txt is already in ReST format. So, move it to the
> core-api guide, where it belongs.
> 
> Signed-off-by: Mauro Carvalho Chehab 

Applied, thanks.

jon


Re: [PATCH 05/18] docs: core-api: add cachetlb documentation

2018-05-08 Thread Jonathan Corbet
On Mon,  7 May 2018 06:35:41 -0300
Mauro Carvalho Chehab  wrote:

> The cachetlb.txt is already in ReST format. So, move it to the
> core-api guide, where it belongs.
> 
> Signed-off-by: Mauro Carvalho Chehab 

I think we could do a better job of this by integrating it with the
kerneldoc comments.  Meanwhile, though, this is a step in the right
direction, so I've applied it, thanks.

jon


Re: [PATCH 04/18] docs: admin-guide: add bcache documentation

2018-05-08 Thread Jonathan Corbet
On Mon,  7 May 2018 06:35:40 -0300
Mauro Carvalho Chehab  wrote:

> The bcache.txt is already in ReST format. So, move it to the
> admin guide, where it belongs.
> 
> Signed-off-by: Mauro Carvalho Chehab 

Applied, thanks.

jon


Re: [PATCH 03/18] docs: */index.rst: Add newer documents to their respective index.rst

2018-05-08 Thread Jonathan Corbet
On Mon,  7 May 2018 06:35:39 -0300
Mauro Carvalho Chehab  wrote:

> A number of new docs were added, but they're currently not on
> the index.rst from the session they're supposed to be, causing
> Sphinx warnings.
> 
> Add them.
> 
> Signed-off-by: Mauro Carvalho Chehab 

I've applied this one, thanks.

jon


Re: [PATCH 06/18] docs: core-api: add cgroup-v2 documentation

2018-05-08 Thread Jonathan Corbet
On Mon,  7 May 2018 06:35:42 -0300
Mauro Carvalho Chehab  wrote:

> The cgroup-v2.txt is already in ReST format. So, move it to the
> core-api guide, where it belongs.
> 
> Signed-off-by: Mauro Carvalho Chehab 

Honestly, this seems to me like sysadmin material, so I think it should
go into the admin guide instead.

Actually, looking at the patch, it seems you agree - it's just the
changelog that's wrong :)

I could fix that, but it should probably be posted with a CC to Tejun
first.

Thanks,

jon


Re: [PATCH 0/3] docs/vm: move numa_memory_policy.rst to admin-guide/mm

2018-05-08 Thread Jonathan Corbet
On Tue,  8 May 2018 10:02:07 +0300
Mike Rapoport  wrote:

> These patches include minor formatting and spelling updates to
> Documentation/vm/numa_memory_policy.rst and move this file to
> Documentation/admin-guide/mm.

Set applied - thanks!

jon


Re: [RFC PATCH v3 0/6] Documentation/features: Provide and apply 'features-refresh.sh'

2018-05-08 Thread Jonathan Corbet
On Mon,  7 May 2018 12:43:37 +0200
Andrea Parri  wrote:

> This series provides the script 'features-refresh.sh', which operates on
> the arch support status files, and it applies this script to refresh the
> status files in place; previous discussions about this series are at [1].

Looks good, I've applied the set, thanks.

jon


Re: [PATCH] Documentation: block: cmdline-partition.txt fixes and additions

2018-05-08 Thread Jonathan Corbet
On Sun, 6 May 2018 11:50:29 -0700
Randy Dunlap  wrote:

> Make the description of the kernel command line option "blkdevparts"
> a bit more flowing and readable.
> 
> Fix a few typos.
> Add the optional  and  suffixes.
> Note that size can be "-" to indicate all of the remaining space.
> 
> Signed-off-by: Randy Dunlap 

Applied, thanks.

jon


Re: [PATCH] vfio: fix documentation

2018-05-08 Thread Jonathan Corbet
On Mon, 7 May 2018 11:02:10 +0800
"dongbo (E)"  wrote:

> Update vfio_add_group_dev description to match the current API.
> 
> Signed-off-by: Dong Bo 

Applied, thanks.

jon


Re: [PATCH] doc: botching-up-ioctls: Make it clearer why structs must be padded

2018-05-08 Thread Jonathan Corbet
On Wed,  2 May 2018 09:51:06 +0200
Daniel Vetter  wrote:

> This came up in discussions when reviewing drm patches.

Applied, thanks.

> Aside: I wonder whether we shouldn't move this to some other place and
> rst-ify it? Any good suggestions?

For the moment, probably in Documentation/process, next to
volatile-considered-harmful.rst and such.  Even better, of course, would
be to have some nice document on designing user-space APIs in general...
one can always dream ... :)

Thanks,

jon


Re: [PATCH resend] VFS: simplify seq_file iteration code and interface

2018-04-30 Thread Jonathan Corbet
On Mon, 30 Apr 2018 11:50:04 +1000
NeilBrown <ne...@suse.com> wrote:

> This patch simplifies the interface for first/next iteration and
> simplifies the code, while maintaining complete backward
> compatability.  Now:
> 
> - if ->start() is given a pos of zero, it should return an iterator
>   placed at the start of the sequence
> - if ->start() is given a non-zero pos, it should return the iterator
>   in the same state it was after the last ->start or ->next.
> 
> This is particularly useful for interators which walk the multiple
> chains in a hash table, e.g. using rhashtable_walk*. See
> fs/gfs2/glock.c and drivers/staging/lustre/lustre/llite/vvp_dev.c

For the docs part:

Acked-by: Jonathan Corbet <cor...@lwn.net>

jon


Re: [PATCH 0/7] docs/vm: update KSM documentation

2018-04-27 Thread Jonathan Corbet
On Tue, 24 Apr 2018 09:40:21 +0300
Mike Rapoport  wrote:

> These patches extend KSM documentation with high level design overview and
> some details about reverse mappings and split the userspace interface
> description to Documentation/admin-guide/mm.
> 
> The description of some KSM sysfs attributes is changed so that it won't
> include implementation detail. The description of these implementation
> details are moved to the new "Design" section.
> 
> The last patch in the series depends on the patchset that create
> Documentation/admin-guide/mm [1], all the rest applies cleanly to the
> current docs-next.

I've applied the set, thanks.

jon


Re: [PATCH] Documentation: driver-api: fix device_connection.rst kernel-doc error

2018-04-27 Thread Jonathan Corbet
On Thu, 26 Apr 2018 18:29:41 -0700
Randy Dunlap  wrote:

> Using incorrect :functions: syntax (extra space) causes an odd kernel-doc
> warning, so fix that.
> 
> Documentation/driver-api/device_connection.rst:42: ERROR: Error in 
> "kernel-doc" directive:

Applied, thanks.

jon


Re: [PATCH] documentation: core-api: rearrange a few kernel-api chapters and sections

2018-04-27 Thread Jonathan Corbet
On Thu, 26 Apr 2018 18:11:02 -0700
Randy Dunlap  wrote:

> Rearrange some kernel-api chapters and sections to group them
> together better.
> 
> - move Bit Operations from Basic C Library Functions to Basic
>   Kernel Library Functions (now adjacent to Bitmap Operations since
>   they are not typical C library functions)
> 
> - move Sorting from Math Functions to Basic Kernel Library Functions
>   since sort functions are more Basic than Math Functions
> 
> - move Text Searching from Math Functions to Basic Kernel Library
>   Functions (keep Sorting and Searching close to each other)
> 
> - combine CRC and Math functions together into the (newly named)
>   CRC and Math Functions chapter

The changes look good.  But ... grr... some of the stuff you are moving
around was introduced in -rc2 via the networking tree.  That kind of thing
makes life harder than it needs to be.  I've sorted it out and applied the
patch, thanks.

jon


Re: [PATCH 0/7] docs/vm: start moving files do Documentation/admin-guide`

2018-04-27 Thread Jonathan Corbet
On Wed, 18 Apr 2018 11:07:43 +0300
Mike Rapoport  wrote:

> These pacthes begin categorizing memory management documentation.  The
> documents that describe userspace APIs and do not overload the reader with
> implementation details can be moved to Documentation/admin-guide, so let's
> do it :)

Looks good, set applied, thanks.

jon


Re: [PATCH v2 0/3] coresight: Refresh documenation

2018-04-27 Thread Jonathan Corbet
On Tue, 17 Apr 2018 10:08:04 -0600
Mathieu Poirier  wrote:

> Now that the perf tools CoreSight support is upstream this set adds
> documentation to go with it and move things around so that topics 
> are located together.

I've applied the set, thanks.

jon


Re: [PATCH v2] doc: dev-tools: kselftest.rst: update contributing new tests

2018-04-27 Thread Jonathan Corbet
On Thu, 19 Apr 2018 12:28:25 +0200
Anders Roxell  wrote:

> Add a description that the kernel headers should be used as far as it is
> possible and then the system headers.
> 
> Signed-off-by: Anders Roxell 

Applied, thanks.

jon


Re: [PATCH v3] docs: kernel-parameters.txt: Fix whitespace

2018-04-27 Thread Jonathan Corbet
On Wed, 18 Apr 2018 20:51:39 +0200
Thymo van Beers  wrote:

> Some lines used spaces instead of tabs at line start.
> This can cause mangled lines in editors due to inconsistency.
> 
> Replace spaces for tabs where appropriate.

Applied, thanks.

jon


Re: [PATCH] linux-next: ftrace/docs: Fix spelling typos in ftrace-users.rst

2018-04-27 Thread Jonathan Corbet
On Fri, 27 Apr 2018 18:17:09 -0400
Steven Rostedt  wrote:

> I just noticed that this was never applied.
> 
> Jon, can you take this?

Wow...from November.  Not sure what happened...applied now, thanks.

jon


Re: [PATCH v2] Documentation: typec.rst: Use literal-block element with ascii art

2018-04-25 Thread Jonathan Corbet
On Wed, 25 Apr 2018 16:47:01 +0300
Jani Nikula  wrote:

> On Fri, 06 Apr 2018, Heikki Krogerus  wrote:
> > Using reStructuredText literal-block element with ascii-art.
> > That prevents the ascii art from being processed as
> > reStructuredText.
> >
> > Reported-by: Masanari Iida 
> > Fixes: bdecb33af34f ("usb: typec: API for controlling USB Type-C 
> > Multiplexers")
> > Signed-off-by: Heikki Krogerus   
> 
> Jon, this fixes a documentation build failure in v4.17-rc1. It's not
> just a warning, it's a complete fail. Our docs builder at 01.org is
> failing, apparently the same at kernel.org. Please pick it up soon.

Sorry, I'd seen the attached and was assuming Greg would ship it
Linusward.  I'll get it upstream soon.

jon

From: Greg KH 
To: changbin...@intel.com
Cc: cor...@lwn.net, linux-...@vger.kernel.org, 
linux-kernel@vger.kernel.org
Subject: Re: [PATCH] Documentation: fix reST markup error in  
driver-api/usb/typec.rst
Date: Sun, 8 Apr 2018 09:19:58 +0200
Sender: linux-kernel-ow...@vger.kernel.org

On Sun, Apr 08, 2018 at 10:47:12AM +0800, changbin...@intel.com wrote:
> From: Changbin Du 
> 
> There is an format error in driver-api/usb/typec.rst that breaks sphinx
> docs building.
> 
> reST markup error:
> /home/changbin/work/linux/Documentation/driver-api/usb/typec.rst:215: 
> (SEVERE/4) Unexpected section title or transition.
> 
> 
> Documentation/Makefile:68: recipe for target 'htmldocs' failed
> make[1]: *** [htmldocs] Error 1
> Makefile:1527: recipe for target 'htmldocs' failed
> make: *** [htmldocs] Error 2
> 
> Signed-off-by: Changbin Du 
> ---
>  Documentation/driver-api/usb/typec.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)  

Thanks, someone else already sent this, sorry.  I'll be sending it
onward after 4.17-rc1 is out.

greg k-h


Re: [patch 8/9] LICENSES: Add CC-BY-SA-4.0 license text

2018-04-23 Thread Jonathan Corbet
On Mon, 23 Apr 2018 10:26:35 +0200
Greg Kroah-Hartman  wrote:

> > > Willy, it's your file, Documentation/core-api/idr.rst that is needing
> > > this addition to the LICENSES directory.  While I'm all for CC licenses
> > > for Documentation, we don't seem to be very consistent with them.
> > > Should this be the "default" license we choose for documentation for now
> > > on?  
> > 
> > I'm all for it. If we can agree than this should move to preferred/ and not
> > to other/  
> 
> Ok, that sounds good, Jon?  I know you have looked into picking a decent
> license for documentation, any thoughts here?

CC-BY-SA is a good license for docs, but it's not GPL-compatible, so I
don't think that anything with that license can incorporate kerneldoc
comments or, conceivably, be integrated into the whole sphinx document
tree (which does use those comments).  That leads to my own believe that
the docs really need to be GPL-licensed, even though it's not the ideal
solution.

I suppose it might be worth putting this question to the LF lawyers to
see what they think.  It's not as if I really know what I'm talking
about, after all...

jon


Re: [PATCH 00/32] docs/vm: convert to ReST format

2018-04-16 Thread Jonathan Corbet
On Sun, 15 Apr 2018 20:36:56 +0300
Mike Rapoport  wrote:

> I didn't mean we should keep it as unorganized jumble of stuff and I agree
> that splitting the documentation by audience is better because developers
> are already know how to find it :)
> 
> I just thought that putting the doc into the place should not be done
> immediately after mechanical ReST conversion but rather after improving the
> contents.

OK, this is fine.  I'll go ahead and apply the set, but then I'll be
watching to see that the other improvements come :)

In applying the set, there was a significant set of conflicts with
vm/hmm.rst; hopefully I've sorted those out properly.

Thanks,

jon


Re: [PATCH] docs: kernel-parameters.txt: Fix whitespace

2018-04-16 Thread Jonathan Corbet
On Mon, 16 Apr 2018 17:45:01 +0200
Thymo van Beers  wrote:

> Some lines used spaces instead of tabs at line start.
> This can cause mangled lines in editors due to inconsistency.
> 
> Replace spaces for tabs where appropriate.

Seems like a fine idea.  The patch doesn't apply, though; can you please
make a version against current docs-next?  (Or against 4.17-rc1 will work
too).

Also...

>   domain
> -   Isolate from the general SMP balancing and scheduling
> -   algorithms. Note that performing domain isolation 
> this way
> -   is irreversible: it's not possible to bring back a 
> CPU to
> -   the domains once isolated through isolcpus. It's 
> strongly
> -   advised to use cpusets instead to disable scheduler 
> load
> -   balancing through the "cpuset.sched_load_balance" 
> file.
> -   It offers a much more flexible interface where CPUs 
> can
> -   move in and out of an isolated set anytime.
> -
> -   You can move a process onto or off an "isolated" CPU 
> via
> -   the CPU affinity syscalls or cpuset.
> -begins at 0 and the maximum value is
> -   "number of CPUs in system - 1".
> + Isolate from the general SMP balancing and 
> scheduling
> + algorithms. Note that performing domain 
> isolation this way
> + is irreversible: it's not possible to bring 
> back a CPU to
> + the domains once isolated through isolcpus. 
> It's strongly
> + advised to use cpusets instead to disable 
> scheduler load
> + balancing through the 
> "cpuset.sched_load_balance" file.
> + It offers a much more flexible interface where 
> CPUs can
> + move in and out of an isolated set anytime.
> +
> + You can move a process onto or off an "isolated" CPU via
> + the CPU affinity syscalls or cpuset.
> +  begins at 0 and the maximum value is
> + "number of CPUs in system - 1".

This would appear to have changed the indentation of some of the text?

Thanks,

jon


Re: [PATCH] Documentation/process: updates to the PGP guide

2018-04-16 Thread Jonathan Corbet
On Thu, 12 Apr 2018 16:44:10 -0400
Konstantin Ryabitsev  wrote:

> Small tweaks to the Maintainer PGP guide:
> 
>  - Use --quick-addkey command that is compatible between GnuPG-2.2 and
>GnuPG-2.1 (which many people still have)
>  - Add a note about the Nitrokey program
>  - Warn that some devices can't change the passphrase before there are
>keys on the card (specifically, Nitrokeys)
>  - Link to the GnuPG wiki page about gpg-agent forwarding over ssh
>  - Tell git to use gpgv2 instead of legacy gpgv when verifying signed
>tags or commits

Applied, thanks.

jon


Re: Linux 4.17-rc1

2018-04-16 Thread Jonathan Corbet
On Sun, 15 Apr 2018 18:55:38 -0700
Linus Torvalds  wrote:

> End result: we actually removed more lines than we added:
> 
>  13538 files changed, 627723 insertions(+), 818855 deletions(-)
> 
> which is probably a first. Ever. In the history of the universe. Or at
> least kernel releases.

For the curious...that's not quite the case.  We shrunk a bit for 2.6.36,
due to the removal of all those defconfig files.  3.17 was also slightly
smaller than 3.16 - removal of POWER3 and a whole bunch of staging stuff.
So...third time's the charm!

Of course, one could look at the numbers involved and conclude that a
release with more lines removed than added is a harbinger of a dot-zero
release in the near future :)

jon


Re: [PATCH 00/32] docs/vm: convert to ReST format

2018-04-13 Thread Jonathan Corbet
Sorry for the silence, I'm pedaling as fast as I can, honest...

On Sun, 1 Apr 2018 09:38:58 +0300
Mike Rapoport  wrote:

> My thinking was to start with mechanical RST conversion and then to start
> working on the contents and ordering of the documentation. Some of the
> existing files, e.g. ksm.txt, can be moved as is into the appropriate
> places, others, like transhuge.txt should be at least split into admin/user
> and developer guides.
> 
> Another problem with many of the existing mm docs is that they are rather
> developer notes and it wouldn't be really straight forward to assign them
> to a particular topic.

All this sounds good.

> I believe that keeping the mm docs together will give better visibility of
> what (little) mm documentation we have and will make the updates easier.
> The documents that fit well into a certain topic could be linked there. For
> instance:

...but this sounds like just the opposite...?  

I've had this conversation with folks in a number of subsystems.
Everybody wants to keep their documentation together in one place - it's
easier for the developers after all.  But for the readers I think it's
objectively worse.  It perpetuates the mess that Documentation/ is, and
forces readers to go digging through all kinds of inappropriate material
in the hope of finding something that tells them what they need to know.

So I would *really* like to split the documentation by audience, as has
been done for a number of other kernel subsystems (and eventually all, I
hope).

I can go ahead and apply the RST conversion, that seems like a step in
the right direction regardless.  But I sure hope we don't really have to
keep it as an unorganized jumble of stuff...

Thanks,

jon


Re: [PATCH] Fixed typo in onewire generic doc

2018-04-09 Thread Jonathan Corbet
On Mon, 09 Apr 2018 02:56:49 +0300
Evgeniy Polyakov  wrote:

> Hi everyone
> 
> I'm really sorry for that long delay.
> 
> Was this patch accepted or should I push it upstream?
> 
> 20.12.2017, 22:09, "Gergo Huszty" :
> > Onewire devices has 6 byte long unique serial numbers, 1 byte family
> > code and 1 byte CRC. Linux sysfs presents the device folder in the
> > form of familyID-deviceID, so CRC is not shown. The consequence is
> > that the device serial number is always a 12 long hex-string, but
> > doc says 13 in one place. This is corrected by this change.
> > Reference: https://en.wikipedia.org/wiki/1-Wire

Commit d6f44b3bd870ff5946fcd4293b4c07029d8d93c9, merged for 4.16.

jon


[PULL] Documentation for 4.17

2018-04-02 Thread Jonathan Corbet
The following changes since commit
7928b2cbe55b2a410a0f5c1f154610059c57b1b2:

  Linux 4.16-rc1 (2018-02-11 15:04:29 -0800)

are available in the Git repository at:

  git://git.lwn.net/linux.git tags/docs-4.17

for you to fetch changes up to 86afad7d87f535ebb1a0e978bc32a8c58ac99268:

  Documentation/process: update FUSE project website (2018-03-29 15:49:18 -0600)


There's been a fair amount of activity in Documentation/ this time around:

 - Lots of work aligning Documentation/ABI with reality, done by Aishwarya
   Pant.

 - The trace documentation has been converted to RST by Changbin Du

 - I thrashed up kernel-doc to deal with a parsing issue and to try to make
   the code more readable.  It's still a 20+-year-old Perl hack, though.

 - Lots of other updates, typo fixes, and more.

Expect some annoying merge conflicts with ftrace - changes in
Documentation/trace were made independently of the RST conversion.
Probably the conversion should have gone through that tree as well, in
retrospect.  The resolution in linux-next seems good.

Aaro Koskinen (1):
  documentation: add my name to kernel driver statement

Aishwarya Pant (13):
  Documentation/ABI: clean up sysfs-class-pktcdvd
  Documentation/ABI: add sysfs interface for s6e63m0 lcd driver
  aoe: document sysfs interface
  Documentation/ABI: update infiniband sysfs interfaces
  block/loop: add documentation for sysfs interface
  backlight: lm3639: document sysfs attributes
  backlight: adp5520: document sysfs attributes
  backlight: adp8860: document sysfs attributes
  Documentation: rapidio: move sysfs interface to ABI
  block: rbd: update sysfs interface
  acpi: nfit: document sysfs interface
  char/bsr: add sysfs interface documentation
  Input: trackpoint: document sysfs interface

Andy Shevchenko (3):
  dmaengine: Add note to dmatest documentation about supported channels
  dmaengine: Make dmatest.rst indeed reST compatible
  dmaengine: Fix spelling for parenthesis in dmatest documentation

Changbin Du (17):
  Documentation: add Linux tracing to Sphinx TOC tree
  trace doc: convert trace/ftrace-design.txt to rst format
  trace doc: add ftrace-uses.rst to doc tree
  trace doc: convert trace/tracepoint-analysis.txt to rst format
  trace doc: convert trace/ftrace.txt to rst format
  trace doc: convert trace/kprobetrace.txt to rst format
  trace doc: convert trace/uprobetracer.txt to rst format
  trace doc: convert trace/tracepoints.txt to rst format
  trace doc: convert trace/events.txt to rst format
  trace doc: convert trace/events-kmem.txt to rst format
  trace doc: convert trace/events-power.txt to rst format
  trace doc: convert trace/events-nmi.txt to rst format
  trace doc: convert trace/events-msr.txt to rst format
  trace doc: convert trace/mmiotrace.txt to rst format
  trace doc: convert trace/hwlat_detector.txt to rst fromat
  trace doc: convert trace/intel_th.txt to rst format
  trace doc: convert trace/stm.txt to rst format

Dave Hansen (1):
  docs: clarify security-bugs disclosure policy

Dominik Brodowski (1):
  Documentation/process: Co-developed-by instead of Co-Developed-by

Eric Engestrom (1):
  Documentation/sparse: fix typo

Gary R Hook (1):
  Documentation/CodingStyle: Add an example for braces

Joel Stanley (1):
  Documentation: Mention why %p prints ptrval

Jonathan Corbet (12):
  docs: kernel-doc: Get rid of xml_escape() and friends
  docs: kernel-doc: Rename and split STATE_FIELD
  docs: kernel-doc: Move STATE_NORMAL processing into its own function
  docs: kernel-doc: Move STATE_NAME processing into its own function
  docs: kernel-doc: Move STATE_BODY processing to a separate function
  docs: kernel-doc: Move STATE_PROTO processing into its own function
  docs: kernel-doc: Finish moving STATE_* code out of process_file()
  docs: kernel-doc: Don't mangle literal code blocks in comments
  docs: Add an SPDX header to kernel-doc
  Merge branch 'kerneldoc2' into docs-next
  docs: ftrace: fix a few formatting issues
  Docs: Added a pointer to the formatted docs to README

Jonathan Neuschäfer (2):
  Documentation/process/howto: Remove outdated info about bugzilla mailing 
lists
  admin-guide: Fix list formatting in tained-kernels.html

Martin Kepplinger (4):
  README: Improve documentation descriptions
  Documentation: admin-guide: add kvmconfig, xenconfig and tinyconfig 
commands
  Documentation: magic-numbers: Fix typo
  Documentation/process: update FUSE project website

Masanari Iida (2):
  linux-next: SLIMbus: doc: Fix a warning "Title underline too short"
  xfs: Change URL for the project in xfs.txt

Matthew Wilcox (7):
  Add documentation for Conte

Re: [PATCH] syscalls: define and explain goal to not call syscalls in the kernel

2018-03-30 Thread Jonathan Corbet
On Sun, 25 Mar 2018 18:25:27 +0200
Dominik Brodowski  wrote:

> As there have been multiple inquiries on the rationale of my patchsets
> removing in-kernel calls to sys_xyzzy(), here is an updated patch 01/NN
> which I will push upstream for v4.17-rc1. I will also include a reference
> to this mail (and therefore to the explanation below) in all related
> patches of the series. Any improvements, hints, suggestions, spelling
> fixes, and/or objections?

I have no objections to the text, but I do wonder about the placement.
The "adding syscalls" document isn't about *invoking* them; I suspect that
few people will see it there.  The coding-style document isn't quite right
either, but I wonder if it might not be a better place in the short term?

What we may really need is an "assorted rules" document that sits near
coding style; we can put stuff like this text, "volatile considered
harmful", and so on there.

Thanks,

jon


Re: [PATCH] Documentation/process: update FUSE project website

2018-03-29 Thread Jonathan Corbet
On Tue, 27 Mar 2018 14:59:50 +0200
Martin Kepplinger  wrote:

> According to the old project site, https://sourceforge.net/projects/fuse/
> the project has moved to https://github.com/libfuse/ so we update the
> link to point to the latest libfuse release.

Applied, thanks.

jon


Re: [PATCH 00/32] docs/vm: convert to ReST format

2018-03-29 Thread Jonathan Corbet
On Wed, 21 Mar 2018 21:22:16 +0200
Mike Rapoport  wrote:

> These patches convert files in Documentation/vm to ReST format, add an
> initial index and link it to the top level documentation.
> 
> There are no contents changes in the documentation, except few spelling
> fixes. The relatively large diffstat stems from the indentation and
> paragraph wrapping changes.
> 
> I've tried to keep the formatting as consistent as possible, but I could
> miss some places that needed markup and add some markup where it was not
> necessary.

So I've been pondering on these for a bit.  It looks like a reasonable and
straightforward RST conversion, no real complaints there.  But I do have a
couple of concerns...

One is that, as we move documentation into RST, I'm really trying to
organize it a bit so that it is better tuned to the various audiences we
have.  For example, ksm.txt is going to be of interest to sysadmin types,
who might want to tune it.  mmu_notifier.txt is of interest to ...
somebody, but probably nobody who is thinking in user space.  And so on.

So I would really like to see this material split up and put into the
appropriate places in the RST hierarchy - admin-guide for administrative
stuff, core-api for kernel development topics, etc.  That, of course,
could be done separately from the RST conversion, but I suspect I know
what will (or will not) happen if we agree to defer that for now :)

The other is the inevitable merge conflicts that changing that many doc
files will create.  Sending the patches through Andrew could minimize
that, I guess, or at least make it his problem.  Alternatively, we could
try to do it as an end-of-merge-window sort of thing.  I can try to manage
that, but an ack or two from the mm crowd would be nice to have.

Thanks,

jon


Re: [RFC PATCH v21 0/6] mm: security: ro protection for dynamic data

2018-03-29 Thread Jonathan Corbet
On Fri, 30 Mar 2018 00:25:22 +0400
Igor Stoppa <igor.sto...@gmail.com> wrote:

> On 27/03/18 20:55, Jonathan Corbet wrote:
> > On Tue, 27 Mar 2018 18:37:36 +0300
> > Igor Stoppa <igor.sto...@huawei.com> wrote:
> >   
> >> This patch-set introduces the possibility of protecting memory that has
> >> been allocated dynamically.  
> > 
> > One thing that jumps out at me as I look at the patch set is: you do not
> > include any users of this functionality.  Where do you expect this
> > allocator to be used?  Actually seeing the API in action would be a useful
> > addition, I think.  
> 
> Yes, this is very true.
> Initially I had in mind to use LSM hooks as easy example, but sadly they 
> seem to be in an almost constant flux.
> 
> My real use case is to secure both those and the SELinux policy DB.
> I have said this few times, but it didn't seem to be worth mentioning in 
> the cover letter.

In general, it is quite hard to merge a new API without users to go along
with it.  Among other things, that's how reviewers can see how well the
API works in real-world use.  I am certainly not the one who will make the
decision on whether this goes in, but I suspect that whoever *does* make
that decision would prefer to see some users.

Thanks,

jon


Re: [RFC PATCH ghak32 V2 01/13] audit: add container id

2018-03-29 Thread Jonathan Corbet
On Thu, 29 Mar 2018 05:01:32 -0400
Richard Guy Briggs  wrote:

> > A little detail, but still...  
> 
> I am understanding that you would prefer more context (as opposed to
> operational detail) in the description, laying out the use case for this
> patch(set)?

No, sorry, "a little detail" was referring to my comment.  The use case,
I believe, has been well described.

Thanks,

jon


Re: [RFC PATCH ghak32 V2 01/13] audit: add container id

2018-03-28 Thread Jonathan Corbet
On Fri, 16 Mar 2018 05:00:28 -0400
Richard Guy Briggs  wrote:

> Implement the proc fs write to set the audit container ID of a process,
> emitting an AUDIT_CONTAINER record to document the event.

A little detail, but still...

> +static int audit_set_containerid_perm(struct task_struct *task, u64 
> containerid)
> +{
> + struct task_struct *parent;
> + u64 pcontainerid, ccontainerid;
> +
> + /* Don't allow to set our own containerid */
> + if (current == task)
> + return -EPERM;
> + /* Don't allow the containerid to be unset */
> + if (!cid_valid(containerid))
> + return -EINVAL;

I went looking for cid_valid(), but it turns out you don't add it until
patch 5.  That, I expect, will not be good for bisectability (or patch
review).

Thanks,

jon


Re: [RFC PATCH v21 0/6] mm: security: ro protection for dynamic data

2018-03-27 Thread Jonathan Corbet
On Tue, 27 Mar 2018 18:37:36 +0300
Igor Stoppa  wrote:

> This patch-set introduces the possibility of protecting memory that has
> been allocated dynamically.

One thing that jumps out at me as I look at the patch set is: you do not
include any users of this functionality.  Where do you expect this
allocator to be used?  Actually seeing the API in action would be a useful
addition, I think.

Thanks,

jon


Re: [PATCH v2] Documentation/CodingStyle: Add an example for braces

2018-03-26 Thread Jonathan Corbet
On Mon, 26 Mar 2018 11:28:03 -0500
Gary R Hook  wrote:

> Submitting a v3 because the example could better illuminate the options 
> by using loop construct inside of an if, addressing Jani's point but 
> without opening the door to later criticism.
> 
> I also like the verbage in v2/3 better, but I'll let Jonathan make the call.

As I told you, I was applying the first version; I did that last week.

> BTW which tree should these be developed against? I used torvalds, but 
> I'm not entirely sure that was the proper one?

The MAINTAINERS file will (almost) always answer that question for
you:

T:  git git://git.lwn.net/linux.git docs-next

For a patch like this it doesn't matter, since there's is no other work on
the file to conflict with.

THanks,

jon


Re: [PATCH] Documentation: magic-numbers: Fix typo

2018-03-26 Thread Jonathan Corbet
On Fri, 23 Mar 2018 08:32:31 +0100
Martin Kepplinger  wrote:

> This fixes a little then / them confusion.
> 
> Signed-off-by: Martin Kepplinger 
> ---
>  Documentation/process/magic-number.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/process/magic-number.rst 
> b/Documentation/process/magic-number.rst
> index c74199f60c6c..00cecf1fcba9 100644
> --- a/Documentation/process/magic-number.rst
> +++ b/Documentation/process/magic-number.rst
> @@ -14,7 +14,7 @@ passing pointers to structures via a void * pointer.  The 
> tty code,
>  for example, does this frequently to pass driver-specific and line
>  discipline-specific structures back and forth.
>  
> -The way to use magic numbers is to declare then at the beginning of
> +The way to use magic numbers is to declare them at the beginning of
>  the structure, like so::
>  
>   struct tty_ldisc {

Applied, thanks.

jon


Re: [PATCH] Documentation: admin-guide: add kvmconfig, xenconfig and tinyconfig commands

2018-03-26 Thread Jonathan Corbet
On Thu, 22 Mar 2018 13:06:56 +0100
Martin Kepplinger  wrote:

> Add kvmconfig, xenconfig and tinyconfig to the list of alternative
> configuration commands. Descriptions are directly taken from the Makefile.

Applied to the docs tree, thanks.

jon


Re: [PATCH] Input: alps - Update documentation for trackstick v3 format

2018-03-26 Thread Jonathan Corbet
On Wed, 21 Mar 2018 21:03:36 +0100
Pali Rohár  wrote:

> Bits for M, R and L buttons are already processed in alps. Other newly
> documented bits not yet.
> 
> Signed-off-by: Pali Rohár 
> ---
> This is based on information which Masaki Ota provided to us.

In the absence of screams of agony I'll assume that the change is
correct.  Applied to the docs tree, thanks.

jon


Re: [PATCH] Documentation: Mention why %p prints ptrval

2018-03-23 Thread Jonathan Corbet
On Thu, 22 Mar 2018 15:53:36 +1030
Joel Stanley  wrote:

> When debugging recent kernels, people will see '(ptrval)' but there
> isn't much information as to what that means. Briefly describe why it's
> there.

Applied, thanks.

jon


Re: [PATCH v2 0/2] COPYING: create a new file with points to the Kernel license files

2018-03-23 Thread Jonathan Corbet
On Fri, 23 Mar 2018 06:51:04 -0300
Mauro Carvalho Chehab  wrote:

> The contents of COPYING file is now duplicated at two other
> files under LICENSE:
>   LICENSES/preferred/GPL-2.0
>   LICENSES/exceptions/Linux-syscall-note
> 
> Also, a new file was added, with describes how SPDX should work at
> the Kernel source files:
>   Documentation/process/license-rules.rst
> 
> Instead fo having it copying the contents of two files, and not
> even mentioning the third one, replace it by a file whose content
> points to the other tree files, preserving the Kernel's license.
> 
> Adjust license-rules.rst accordingly.

It looks like we're about there with these, so I went ahead and applied
them.

Thanks,

jon


Re: [PATCH] Input: trackpoint: document sysfs interface

2018-03-21 Thread Jonathan Corbet
On Fri, 2 Mar 2018 23:00:19 +0530
Aishwarya Pant  wrote:

> Descriptions have been collected from git commit logs, code commits and
> the TrackPoint System Version 4.0 Engineering Specification.

Applied to the docs tree, thanks.

jon


Re: [PATCH] xfs: Change URL for the project in xfs.txt

2018-03-21 Thread Jonathan Corbet
On Fri,  2 Mar 2018 22:30:13 +0900
Masanari Iida  wrote:

> The oss.sgi.com doesn't exist any more.
> Change it to current project URL, https://xfs.wiki.kernel.org/

Applied to the docs tree, thanks.

jon


Re: [PATCH] HID: ntrig: document sysfs interface

2018-03-21 Thread Jonathan Corbet
On Wed, 21 Mar 2018 09:28:05 -0600
Jonathan Corbet <cor...@lwn.net> wrote:

> > Add sysfs documentation for N-Trig touchscreens under Documentation/ABI.
> > Descriptions have been collected from code comments.  
> 
> Applied to the docs tree, thanks.

Oops, I thought I'd checked to see whether Jiri had picked these up, but I
evidently haven't had enough coffee yet.  Since they're taken care of,
I'll unapply them; sorry for the noise.

jon


  1   2   3   4   5   6   7   8   9   10   >