Re: git pull

[Tobin C. Harding]

Added Linus to To: header.

On Tue, Nov 14, 2017 at 12:05:00PM +0100, Greg Kroah-Hartman wrote:
> Adding lkml and linux-doc mailing lists...
> 
> On Tue, Nov 14, 2017 at 10:11:55AM +1100, Tobin C. Harding wrote:
> > Hi Greg,
> > 
> > This is totally asking a favour, feel free to ignore. How do you format
> > your [GIT PULL] emails to Linus? Do you create a tag and then run a git
> > command to get the email?
> > 
> > I tried to do it manually and failed pretty hard (as you no doubt will
> > notice on LKML).
> 
> Well, I think you got it right the third time, so nice job :)
> 
> Anyway, this actually came up at the kernel summit / maintainer meeting
> a few weeks ago, in that "how do I make a good pull request to Linus" is
> something we need to document.
> 
> Here's what I do, and it seems to work well, so maybe we should turn it
> into the start of the documentation for how to do it.
> 
> ---
> 
> To start with, put your changes on a branch, hopefully one named in a
> semi-useful way (I use 'char-misc-next' for my char/misc driver patches
> to be merged into linux-next).  That is the branch you wish to tag and
> have Linus pull from.
> 
> Name the tag with something useful that you can understand if you run
> across it in a few weeks, and something that will be "unique".
> Continuing the example of my char-misc tree, for the patches to be sent
> to Linus for the 4.15-rc1 merge window, I would name the tag
> 'char-misc-4.15-rc1':
>   git tag -u KEY_ID -s char-misc-4.15-rc1 char-misc-next
> 
> that will create a signed tag called 'char-misc-4.15-rc1' based on the
> last commit in the char-misc-next branch, and sign it with my gpg key
> KEY_ID (replace KEY_ID with your own gpg key id.)
> 
> When you run the above command, git will drop you into an editor and ask
> you to describe the tag.  In this case, you are describing a pull
> request, so outline what is contained here, why it should be merged, and
> what, if any, testing has happened to it.  All of this information will
> end up in the tag itself, and then in the merge commit that Linus makes,
> so write it up well, as it will be in the kernel tree for forever.
> 
> An example pull request of mine might look like:
>   Char/Misc patches for 4.15-rc1
> 
>   Here is the big char/misc patch set for the 4.15-rc1 merge
>   window.  Contained in here is the normal set of new functions
>   added to all of these crazy drivers, as well as the following
>   brand new subsystems:
>   - time_travel_controller: Finally a set of drivers for
> the latest time travel bus architecture that provides
> i/o to the CPU before it asked for it, allowing
> uninterrupted processing
>   - relativity_shifters: due to the affect that the
> time_travel_controllers have on the overall system,
> there was a need for a new set of relativity shifter
> drivers to accommodate the newly formed black holes
> that would threaten to suck CPUs into them.  This
> subsystem handles this in a way to successfully
> neutralize the problems.  There is a Kconfig option to
> force these to be enabled when needed, so problems
> should not occur.
> 
>   All of these patches have been successfully tested in the latest
>   linux-next releases, and the original problems that it found
>   have all been resolved (apologies to anyone living near Canberra
>   for the lack of the Kconfig options in the earlier versions of
>   the linux-next tree creations.)
> 
>   Signed-off-by: Your-name-here 
> 
> 
> The tag message format is just like a git commit id.  One line at the
> top for a "summary subject" and be sure to sign-off at the bottom.
> 
> Now that you have a local signed tag, you need to push it up to where it
> can be retrieved by others:
>   git push origin char-misc-4.15-rc1
> pushes the char-misc-4.15-rc1 tag to where the 'origin' repo is located.
> 
> The last thing to do is create the pull request message.  Git handily
> will do this for you with the 'git request-pull' command, but it needs a
> bit of help determining what you want to pull, and what to base the pull
> against (to show the correct changes to be pulled and the diffstat.)
> 
> I use the following command to generate a pull request:
>   git request-pull master 
> git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/char-misc.git/ 
> char-misc-4.15-rc1
> 
> This is asking git to compare the d

Re: git pull

[Tobin C. Harding]

On Tue, Nov 14, 2017 at 12:05:00PM +0100, Greg Kroah-Hartman wrote:
> Adding lkml and linux-doc mailing lists...
> 
> On Tue, Nov 14, 2017 at 10:11:55AM +1100, Tobin C. Harding wrote:
> > Hi Greg,
> > 
> > This is totally asking a favour, feel free to ignore. How do you format
> > your [GIT PULL] emails to Linus? Do you create a tag and then run a git
> > command to get the email?
> > 
> > I tried to do it manually and failed pretty hard (as you no doubt will
> > notice on LKML).
> 
> Well, I think you got it right the third time, so nice job :)

Lucky. Three strikes and your out isn't it?

> Anyway, this actually came up at the kernel summit / maintainer meeting
> a few weeks ago, in that "how do I make a good pull request to Linus" is
> something we need to document.
> 
> Here's what I do, and it seems to work well, so maybe we should turn it
> into the start of the documentation for how to do it.

Patch to come.

> ---
> 
> To start with, put your changes on a branch, hopefully one named in a
> semi-useful way (I use 'char-misc-next' for my char/misc driver patches
> to be merged into linux-next).  That is the branch you wish to tag and
> have Linus pull from.
> 
> Name the tag with something useful that you can understand if you run
> across it in a few weeks, and something that will be "unique".
> Continuing the example of my char-misc tree, for the patches to be sent
> to Linus for the 4.15-rc1 merge window, I would name the tag
> 'char-misc-4.15-rc1':
>   git tag -u KEY_ID -s char-misc-4.15-rc1 char-misc-next
> 
> that will create a signed tag called 'char-misc-4.15-rc1' based on the
> last commit in the char-misc-next branch, and sign it with my gpg key
> KEY_ID (replace KEY_ID with your own gpg key id.)
> 
> When you run the above command, git will drop you into an editor and ask
> you to describe the tag.  In this case, you are describing a pull
> request, so outline what is contained here, why it should be merged, and
> what, if any, testing has happened to it.  All of this information will
> end up in the tag itself, and then in the merge commit that Linus makes,
> so write it up well, as it will be in the kernel tree for forever.
> 
> An example pull request of mine might look like:
>   Char/Misc patches for 4.15-rc1
> 
>   Here is the big char/misc patch set for the 4.15-rc1 merge
>   window.  Contained in here is the normal set of new functions
>   added to all of these crazy drivers, as well as the following
>   brand new subsystems:
>   - time_travel_controller: Finally a set of drivers for
> the latest time travel bus architecture that provides
> i/o to the CPU before it asked for it, allowing
> uninterrupted processing
>   - relativity_shifters: due to the affect that the
> time_travel_controllers have on the overall system,
> there was a need for a new set of relativity shifter
> drivers to accommodate the newly formed black holes
> that would threaten to suck CPUs into them.  This
> subsystem handles this in a way to successfully
> neutralize the problems.  There is a Kconfig option to
> force these to be enabled when needed, so problems
> should not occur.
> 
>   All of these patches have been successfully tested in the latest
>   linux-next releases, and the original problems that it found
>   have all been resolved (apologies to anyone living near Canberra
>   for the lack of the Kconfig options in the earlier versions of
>   the linux-next tree creations.)
> 
>   Signed-off-by: Your-name-here 
> 
> 
> The tag message format is just like a git commit id.  One line at the
> top for a "summary subject" and be sure to sign-off at the bottom.
> 
> Now that you have a local signed tag, you need to push it up to where it
> can be retrieved by others:
>   git push origin char-misc-4.15-rc1
> pushes the char-misc-4.15-rc1 tag to where the 'origin' repo is located.
> 
> The last thing to do is create the pull request message.  Git handily
> will do this for you with the 'git request-pull' command, but it needs a
> bit of help determining what you want to pull, and what to base the pull
> against (to show the correct changes to be pulled and the diffstat.)
> 
> I use the following command to generate a pull request:
>   git request-pull master 
> git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/char-misc.git/ 
> char-misc-4.15-rc1
> 
> This

[PATCH] docs: add submitting-pull-requests.rst

[Tobin C. Harding]

There is currently no documentation on how to create a pull request for
Linus.

Anyway, this actually came up at the kernel summit / maintainer
meeting a few weeks ago, in that "how do I make a good pull request
to Linus" is something we need to document.

Here's what I do, and it seems to work well, so maybe we should turn
it into the start of the documentation for how to do it.

Create document from email thread on LKML (referenced in document).

Signed-off-by: Tobin C. Harding 
---

Is it rude to send this during the merge window? Can resend after it closes if
it makes life easier.

thanks,
Tobin.

 Documentation/process/submitting-pull-requests.rst | 171 +
 1 file changed, 171 insertions(+)
 create mode 100644 Documentation/process/submitting-pull-requests.rst

diff --git a/Documentation/process/submitting-pull-requests.rst 
b/Documentation/process/submitting-pull-requests.rst
new file mode 100644
index ..9528aead4809
--- /dev/null
+++ b/Documentation/process/submitting-pull-requests.rst
@@ -0,0 +1,171 @@
+Submitting Pull Requests to Linus: a guide for maintainers
+==
+
+This document is aimed at kernel maintainers.  It describes a method for 
creating
+a pull request to be sent to Linus.
+
+Configure Git
+-
+
+Since you _usually_ would use the same key for the same project, just set it
+once with
+
+   git config user.signingkey "keyname"
+
+and if you use the same key for everything, just add "--global".
+
+Or just edit your .git/config or ~/.gitconfig file by hand, it's designed to be
+human-readable and writable, and not some garbage like XML:
+
+   [torvalds@i7 ~]$ head -4 .gitconfig
+   [user]
+   name = Linus Torvalds
+   email = torva...@linux-foundation.org
+   signingkey = torva...@linux-foundation.org
+
+You may need to tell git to use gpg2
+
+   [gpg]
+   program = /path/to/gpg2
+
+You may also like to tell gpg which tty to use (add to shell rc file)
+
+   export GPG_TTY=$(tty)
+
+
+Branch, Tag, Push
+-
+
+Next, put your changes on a branch, hopefully one named in a semi-useful way (I
+use 'char-misc-next' for my char/misc driver patches to be merged into
+linux-next).  That is the branch you wish to tag and have Linus pull from.
+
+Name the tag with something useful that you can understand if you run across it
+in a few weeks, and something that will be "unique".  Continuing the example of
+the char-misc tree, for the patches to be sent to Linus for the 4.15-rc1 merge
+window, I would name the tag 'char-misc-4.15-rc1':
+
+   git tag -s char-misc-4.15-rc1 char-misc-next
+
+that will create a signed tag called 'char-misc-4.15-rc1' based on the last
+commit in the char-misc-next branch, and sign it with your gpg key (configured
+above).
+
+When you run the above command, git will drop you into an editor and ask you to
+describe the tag.  In this case, you are describing a pull request, so outline
+what is contained here, why it should be merged, and what, if any, testing has
+happened to it.  All of this information will end up in the tag itself, and 
then
+in the merge commit that Linus makes, so write it up well, as it will be in the
+kernel tree for forever.
+
+   Anyway, at least to me, the important part is the *message*. I want to
+   understand what I'm pulling, and why I should pull it. I also want to
+   use that message as the message for the merge, so it should not just
+   make sense to me, but make sense as a historical record too.
+
+   Note that if there is something odd about the pull request, that
+   should very much be in the explanation. If you're touching files that
+   you don't maintain, explain _why_. I will see it in the diffstat
+   anyway, and if you didn't mention it, I'll just be extra suspicious.
+   And when you send me new stuff after the merge window (or even
+   bug-fixes, but ones that look scary), explain not just what they do
+   and why they do it, but explain the _timing_. What happened that this
+   didn't go through the merge window..
+
+   I will take both what you write in the email pull request _and_ in the
+   signed tag, so depending on your workflow, you can either describe
+   your work in the signed tag (which will also automatically make it
+   into the pull request email), or you can make the signed tag just a
+   placeholder with nothing interesting in it, and describe the work
+   later when you actually send me the pull request.
+
+   And yes, I will edit the message. Partly because I tend to do just
+   trivial formatting (the whole indentation and quoting etc), but partly
+   because part of the message may make sense for me at pull time

Re: [PATCH] docs: add submitting-pull-requests.rst

[Tobin C. Harding]

On Tue, Nov 14, 2017 at 04:48:16PM -0700, Jonathan Corbet wrote:

Awesome comments Jon, I knew there would be more to writing docs than
first met the eye.

> On Wed, 15 Nov 2017 09:54:21 +1100
> "Tobin C. Harding"  wrote:
> 
> > There is currently no documentation on how to create a pull request for
> > Linus.
> > 
> > Anyway, this actually came up at the kernel summit / maintainer
> > meeting a few weeks ago, in that "how do I make a good pull request
> > to Linus" is something we need to document.
> > 
> > Here's what I do, and it seems to work well, so maybe we should turn
> > it into the start of the documentation for how to do it.
> > 
> > Create document from email thread on LKML (referenced in document).
> > 
> > Signed-off-by: Tobin C. Harding 
> > ---
> > 
> > Is it rude to send this during the merge window? Can resend after it closes 
> > if
> > it makes life easier.
> 
> I can handle patches during the merge window.  That said, while I welcome
> this effort and think it's a good start, there's a few things I'll
> quibble about:
> 
>  - Much of this was actually written by Greg, I believe, and some by Linus.
>That deserves credit in the changelog, if nowhere else.

Yeah, I struggled for ages with the tense, Greg's stuff is obviously
written as him. But I didn't want to paraphrase and present it as if I'd
written it. After your comments I'm still unsure of the _best_ way to
present this material with a good flow but still giving credit where
credit is due? I didn't seem right to add their names to the document
(thereby presenting myself as them). I did not think of the changelog -
I'll go that path for v2.

>  - Putting it in Documentation/process as RST is good.  But it should be
>added to index.rst and made part of the docs build.  I suspect you
>haven't run it through sphinx at all yet, right?  Some things are
>unlikely to format the way you think they might.

My bad, I knew I would botch some of the RST stuff, didn't think to run
it through sphinx (I tend to view kernel docs as the raw files ;)

> Finally, I see this as being the first installment in what, I hope, will
> someday be a nice "how to be a kernel maintainer" manual.  I wouldn't
> insist on it before taking a patch like this, but if you could see
> through to organizing it as a chapter in a bigger sub-book, that would be
> great.

Happy to do so. I'm no way qualified to produce much of the text but
perhaps can assist in getting things moving.

> Finally finally... Dan Williams [CC'd] has plans for doing some
> maintainer-level documentation.  He may have thoughts on how this fits
> into what he's scheming, and I'd suggest copying him on the next
> iteration.

Let's liaise on this Dan (if you want to).

> Finally finally finally...some specific comments on the text.  Some of
> them might be read to suggest a major expansion of the work you've done;
> please see that as me saying "that would be nice".  Doing all of this is
> not a precondition to getting this document added!

There is no rush to get merged, let's get it into shape first :)

> > +Submitting Pull Requests to Linus: a guide for maintainers
> > +==
> > +
> > +This document is aimed at kernel maintainers.  It describes a method for 
> > creating
> > +a pull request to be sent to Linus.
> 
> Limiting text widths to, say, 75 columns when possible is preferable.  Word
> has it some maintainers are still reading the docs on their adm3a
> terminals.

Got it. (idea for next doc 'column widths howto' - your canonical guide
to column widths (includes git brief, commit log, email, source code,
and docs).

I'm kidding. 75 it is.

> Most maintainers push directly to Linus, so that's an obvious best focus,
> but pull requests happen at other levels too.  One would hope that this
> information would be applicable at all levels, so it might be nice to
> describe it as such.

Oh, Greg had this, I stripped it out. Back in on next spin.

> > +Configure Git
> > +-
> 
> "Configure Git to use your private key"
> 
> We are, of course, missing the whole discussion on why one would want a
> keypair, how to create it, how to get it into the web of trust, etc.  All
> fodder for a separate chapter in our shiny new maintainer book :)  But it
> is worth saying at least that this is about making Git use your key so you
> can sign tags for pull requests.

Funny you should say that, I'm trying to get into the web of trust so
perhaps I can help wit

Re: [PATCH] docs: add submitting-pull-requests.rst

[Tobin C. Harding]

On Wed, Nov 15, 2017 at 04:09:32PM +0200, Jani Nikula wrote:
> On Wed, 15 Nov 2017, "Tobin C. Harding"  wrote:
> > On Tue, Nov 14, 2017 at 04:48:16PM -0700, Jonathan Corbet wrote:
> >
> > Awesome comments Jon, I knew there would be more to writing docs than
> > first met the eye.
> >
> >> On Wed, 15 Nov 2017 09:54:21 +1100
> >> "Tobin C. Harding"  wrote:
> >> 
> >> > There is currently no documentation on how to create a pull request for
> >> > Linus.
> >> > 
> >> > Anyway, this actually came up at the kernel summit / maintainer
> >> > meeting a few weeks ago, in that "how do I make a good pull request
> >> > to Linus" is something we need to document.
> >> > 
> >> > Here's what I do, and it seems to work well, so maybe we should turn
> >> > it into the start of the documentation for how to do it.
> >> > 
> >> > Create document from email thread on LKML (referenced in document).
> >> > 
> >> > Signed-off-by: Tobin C. Harding 
> >> > ---
> >> > 
> >> > Is it rude to send this during the merge window? Can resend after it 
> >> > closes if
> >> > it makes life easier.
> >> 
> >> I can handle patches during the merge window.  That said, while I welcome
> >> this effort and think it's a good start, there's a few things I'll
> >> quibble about:
> >> 
> >>  - Much of this was actually written by Greg, I believe, and some by Linus.
> >>That deserves credit in the changelog, if nowhere else.
> >
> > Yeah, I struggled for ages with the tense, Greg's stuff is obviously
> > written as him. But I didn't want to paraphrase and present it as if I'd
> > written it. After your comments I'm still unsure of the _best_ way to
> > present this material with a good flow but still giving credit where
> > credit is due? I didn't seem right to add their names to the document
> > (thereby presenting myself as them). I did not think of the changelog -
> > I'll go that path for v2.
> >
> >>  - Putting it in Documentation/process as RST is good.  But it should be
> >>added to index.rst and made part of the docs build.  I suspect you
> >>haven't run it through sphinx at all yet, right?  Some things are
> >>unlikely to format the way you think they might.
> >
> > My bad, I knew I would botch some of the RST stuff, didn't think to run
> > it through sphinx (I tend to view kernel docs as the raw files ;)
> >
> >> Finally, I see this as being the first installment in what, I hope, will
> >> someday be a nice "how to be a kernel maintainer" manual.  I wouldn't
> >> insist on it before taking a patch like this, but if you could see
> >> through to organizing it as a chapter in a bigger sub-book, that would be
> >> great.
> >
> > Happy to do so. I'm no way qualified to produce much of the text but
> > perhaps can assist in getting things moving.
> >
> >> Finally finally... Dan Williams [CC'd] has plans for doing some
> >> maintainer-level documentation.  He may have thoughts on how this fits
> >> into what he's scheming, and I'd suggest copying him on the next
> >> iteration.
> >
> > Let's liaise on this Dan (if you want to).
> >
> >> Finally finally finally...some specific comments on the text.  Some of
> >> them might be read to suggest a major expansion of the work you've done;
> >> please see that as me saying "that would be nice".  Doing all of this is
> >> not a precondition to getting this document added!
> >
> > There is no rush to get merged, let's get it into shape first :)
> >
> >> > +Submitting Pull Requests to Linus: a guide for maintainers
> >> > +==
> >> > +
> >> > +This document is aimed at kernel maintainers.  It describes a method 
> >> > for creating
> >> > +a pull request to be sent to Linus.
> >> 
> >> Limiting text widths to, say, 75 columns when possible is preferable.  Word
> >> has it some maintainers are still reading the docs on their adm3a
> >> terminals.
> >
> > Got it. (idea for next doc 'column widths howto' - your canonical guide
> > to column widths (includes git brief, commit log, email, source code,
> > and doc

[RFC] doc: add maintainer book

[Tobin C. Harding]

There is currently very little documentation in the kernel on maintainer
level tasks. In particular there are no documents on creating pull
requests to submit to Linus.

Quoting Greg Kroah-Hartman on LKML:

Anyway, this actually came up at the kernel summit / maintainer
meeting a few weeks ago, in that "how do I make a
good pull request to Linus" is something we need to document.

Here's what I do, and it seems to work well, so maybe we should turn
it into the start of the documentation for how to do it.

(quote references: kernel summit, Europe 2017)

Create a new kernel documentation book 'how to be a maintainer'
(suggested by Jonathan Corbet). Add chapters on 'configuring git' and
'creating a pull request'.

Most of the content was written by Linus Torvalds and Greg Kroah-Hartman
in discussion on LKML. This is stated at the start of one of the
chapters and the original email thread is referenced in
'pull-requests.rst'.

Signed-off-by: Tobin C. Harding 
---

Linus and Greg are CC'd because they are quoted heavily in the document.

Greg,

This is my second attempt at this but still it reads as if I am saying things
that actually you said. I feel this is in the spirit of your original message
but I would still like you to okay it please. Any suggestions (from anyone) on a
better way to word, or structure, the document most welcome.

thanks.


Dan,

Is this in line with your ideas for the maintainer documentation you have
planned? I am a total noob at writing docs, please don't be shy to say if there
is a better way.

thanks,
Tobin.

 Documentation/index.rst|   1 +
 Documentation/maintainer/conf.py   |  10 ++
 Documentation/maintainer/configure-git.rst |  34 ++
 Documentation/maintainer/index.rst |  10 ++
 Documentation/maintainer/pull-requests.rst | 178 +
 5 files changed, 233 insertions(+)
 create mode 100644 Documentation/maintainer/conf.py
 create mode 100644 Documentation/maintainer/configure-git.rst
 create mode 100644 Documentation/maintainer/index.rst
 create mode 100644 Documentation/maintainer/pull-requests.rst

diff --git a/Documentation/index.rst b/Documentation/index.rst
index cb7f1ba5b3b1..a4fb34dddcf3 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -52,6 +52,7 @@ merged much easier.
dev-tools/index
doc-guide/index
kernel-hacking/index
+   maintainer/index
 
 Kernel API documentation
 
diff --git a/Documentation/maintainer/conf.py b/Documentation/maintainer/conf.py
new file mode 100644
index ..81e9eb7a7884
--- /dev/null
+++ b/Documentation/maintainer/conf.py
@@ -0,0 +1,10 @@
+# -*- 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/maintainer/configure-git.rst 
b/Documentation/maintainer/configure-git.rst
new file mode 100644
index ..780d2c84
--- /dev/null
+++ b/Documentation/maintainer/configure-git.rst
@@ -0,0 +1,34 @@
+.. _configuregit:
+
+Configure Git
+=
+
+This chapter describes maintainer level git configuration.
+
+Tagged branches used in :ref:`Documentation/maintainer/pull-requests.rst
+` should be signed with the developers public GPG key. Signed
+tags can be created by passing the ``-u`` flag to ``git tag``. However,
+since you would *usually* use the same key for the same project, you can
+set it once with
+::
+
+   git config user.signingkey "keyname"
+
+Alternatively, edit your ``.git/config`` or ``~/.gitconfig`` file by hand:
+::
+
+   [user]
+   name = Jane Developer
+   email = j...@domain.org
+   signingkey = j...@domain.org
+
+You may need to tell ``git`` to use ``gpg2``
+::
+
+   [gpg]
+   program = /path/to/gpg2
+
+You may also like to tell ``gpg`` which ``tty`` to use (add to your shell rc 
file)
+::
+
+   export GPG_TTY=$(tty)
diff --git a/Documentation/maintainer/index.rst 
b/Documentation/maintainer/index.rst
new file mode 100644
index ..23dd28ec8762
--- /dev/null
+++ b/Documentation/maintainer/index.rst
@@ -0,0 +1,10 @@
+=
+How to Be a Kernel Maintainer
+=
+
+.. toctree::
+   :maxdepth: 2
+
+   configure-git
+   pull-requests
+
diff --git a/Documentation/maintainer/pull-requests.rst 
b/Documentation/maintainer/pull-requests.rst
new file mode 100644
index ..0ca9f9bfd679
--- /dev/null
+++ b/Documentation/maintainer/pull-requests.rst
@@ -0,0 +1,178 @@
+.. _pullrequests:
+
+Creating Pull Requests
+==
+
+This chapter describes how maintainers can

Are .txt -> .rst patches welcome

[Tobin C. Harding]

Hi,

What's the status of the move from .txt to .rst files within the
kernel?

The point of the question; are patches converting .txt files in
Documentation/ to .rst files welcome?

thanks,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC] doc: add maintainer book

[Tobin C. Harding]

On Fri, Nov 24, 2017 at 11:02:49AM -0800, Dan Williams wrote:
> On Tue, Nov 21, 2017 at 2:39 PM, Tobin C. Harding  wrote:
> > There is currently very little documentation in the kernel on maintainer
> > level tasks. In particular there are no documents on creating pull
> > requests to submit to Linus.
> >
> > Quoting Greg Kroah-Hartman on LKML:
> >
> > Anyway, this actually came up at the kernel summit / maintainer
> > meeting a few weeks ago, in that "how do I make a
> > good pull request to Linus" is something we need to document.
> >
> > Here's what I do, and it seems to work well, so maybe we should turn
> > it into the start of the documentation for how to do it.
> >
> > (quote references: kernel summit, Europe 2017)
> >
> > Create a new kernel documentation book 'how to be a maintainer'
> > (suggested by Jonathan Corbet). Add chapters on 'configuring git' and
> > 'creating a pull request'.
> >
> > Most of the content was written by Linus Torvalds and Greg Kroah-Hartman
> > in discussion on LKML. This is stated at the start of one of the
> > chapters and the original email thread is referenced in
> > 'pull-requests.rst'.
> >
> > Signed-off-by: Tobin C. Harding 
> > ---
> >
> > Linus and Greg are CC'd because they are quoted heavily in the document.
> >
> > Greg,
> >
> > This is my second attempt at this but still it reads as if I am saying 
> > things
> > that actually you said. I feel this is in the spirit of your original 
> > message
> > but I would still like you to okay it please. Any suggestions (from anyone) 
> > on a
> > better way to word, or structure, the document most welcome.
> >
> > thanks.
> >
> >
> > Dan,
> >
> > Is this in line with your ideas for the maintainer documentation you have
> > planned? I am a total noob at writing docs, please don't be shy to say if 
> > there
> > is a better way.
> 
> This is a good start that we can build on, I'll let others comment on
> the mechanical doc building details I want to focus on the content.
> The only change I would make at this point is to the index...
> 
> [..]
> > diff --git a/Documentation/maintainer/index.rst 
> > b/Documentation/maintainer/index.rst
> > new file mode 100644
> > index ..23dd28ec8762
> > --- /dev/null
> > +++ b/Documentation/maintainer/index.rst
> > @@ -0,0 +1,10 @@
> > +=
> > +How to Be a Kernel Maintainer
> > +=
> 
> Let's call this the "Kernel Maintainer Handbook". Unlike
> SubmittingPatches and CodingStyle, this won't be a list of rules and
> mandates but instead some common principles and practical advice that
> maintainers will find useful, especially new and casual maintainers.

Sounds good to me, I'll re-spin it with that change.

> > +
> > +.. toctree::
> > +   :maxdepth: 2
> > +
> > +   configure-git
> > +   pull-requests
> > +
> > diff --git a/Documentation/maintainer/pull-requests.rst 
> > b/Documentation/maintainer/pull-requests.rst
> > new file mode 100644
> > index ..0ca9f9bfd679
> > --- /dev/null
> > +++ b/Documentation/maintainer/pull-requests.rst
> > @@ -0,0 +1,178 @@
> > +.. _pullrequests:
> > +
> > +Creating Pull Requests
> > +==
> 
> It strikes me that the very next chapter we need to precede this one
> is how to age commits in -next and the art of avoiding rebasing.

I'd like to read this!

thanks,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2] doc: add maintainer book

[Tobin C. Harding]

There is currently very little documentation in the kernel on maintainer
level tasks. In particular there are no documents on creating pull
requests to submit to Linus.

Quoting Greg Kroah-Hartman on LKML:

Anyway, this actually came up at the kernel summit / maintainer
meeting a few weeks ago, in that "how do I make a
good pull request to Linus" is something we need to document.

Here's what I do, and it seems to work well, so maybe we should turn
it into the start of the documentation for how to do it.

(quote references: kernel summit, Europe 2017)

Create a new kernel documentation book 'how to be a maintainer'
(suggested by Jonathan Corbet). Add chapters on 'configuring git' and
'creating a pull request'.

Most of the content was written by Linus Torvalds and Greg Kroah-Hartman
in discussion on LKML. This is stated at the start of one of the
chapters and the original email thread is referenced in
'pull-requests.rst'.

Signed-off-by: Tobin C. Harding 
---

v2:
 - Change title of book, suggested by Dan Williams.

thanks,
Tobin.

 Documentation/index.rst|   1 +
 Documentation/maintainer/conf.py   |  10 ++
 Documentation/maintainer/configure-git.rst |  34 ++
 Documentation/maintainer/index.rst |  10 ++
 Documentation/maintainer/pull-requests.rst | 178 +
 5 files changed, 233 insertions(+)
 create mode 100644 Documentation/maintainer/conf.py
 create mode 100644 Documentation/maintainer/configure-git.rst
 create mode 100644 Documentation/maintainer/index.rst
 create mode 100644 Documentation/maintainer/pull-requests.rst

diff --git a/Documentation/index.rst b/Documentation/index.rst
index cb7f1ba5b3b1..a4fb34dddcf3 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -52,6 +52,7 @@ merged much easier.
dev-tools/index
doc-guide/index
kernel-hacking/index
+   maintainer/index
 
 Kernel API documentation
 
diff --git a/Documentation/maintainer/conf.py b/Documentation/maintainer/conf.py
new file mode 100644
index ..81e9eb7a7884
--- /dev/null
+++ b/Documentation/maintainer/conf.py
@@ -0,0 +1,10 @@
+# -*- 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/maintainer/configure-git.rst 
b/Documentation/maintainer/configure-git.rst
new file mode 100644
index ..780d2c84
--- /dev/null
+++ b/Documentation/maintainer/configure-git.rst
@@ -0,0 +1,34 @@
+.. _configuregit:
+
+Configure Git
+=
+
+This chapter describes maintainer level git configuration.
+
+Tagged branches used in :ref:`Documentation/maintainer/pull-requests.rst
+` should be signed with the developers public GPG key. Signed
+tags can be created by passing the ``-u`` flag to ``git tag``. However,
+since you would *usually* use the same key for the same project, you can
+set it once with
+::
+
+   git config user.signingkey "keyname"
+
+Alternatively, edit your ``.git/config`` or ``~/.gitconfig`` file by hand:
+::
+
+   [user]
+   name = Jane Developer
+   email = j...@domain.org
+   signingkey = j...@domain.org
+
+You may need to tell ``git`` to use ``gpg2``
+::
+
+   [gpg]
+   program = /path/to/gpg2
+
+You may also like to tell ``gpg`` which ``tty`` to use (add to your shell rc 
file)
+::
+
+   export GPG_TTY=$(tty)
diff --git a/Documentation/maintainer/index.rst 
b/Documentation/maintainer/index.rst
new file mode 100644
index ..fa84ac9cae39
--- /dev/null
+++ b/Documentation/maintainer/index.rst
@@ -0,0 +1,10 @@
+==
+Kernel Maintainer Handbook
+==
+
+.. toctree::
+   :maxdepth: 2
+
+   configure-git
+   pull-requests
+
diff --git a/Documentation/maintainer/pull-requests.rst 
b/Documentation/maintainer/pull-requests.rst
new file mode 100644
index ..0ca9f9bfd679
--- /dev/null
+++ b/Documentation/maintainer/pull-requests.rst
@@ -0,0 +1,178 @@
+.. _pullrequests:
+
+Creating Pull Requests
+==
+
+This chapter describes how maintainers can create and submit pull requests
+to other maintainers. This is useful for transferring changes from one
+maintainers tree to another maintainers tree.
+
+This document was written by Tobin C. Harding (who at that time, was not an
+experienced maintainer) primarily from comments made by Greg Kroah-Hartman
+and Linus Torvalds on LKML. Suggestions and fixes by Jonathan Corbet.
+Misrepresentation was unintentional but inevitable, please direct abuse to
+Tobin C. Harding .
+
+Original email thread::
+
+   http://lkml.kernel.o

Re: [PATCH v2] doc: add maintainer book

[Tobin C. Harding]

On Sat, Nov 25, 2017 at 08:56:23AM +0100, Greg Kroah-Hartman wrote:
> On Sat, Nov 25, 2017 at 08:44:19AM +1100, Tobin C. Harding wrote:
> > There is currently very little documentation in the kernel on maintainer
> > level tasks. In particular there are no documents on creating pull
> > requests to submit to Linus.
> > 
> > Quoting Greg Kroah-Hartman on LKML:
> > 
> > Anyway, this actually came up at the kernel summit / maintainer
> > meeting a few weeks ago, in that "how do I make a
> > good pull request to Linus" is something we need to document.
> > 
> > Here's what I do, and it seems to work well, so maybe we should turn
> > it into the start of the documentation for how to do it.
> > 
> > (quote references: kernel summit, Europe 2017)
> > 
> > Create a new kernel documentation book 'how to be a maintainer'
> > (suggested by Jonathan Corbet). Add chapters on 'configuring git' and
> > 'creating a pull request'.
> > 
> > Most of the content was written by Linus Torvalds and Greg Kroah-Hartman
> > in discussion on LKML. This is stated at the start of one of the
> > chapters and the original email thread is referenced in
> > 'pull-requests.rst'.
> > 
> > Signed-off-by: Tobin C. Harding 
> > ---
> 
> You dropped my reviewed-by :(

Oh, I didn't realize I was able to keep it between versions. I realize
this was a reasonably trivial change but in general how much change is
ok while keeping the reviewed-by? Who's call is it, the original
author, the reviewed-by dev or the maintainer?

So v3 with your reviewed-by in the commit log below the signed-off
tag. (ain't nothin like noise ;)

thanks,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2] doc: add maintainer book

[Tobin C. Harding]

On Mon, Nov 27, 2017 at 04:57:30PM -0200, Mauro Carvalho Chehab wrote:
> Em Sat, 25 Nov 2017 08:44:19 +1100
> "Tobin C. Harding"  escreveu:
> 
> > There is currently very little documentation in the kernel on maintainer
> > level tasks. In particular there are no documents on creating pull
> > requests to submit to Linus.
> > 
> > Quoting Greg Kroah-Hartman on LKML:
> > 
> > Anyway, this actually came up at the kernel summit / maintainer
> > meeting a few weeks ago, in that "how do I make a
> > good pull request to Linus" is something we need to document.
> > 
> > Here's what I do, and it seems to work well, so maybe we should turn
> > it into the start of the documentation for how to do it.
> > 
> > (quote references: kernel summit, Europe 2017)
> > 
> > Create a new kernel documentation book 'how to be a maintainer'
> > (suggested by Jonathan Corbet). Add chapters on 'configuring git' and
> > 'creating a pull request'.
> > 
> > Most of the content was written by Linus Torvalds and Greg Kroah-Hartman
> > in discussion on LKML. This is stated at the start of one of the
> > chapters and the original email thread is referenced in
> > 'pull-requests.rst'.
> > 
> > Signed-off-by: Tobin C. Harding 
> > ---
> > 
> > v2:
> >  - Change title of book, suggested by Dan Williams.
> > 
> > thanks,
> > Tobin.
> > 
> >  Documentation/index.rst|   1 +
> >  Documentation/maintainer/conf.py   |  10 ++
> >  Documentation/maintainer/configure-git.rst |  34 ++
> >  Documentation/maintainer/index.rst |  10 ++
> >  Documentation/maintainer/pull-requests.rst | 178 
> > +
> >  5 files changed, 233 insertions(+)
> >  create mode 100644 Documentation/maintainer/conf.py
> >  create mode 100644 Documentation/maintainer/configure-git.rst
> >  create mode 100644 Documentation/maintainer/index.rst
> >  create mode 100644 Documentation/maintainer/pull-requests.rst
> > 
> > diff --git a/Documentation/index.rst b/Documentation/index.rst
> > index cb7f1ba5b3b1..a4fb34dddcf3 100644
> > --- a/Documentation/index.rst
> > +++ b/Documentation/index.rst
> > @@ -52,6 +52,7 @@ merged much easier.
> > dev-tools/index
> > doc-guide/index
> > kernel-hacking/index
> > +   maintainer/index
> >  
> >  Kernel API documentation
> >  
> > diff --git a/Documentation/maintainer/conf.py 
> > b/Documentation/maintainer/conf.py
> > new file mode 100644
> > index ..81e9eb7a7884
> > --- /dev/null
> > +++ b/Documentation/maintainer/conf.py
> > @@ -0,0 +1,10 @@
> > +# -*- 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/maintainer/configure-git.rst 
> > b/Documentation/maintainer/configure-git.rst
> > new file mode 100644
> > index ..780d2c84
> > --- /dev/null
> > +++ b/Documentation/maintainer/configure-git.rst
> > @@ -0,0 +1,34 @@
> > +.. _configuregit:
> > +
> > +Configure Git
> > +=
> > +
> > +This chapter describes maintainer level git configuration.
> > +
> > +Tagged branches used in :ref:`Documentation/maintainer/pull-requests.rst
> > +` should be signed with the developers public GPG key. Signed
> > +tags can be created by passing the ``-u`` flag to ``git tag``. However,
> > +since you would *usually* use the same key for the same project, you can
> > +set it once with
> > +::
> > +
> > +   git config user.signingkey "keyname"
> > +
> > +Alternatively, edit your ``.git/config`` or ``~/.gitconfig`` file by hand:
> > +::
> > +
> > +   [user]
> > +   name = Jane Developer
> > +   email = j...@domain.org
> > +   signingkey = j...@domain.org
> > +
> > +You may need to tell ``git`` to use ``gpg2``
> > +::
> > +
> > +   [gpg]
> > +   program = /path/to/gpg2
> > +
> > +You may also like to tell ``gpg`` which ``tty`` to use (add to your shell 
> > rc file)
> > +::
> >

Re: [PATCH v2] doc: add maintainer book

[Tobin C. Harding]

On Mon, Nov 27, 2017 at 07:01:23PM -0200, Mauro Carvalho Chehab wrote:
> Em Tue, 28 Nov 2017 07:53:03 +1100
> "Tobin C. Harding"  escreveu:
> 
> > On Mon, Nov 27, 2017 at 04:57:30PM -0200, Mauro Carvalho Chehab wrote:
> > > Em Sat, 25 Nov 2017 08:44:19 +1100
> > > "Tobin C. Harding"  escreveu:
> > > 
> > > > There is currently very little documentation in the kernel on maintainer
> > > > level tasks. In particular there are no documents on creating pull
> > > > requests to submit to Linus.
> > > > 
> > > > Quoting Greg Kroah-Hartman on LKML:
> > > > 
> > > > Anyway, this actually came up at the kernel summit / maintainer
> > > > meeting a few weeks ago, in that "how do I make a
> > > > good pull request to Linus" is something we need to document.
> > > > 
> > > > Here's what I do, and it seems to work well, so maybe we should turn
> > > > it into the start of the documentation for how to do it.
> > > > 
> > > > (quote references: kernel summit, Europe 2017)
> > > > 
> > > > Create a new kernel documentation book 'how to be a maintainer'
> > > > (suggested by Jonathan Corbet). Add chapters on 'configuring git' and
> > > > 'creating a pull request'.
> > > > 
> > > > Most of the content was written by Linus Torvalds and Greg Kroah-Hartman
> > > > in discussion on LKML. This is stated at the start of one of the
> > > > chapters and the original email thread is referenced in
> > > > 'pull-requests.rst'.
> > > > 
> > > > Signed-off-by: Tobin C. Harding 
> > > > ---
> > > > 
> > > > v2:
> > > >  - Change title of book, suggested by Dan Williams.
> > > > 
> > > > thanks,
> > > > Tobin.
> > > > 
> > > >  Documentation/index.rst|   1 +
> > > >  Documentation/maintainer/conf.py   |  10 ++
> > > >  Documentation/maintainer/configure-git.rst |  34 ++
> > > >  Documentation/maintainer/index.rst |  10 ++
> > > >  Documentation/maintainer/pull-requests.rst | 178 
> > > > +
> > > >  5 files changed, 233 insertions(+)
> > > >  create mode 100644 Documentation/maintainer/conf.py
> > > >  create mode 100644 Documentation/maintainer/configure-git.rst
> > > >  create mode 100644 Documentation/maintainer/index.rst
> > > >  create mode 100644 Documentation/maintainer/pull-requests.rst
> > > > 
> > > > diff --git a/Documentation/index.rst b/Documentation/index.rst
> > > > index cb7f1ba5b3b1..a4fb34dddcf3 100644
> > > > --- a/Documentation/index.rst
> > > > +++ b/Documentation/index.rst
> > > > @@ -52,6 +52,7 @@ merged much easier.
> > > > dev-tools/index
> > > > doc-guide/index
> > > > kernel-hacking/index
> > > > +   maintainer/index
> > > >  
> > > >  Kernel API documentation
> > > >  
> > > > diff --git a/Documentation/maintainer/conf.py 
> > > > b/Documentation/maintainer/conf.py
> > > > new file mode 100644
> > > > index ..81e9eb7a7884
> > > > --- /dev/null
> > > > +++ b/Documentation/maintainer/conf.py
> > > > @@ -0,0 +1,10 @@
> > > > +# -*- 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/maintainer/configure-git.rst 
> > > > b/Documentation/maintainer/configure-git.rst
> > > > new file mode 100644
> > > > index ..780d2c84
> > > > --- /dev/null
> > > > +++ b/Documentation/maintainer/configure-git.rst
> > > > @@ -0,0 +1,34 @@
> > > > +.. _configuregit:
> > > > +
> > > > +Configure Git
> > > > +=
> > > > +
> > >

Re: Are .txt -> .rst patches welcome

[Tobin C. Harding]

On Tue, Nov 28, 2017 at 11:03:56AM -0700, Jonathan Corbet wrote:
> On Fri, 24 Nov 2017 10:30:56 +1100
> "Tobin C. Harding"  wrote:
> 
> > What's the status of the move from .txt to .rst files within the
> > kernel?
> > 
> > The point of the question; are patches converting .txt files in
> > Documentation/ to .rst files welcome?
> 
> As a general rule, yes, they are.  That said, I'm much happier when these
> patches also involve a look at the documentation to ensure that it's still
> current and worth keeping and also include some thought as to where the
> converted documentation should go in a more rational hierarchy.
> 
> A different way of putting it would be: Documentation/ now is a mess.
> Simply converting .txt files to RST does not, on its own, reduce the mess
> factor much.  But it can be a part of the bigger effort to turn the
> kernel's documentation into some sort of coherent whole.

Cool, thanks for the reply. I was hoping to do the odd conversion for
the purely selfish reason that updating the doc makes me read (and
understand) them thoroughly. I'll keep your points in mind.

thanks,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v3] doc: add maintainer book

[Tobin C. Harding]

There is currently very little documentation in the kernel on maintainer
level tasks. In particular there are no documents on creating pull
requests to submit to Linus.

Quoting Greg Kroah-Hartman on LKML:

Anyway, this actually came up at the kernel summit / maintainer
meeting a few weeks ago, in that "how do I make a
good pull request to Linus" is something we need to document.

Here's what I do, and it seems to work well, so maybe we should turn
it into the start of the documentation for how to do it.

(quote references: kernel summit, Europe 2017)

Create a new kernel documentation book 'how to be a maintainer'
(suggested by Jonathan Corbet). Add chapters on 'configuring git' and
'creating a pull request'.

Most of the content was written by Linus Torvalds and Greg Kroah-Hartman
in discussion on LKML. This is stated at the start of one of the
chapters and the original email thread is referenced in
'pull-requests.rst'.

Signed-off-by: Tobin C. Harding 
Reviewed-by: Greg Kroah-Hartman 

---

v3:
 - Modified details for branch and tag naming, suggested by Mauro
   Carvalho Chehab.
 - Added example email subject line for submitting pull requests.
 - Re-added Greg's reviewed-by tag from version 1.

v2:
 - Change title of book, suggested by Dan Williams.

---
 Documentation/index.rst|   1 +
 Documentation/maintainer/conf.py   |  10 ++
 Documentation/maintainer/configure-git.rst |  34 ++
 Documentation/maintainer/index.rst |  10 ++
 Documentation/maintainer/pull-requests.rst | 182 +
 5 files changed, 237 insertions(+)
 create mode 100644 Documentation/maintainer/conf.py
 create mode 100644 Documentation/maintainer/configure-git.rst
 create mode 100644 Documentation/maintainer/index.rst
 create mode 100644 Documentation/maintainer/pull-requests.rst

diff --git a/Documentation/index.rst b/Documentation/index.rst
index cb7f1ba5b3b1..a4fb34dddcf3 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -52,6 +52,7 @@ merged much easier.
dev-tools/index
doc-guide/index
kernel-hacking/index
+   maintainer/index
 
 Kernel API documentation
 
diff --git a/Documentation/maintainer/conf.py b/Documentation/maintainer/conf.py
new file mode 100644
index ..81e9eb7a7884
--- /dev/null
+++ b/Documentation/maintainer/conf.py
@@ -0,0 +1,10 @@
+# -*- 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/maintainer/configure-git.rst 
b/Documentation/maintainer/configure-git.rst
new file mode 100644
index ..780d2c84
--- /dev/null
+++ b/Documentation/maintainer/configure-git.rst
@@ -0,0 +1,34 @@
+.. _configuregit:
+
+Configure Git
+=
+
+This chapter describes maintainer level git configuration.
+
+Tagged branches used in :ref:`Documentation/maintainer/pull-requests.rst
+` should be signed with the developers public GPG key. Signed
+tags can be created by passing the ``-u`` flag to ``git tag``. However,
+since you would *usually* use the same key for the same project, you can
+set it once with
+::
+
+   git config user.signingkey "keyname"
+
+Alternatively, edit your ``.git/config`` or ``~/.gitconfig`` file by hand:
+::
+
+   [user]
+   name = Jane Developer
+   email = j...@domain.org
+   signingkey = j...@domain.org
+
+You may need to tell ``git`` to use ``gpg2``
+::
+
+   [gpg]
+   program = /path/to/gpg2
+
+You may also like to tell ``gpg`` which ``tty`` to use (add to your shell rc 
file)
+::
+
+   export GPG_TTY=$(tty)
diff --git a/Documentation/maintainer/index.rst 
b/Documentation/maintainer/index.rst
new file mode 100644
index ..fa84ac9cae39
--- /dev/null
+++ b/Documentation/maintainer/index.rst
@@ -0,0 +1,10 @@
+==
+Kernel Maintainer Handbook
+==
+
+.. toctree::
+   :maxdepth: 2
+
+   configure-git
+   pull-requests
+
diff --git a/Documentation/maintainer/pull-requests.rst 
b/Documentation/maintainer/pull-requests.rst
new file mode 100644
index ..a25e1002a5b9
--- /dev/null
+++ b/Documentation/maintainer/pull-requests.rst
@@ -0,0 +1,182 @@
+.. _pullrequests:
+
+Creating Pull Requests
+==
+
+This chapter describes how maintainers can create and submit pull requests
+to other maintainers. This is useful for transferring changes from one
+maintainers tree to another maintainers tree.
+
+This document was written by Tobin C. Harding (who at that time, was not an
+experienced maintainer) primarily from comments made by Greg Kroa

Re: [PATCH v3] doc: add maintainer book

[Tobin C. Harding]

On Thu, Nov 30, 2017 at 07:01:19AM -0200, Mauro Carvalho Chehab wrote:
> Em Thu, 30 Nov 2017 12:55:07 +1100
> "Tobin C. Harding"  escreveu:
> 
> > There is currently very little documentation in the kernel on maintainer
> > level tasks. In particular there are no documents on creating pull
> > requests to submit to Linus.
> > 
> > Quoting Greg Kroah-Hartman on LKML:
> > 
> > Anyway, this actually came up at the kernel summit / maintainer
> > meeting a few weeks ago, in that "how do I make a
> > good pull request to Linus" is something we need to document.
> > 
> > Here's what I do, and it seems to work well, so maybe we should turn
> > it into the start of the documentation for how to do it.
> > 
> > (quote references: kernel summit, Europe 2017)
> > 
> > Create a new kernel documentation book 'how to be a maintainer'
> > (suggested by Jonathan Corbet). Add chapters on 'configuring git' and
> > 'creating a pull request'.
> > 
> > Most of the content was written by Linus Torvalds and Greg Kroah-Hartman
> > in discussion on LKML. This is stated at the start of one of the
> > chapters and the original email thread is referenced in
> > 'pull-requests.rst'.
> > 
> > Signed-off-by: Tobin C. Harding 
> > Reviewed-by: Greg Kroah-Hartman 
> > 
> > ---
> > 
> > v3:
> >  - Modified details for branch and tag naming, suggested by Mauro
> >Carvalho Chehab.
> >  - Added example email subject line for submitting pull requests.
> >  - Re-added Greg's reviewed-by tag from version 1.
> > 
> > v2:
> >  - Change title of book, suggested by Dan Williams.
> > 
> > ---
> >  Documentation/index.rst|   1 +
> >  Documentation/maintainer/conf.py   |  10 ++
> >  Documentation/maintainer/configure-git.rst |  34 ++
> >  Documentation/maintainer/index.rst |  10 ++
> >  Documentation/maintainer/pull-requests.rst | 182 
> > +
> >  5 files changed, 237 insertions(+)
> >  create mode 100644 Documentation/maintainer/conf.py
> >  create mode 100644 Documentation/maintainer/configure-git.rst
> >  create mode 100644 Documentation/maintainer/index.rst
> >  create mode 100644 Documentation/maintainer/pull-requests.rst
> > 
> > diff --git a/Documentation/index.rst b/Documentation/index.rst
> > index cb7f1ba5b3b1..a4fb34dddcf3 100644
> > --- a/Documentation/index.rst
> > +++ b/Documentation/index.rst
> > @@ -52,6 +52,7 @@ merged much easier.
> > dev-tools/index
> > doc-guide/index
> > kernel-hacking/index
> > +   maintainer/index
> >  
> >  Kernel API documentation
> >  
> > diff --git a/Documentation/maintainer/conf.py 
> > b/Documentation/maintainer/conf.py
> > new file mode 100644
> > index ..81e9eb7a7884
> > --- /dev/null
> > +++ b/Documentation/maintainer/conf.py
> > @@ -0,0 +1,10 @@
> > +# -*- 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/maintainer/configure-git.rst 
> > b/Documentation/maintainer/configure-git.rst
> > new file mode 100644
> > index ..780d2c84
> > --- /dev/null
> > +++ b/Documentation/maintainer/configure-git.rst
> > @@ -0,0 +1,34 @@
> > +.. _configuregit:
> > +
> > +Configure Git
> > +=
> > +
> > +This chapter describes maintainer level git configuration.
> > +
> > +Tagged branches used in :ref:`Documentation/maintainer/pull-requests.rst
> > +` should be signed with the developers public GPG key. Signed
> > +tags can be created by passing the ``-u`` flag to ``git tag``. However,
> > +since you would *usually* use the same key for the same project, you can
> > +set it once with
> > +::
> > +
> > +   git config user.signingkey "keyname"
> > +
> > +Alternatively, edit your ``.git/config`` or ``~/.gitconfig`` file by hand:
> > +::
> > +
> > +   [user]
> > +   name = Jane Developer
> > +   email = j...@domain.org
> > +   signingkey = j...@domain.org
&g

Re: [PATCH v3] doc: add maintainer book

[Tobin C. Harding]

On Thu, Nov 30, 2017 at 09:06:21AM -0200, Mauro Carvalho Chehab wrote:
> Em Thu, 30 Nov 2017 21:47:44 +1100
> "Tobin C. Harding"  escreveu:
> 
> > On Thu, Nov 30, 2017 at 07:01:19AM -0200, Mauro Carvalho Chehab wrote:
> > > Em Thu, 30 Nov 2017 12:55:07 +1100
> > > "Tobin C. Harding"  escreveu:
> 
> 
> > > > +So, by way of an example, Greg gives; a pull request with 
> > > > miscellaneous  
> > > 
> > > Nitpick: there's an extra ";" character above:
> > >   gives; -> gives  
> > 
> > Ha ha, I thought for ages how to word this bit. The irony of grammar
> > corrections from a non-native speaker is not lost on me :)
> 
> :-)
> 
> Well, if that serves as a consolation, I had to go to a dictionary to
> understand "By way of":
> 
>   https://www.collinsdictionary.com/dictionary/english/by-way-of
> 
> As that was a new expression for me :-)
> 
> Anyway, AFAIKT, English and Portuguese (and probably Spanish) have 
> similar rules with regards to commas and semicolons.

Oh cool, I didn't know that. Eu fallo um pouco Portugese muito no
esrever bem. I never learned to spell in Portuguese.

> > Perhaps:
> > 
> >  By way of an example Greg gives, a pull request with miscellaneous
> > 
> > I'll take any nitpicks you have Mauro, striving for perfection here. Thanks.
> 
> Yeah, that looks a way better on my eyes.

thanks,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v4] doc: add maintainer book

[Tobin C. Harding]

There is currently very little documentation in the kernel on maintainer
level tasks. In particular there are no documents on creating pull
requests to submit to Linus.

Quoting Greg Kroah-Hartman on LKML:

Anyway, this actually came up at the kernel summit / maintainer
meeting a few weeks ago, in that "how do I make a
good pull request to Linus" is something we need to document.

Here's what I do, and it seems to work well, so maybe we should turn
it into the start of the documentation for how to do it.

(quote references: kernel summit, Europe 2017)

Create a new kernel documentation book 'how to be a maintainer'
(suggested by Jonathan Corbet). Add chapters on 'configuring git' and
'creating a pull request'.

Most of the content was written by Linus Torvalds and Greg Kroah-Hartman
in discussion on LKML. This is stated at the start of one of the
chapters and the original email thread is referenced in
'pull-requests.rst'.

Signed-off-by: Tobin C. Harding 
Reviewed-by: Greg Kroah-Hartman 
Reviewed-by: Mauro Carvalho Chehab 

---

v4:
 - Add tweaks from Mauro.
 - Add reviewed-by tag for Mauro.

v3:
 - Modified details for branch and tag naming, suggested by Mauro
   Carvalho Chehab.
 - Added example email subject line for submitting pull requests.
 - Re-added Greg's reviewed-by tag from version 1.

v2:
 - Change title of book, suggested by Dan Williams.

---
 Documentation/index.rst|   1 +
 Documentation/maintainer/conf.py   |  10 ++
 Documentation/maintainer/configure-git.rst |  34 ++
 Documentation/maintainer/index.rst |  10 ++
 Documentation/maintainer/pull-requests.rst | 178 +
 5 files changed, 233 insertions(+)
 create mode 100644 Documentation/maintainer/conf.py
 create mode 100644 Documentation/maintainer/configure-git.rst
 create mode 100644 Documentation/maintainer/index.rst
 create mode 100644 Documentation/maintainer/pull-requests.rst

diff --git a/Documentation/index.rst b/Documentation/index.rst
index cb7f1ba5b3b1..a4fb34dddcf3 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -52,6 +52,7 @@ merged much easier.
dev-tools/index
doc-guide/index
kernel-hacking/index
+   maintainer/index
 
 Kernel API documentation
 
diff --git a/Documentation/maintainer/conf.py b/Documentation/maintainer/conf.py
new file mode 100644
index ..81e9eb7a7884
--- /dev/null
+++ b/Documentation/maintainer/conf.py
@@ -0,0 +1,10 @@
+# -*- 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/maintainer/configure-git.rst 
b/Documentation/maintainer/configure-git.rst
new file mode 100644
index ..780d2c84
--- /dev/null
+++ b/Documentation/maintainer/configure-git.rst
@@ -0,0 +1,34 @@
+.. _configuregit:
+
+Configure Git
+=
+
+This chapter describes maintainer level git configuration.
+
+Tagged branches used in :ref:`Documentation/maintainer/pull-requests.rst
+` should be signed with the developers public GPG key. Signed
+tags can be created by passing the ``-u`` flag to ``git tag``. However,
+since you would *usually* use the same key for the same project, you can
+set it once with
+::
+
+   git config user.signingkey "keyname"
+
+Alternatively, edit your ``.git/config`` or ``~/.gitconfig`` file by hand:
+::
+
+   [user]
+   name = Jane Developer
+   email = j...@domain.org
+   signingkey = j...@domain.org
+
+You may need to tell ``git`` to use ``gpg2``
+::
+
+   [gpg]
+   program = /path/to/gpg2
+
+You may also like to tell ``gpg`` which ``tty`` to use (add to your shell rc 
file)
+::
+
+   export GPG_TTY=$(tty)
diff --git a/Documentation/maintainer/index.rst 
b/Documentation/maintainer/index.rst
new file mode 100644
index ..fa84ac9cae39
--- /dev/null
+++ b/Documentation/maintainer/index.rst
@@ -0,0 +1,10 @@
+==
+Kernel Maintainer Handbook
+==
+
+.. toctree::
+   :maxdepth: 2
+
+   configure-git
+   pull-requests
+
diff --git a/Documentation/maintainer/pull-requests.rst 
b/Documentation/maintainer/pull-requests.rst
new file mode 100644
index ..a19db3458b56
--- /dev/null
+++ b/Documentation/maintainer/pull-requests.rst
@@ -0,0 +1,178 @@
+.. _pullrequests:
+
+Creating Pull Requests
+==
+
+This chapter describes how maintainers can create and submit pull requests
+to other maintainers. This is useful for transferring changes from one
+maintainers tree to another maintainers tree.
+
+This document was written by Tobin C. H

[PATCH] doc: update 'unique identifiers'

[Tobin C. Harding]

Advice about what to use as a unique identifier is no longer valid since
patch series was merged to hash pointers printed with %p. We can use
this as a unique identifier now.

Signed-off-by: Tobin C. Harding 
---
 Documentation/security/self-protection.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/security/self-protection.rst 
b/Documentation/security/self-protection.rst
index 60c8bd8b77bf..f10f47cad825 100644
--- a/Documentation/security/self-protection.rst
+++ b/Documentation/security/self-protection.rst
@@ -274,8 +274,8 @@ Unique identifiers
 --
 
 Kernel memory addresses must never be used as identifiers exposed to
-userspace. Instead, use an atomic counter, an idr, or similar unique
-identifier.
+userspace. Printk specifier %p hashes addresses by default now and can be
+used as a unique identifier.
 
 Memory initialization
 -
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc: update 'unique identifiers'

[Tobin C. Harding]

On Mon, Dec 04, 2017 at 01:28:45PM -0800, Kees Cook wrote:
> On Mon, Dec 4, 2017 at 1:22 PM, Tobin C. Harding  wrote:
> > Advice about what to use as a unique identifier is no longer valid since
> > patch series was merged to hash pointers printed with %p. We can use
> > this as a unique identifier now.
> >
> > Signed-off-by: Tobin C. Harding 
> 
> I don't agree: %p should still not be encouraged. Exposing an
> identifier to userspace needs careful consideration, and atomics,
> idrs, etc, continue to be a good recommendation here, as far as I'm
> concerned.

Ok no worries, so these docs are valid and current as is? I have no
agenda with this patch, just attempting to keep the docs in line with
the code :)

thanks,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc: update 'unique identifiers'

[Tobin C. Harding]

On Mon, Dec 04, 2017 at 01:51:42PM -0800, Kees Cook wrote:
> On Mon, Dec 4, 2017 at 1:44 PM, Tobin C. Harding  wrote:
> > On Mon, Dec 04, 2017 at 01:28:45PM -0800, Kees Cook wrote:
> >> On Mon, Dec 4, 2017 at 1:22 PM, Tobin C. Harding  wrote:
> >> > Advice about what to use as a unique identifier is no longer valid since
> >> > patch series was merged to hash pointers printed with %p. We can use
> >> > this as a unique identifier now.
> >> >
> >> > Signed-off-by: Tobin C. Harding 
> >>
> >> I don't agree: %p should still not be encouraged. Exposing an
> >> identifier to userspace needs careful consideration, and atomics,
> >> idrs, etc, continue to be a good recommendation here, as far as I'm
> >> concerned.
> >
> > Ok no worries, so these docs are valid and current as is? I have no
> > agenda with this patch, just attempting to keep the docs in line with
> > the code :)
> 
> I think a section could be added/updated discussing leaks and %p (in
> that it is hashing now), that would be quite welcome!
> 
> I do, probably need to go through this document and update a few things.

How about I do whatever generates the least amount of work for you. Is
it easier if I add the %p stuff for you to review or is it easier to
just leave it for you to do in your own time?

thanks,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] doc: convert printk-formats.txt to rst

[Tobin C. Harding]

Documentation/printk-formats.txt is a candidate for conversion to
ReStructuredText format. Some effort has already been made to do this
conversion even thought the suffix is currently .txt

Changes required to complete conversion

- Add double backticks where needed.
- Add entry to Documentation/index.rst
- Use flat-table instead of ASCII table.
- Fix minor grammatical errors.
- Capitalize headers and correctly order heading adornments.
- Use 'Passed by reference' uniformly.
- Update pointer documentation around %px specifier.
- Fix erroneous double backticks (to commas).
- Simplify documentation for kobject.
- Convert lib/vsnprintf.c function docs to use kernel-docs and
  include in Documentation/printk-formats.rst

Signed-off-by: Tobin C. Harding 
---

The last two need special reviewing please. In particular the conversion
of kernel-docs in vsnprintf.c attempt was made to reduce documentation
duplication with comments in the source code being simplified in order
to be suitable for inclusion in Documentation/printk-formats.rst

I used -M when formatting the patch. If you don't like the diff with
this flag just holla.

thanks,
Tobin.

 Documentation/index.rst|  10 +
 .../{printk-formats.txt => printk-formats.rst} | 295 -
 lib/vsprintf.c | 160 +--
 3 files changed, 235 insertions(+), 230 deletions(-)
 rename Documentation/{printk-formats.txt => printk-formats.rst} (61%)

diff --git a/Documentation/index.rst b/Documentation/index.rst
index cb7f1ba5b3b1..83ace60efbe7 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -87,6 +87,16 @@ implementation.
 
sh/index
 
+Miscellaneous documentation
+---
+
+These guides contain general information useful when writing kernel code.
+
+.. toctree::
+   :maxdepth: 1
+
+   printk-formats
+
 Korean translations
 ---
 
diff --git a/Documentation/printk-formats.txt b/Documentation/printk-formats.rst
similarity index 61%
rename from Documentation/printk-formats.txt
rename to Documentation/printk-formats.rst
index aa0a776c817a..51449d213748 100644
--- a/Documentation/printk-formats.txt
+++ b/Documentation/printk-formats.rst
@@ -1,6 +1,6 @@
-=
-How to get printk format specifiers right
-=
+=
+How to Get ``printk`` Format Specifiers Right
+=
 
 :Author: Randy Dunlap 
 :Author: Andrew Murray 
@@ -8,56 +8,91 @@ How to get printk format specifiers right
 Integer types
 =
 
-::
+For printing integer types, we have the following format specifiers:
+   
+   .. flat-table:: 
+  :widths: 2 2
+
+  * - **Type**
+   - **Specifier**
+
+  * - ``int``
+- ``%d`` or ``%x``
+
+  * - ``unsigned int``
+   - ``%u`` or ``%x``
+
+  * - ``long``
+   - ``%ld`` or ``%lx``
+
+  * - ``unsigned long``
+   - ``%lu`` or ``%lx``
+
+  * - ``long long``
+   - ``%lld`` or ``%llx``
 
-   If variable is of Type, use printk format specifier:
-   
-   int %d or %x
-   unsigned int%u or %x
-   long%ld or %lx
-   unsigned long   %lu or %lx
-   long long   %lld or %llx
-   unsigned long long  %llu or %llx
-   size_t  %zu or %zx
-   ssize_t %zd or %zx
-   s32 %d or %x
-   u32 %u or %x
-   s64 %lld or %llx
-   u64 %llu or %llx
-
-If  is dependent on a config option for its size (e.g., ``sector_t``,
+  * - ``unsigned long long``
+   - ``%llu`` or ``%llx``
+
+  * - ``size_t``
+   - ``%zu`` or ``%zx``
+
+  * - ``ssize_t``
+   - ``%zd`` or ``%zx``
+
+  * - ``s32``
+   - ``%d`` or ``%x``
+
+  * - ``u32``
+   - ``%u`` or ``%x``
+
+  * - ``s64``
+   - ``%lld`` or ``%llx``
+
+  * - ``u64``
+   - ``%llu`` or ``%llx``
+
+
+If  is dependent on a config option for its size (e.g., ``sector_t``,
 ``blkcnt_t``) or is architecture-dependent for its size (e.g., ``tcflag_t``),
 use a format specifier of its largest possible type and explicitly cast to it.
 
 Example::
 
-   printk("test: sector number/total blocks: %llu/%llu\n",
-   (unsigned long long)sector, (unsigned long long)blockcount);
+   printk("test: total blocks: %llu\n", (unsigned long long)blockcount);
 
-Reminder: ``sizeof()`` result is of type ``size_t``.
+Reminder: ``sizeof()`` returns type ``size_t``.
 
-The kernel's printf does not support ``%n`

Re: [PATCH] doc: convert printk-formats.txt to rst

[Tobin C. Harding]

On Wed, Dec 06, 2017 at 10:18:49AM -0800, Randy Dunlap wrote:

Thanks for your comments Randy.

> On 12/05/2017 05:45 PM, Tobin C. Harding wrote:
> > Documentation/printk-formats.txt is a candidate for conversion to
> > ReStructuredText format. Some effort has already been made to do this
> > conversion even thought the suffix is currently .txt
> > 
> > Changes required to complete conversion
> > 
> > - Add double backticks where needed.
> > - Add entry to Documentation/index.rst
> > - Use flat-table instead of ASCII table.
> > - Fix minor grammatical errors.
> > - Capitalize headers and correctly order heading adornments.
> 
> That's a style choice and an unneeded change (referring to Capitalize 
> headers).

No worries, will revert.

> > - Use 'Passed by reference' uniformly.
> > - Update pointer documentation around %px specifier.
> > - Fix erroneous double backticks (to commas).
> > - Simplify documentation for kobject.
> > - Convert lib/vsnprintf.c function docs to use kernel-docs and
> >   include in Documentation/printk-formats.rst
> 
> good idea.
>
> > 
> > Signed-off-by: Tobin C. Harding 
> > ---
> > 
> > The last two need special reviewing please. In particular the conversion
> > of kernel-docs in vsnprintf.c attempt was made to reduce documentation
> > duplication with comments in the source code being simplified in order
> > to be suitable for inclusion in Documentation/printk-formats.rst
> > 
> > I used -M when formatting the patch. If you don't like the diff with
> > this flag just holla.
> > 
> > thanks,
> > Tobin.
> > 
> >  Documentation/index.rst|  10 +
> >  .../{printk-formats.txt => printk-formats.rst} | 295 
> > -
> >  lib/vsprintf.c | 160 +--
> >  3 files changed, 235 insertions(+), 230 deletions(-)
> >  rename Documentation/{printk-formats.txt => printk-formats.rst} (61%)
> 
> > diff --git a/Documentation/printk-formats.txt 
> > b/Documentation/printk-formats.rst
> > similarity index 61%
> > rename from Documentation/printk-formats.txt
> > rename to Documentation/printk-formats.rst
> > index aa0a776c817a..51449d213748 100644
> > --- a/Documentation/printk-formats.txt
> > +++ b/Documentation/printk-formats.rst
> > @@ -1,6 +1,6 @@
> > -=
> > -How to get printk format specifiers right
> > -=
> > +=
> > +How to Get ``printk`` Format Specifiers Right
> > +=
> >  
> >  :Author: Randy Dunlap 
> >  :Author: Andrew Murray 
> > @@ -8,56 +8,91 @@ How to get printk format specifiers right
> >  Integer types
> >  =
> >  
> > -::
> > +For printing integer types, we have the following format specifiers:
> > +   
> > +   .. flat-table:: 
> > +  :widths: 2 2
> > +
> > +  * - **Type**
> > +   - **Specifier**
> > +
> > +  * - ``int``
> > +- ``%d`` or ``%x``
> > +
> > +  * - ``unsigned int``
> > +   - ``%u`` or ``%x``
> > +
> > +  * - ``long``
> > +   - ``%ld`` or ``%lx``
> > +
> > +  * - ``unsigned long``
> > +   - ``%lu`` or ``%lx``
> > +
> > +  * - ``long long``
> > +   - ``%lld`` or ``%llx``
> >  
> > -   If variable is of Type, use printk format specifier:
> > -   
> > -   int %d or %x
> > -   unsigned int%u or %x
> > -   long%ld or %lx
> > -   unsigned long   %lu or %lx
> > -   long long   %lld or %llx
> > -   unsigned long long  %llu or %llx
> > -   size_t  %zu or %zx
> > -   ssize_t %zd or %zx
> > -   s32 %d or %x
> > -   u32 %u or %x
> > -   s64 %lld or %llx
> > -   u64 %llu or %llx
> > -
> > -If  is dependent on a config option for its size (e.g., ``sector_t``,
> > +  * - ``unsigned long long``
> > +   - ``%llu`` or ``%llx``
> > +
> > +  * - ``size_t``
> > +   - ``%zu`` or ``%zx``
> > +
> > +  * - ``ssize_t``
> > +   - ``%zd`` or ``%

Re: [PATCH] doc: convert printk-formats.txt to rst

[Tobin C. Harding]

On Wed, Dec 06, 2017 at 11:23:25AM -0700, Jonathan Corbet wrote:
> On Wed,  6 Dec 2017 12:45:29 +1100
> "Tobin C. Harding"  wrote:
> 
> > Documentation/printk-formats.txt is a candidate for conversion to
> > ReStructuredText format. Some effort has already been made to do this
> > conversion even thought the suffix is currently .txt
> > 
> > Changes required to complete conversion
> > 
> > - Add double backticks where needed.
> > - Add entry to Documentation/index.rst
> > - Use flat-table instead of ASCII table.
> > - Fix minor grammatical errors.
> > - Capitalize headers and correctly order heading adornments.
> > - Use 'Passed by reference' uniformly.
> > - Update pointer documentation around %px specifier.
> > - Fix erroneous double backticks (to commas).
> > - Simplify documentation for kobject.
> > - Convert lib/vsnprintf.c function docs to use kernel-docs and
> >   include in Documentation/printk-formats.rst
> > 
> > Signed-off-by: Tobin C. Harding 
> 
> Some comments from a quick review:
> 
>  - I would just put this into the core-api manual; we don't need to create
>a separate section for printk formats.

Cool, I was hoping you'd give some direction on this. thanks.

>  - I agree with Markus and others about the table.  I think I would go a
>little further and encourage observance of the "use minimal markup"
>rule.  Lots of ``double backticks`` make for slightly nicer HTML/PDF
>output, but they come at the expense of plain-text readability, which
>is something we really don't want to sacrifice.

Great. I personally don't read docs in HTML/PDF so I like this ruling.

>  - The vsprintf.c part is probably not for me to take, so it should be
>split out into a separate patch.

I'm much less experienced than you Jon so please say if I am wrong but
since the rst file depends on the changes to vsprintf.c wouldn't it be
better if the changes went into the mainline together. I can split it
into a two patch set if that is cleaner but putting the two patches
through different trees seems like a bad idea because of the
dependency. For what it's worth, I don't believe lib/vsprintf.c has a
maintainer. Linus took changes to that file from my tree just
recently. I don't know how this stuff works though in regards to merge
conflicts. (Please take everything I say here with a pinch of salt since
I have only maintained a tree for a few weeks now.)

thanks,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc: convert printk-formats.txt to rst

[Tobin C. Harding]

On Wed, Dec 06, 2017 at 10:18:49AM -0800, Randy Dunlap wrote:
> On 12/05/2017 05:45 PM, Tobin C. Harding wrote:
> > Documentation/printk-formats.txt is a candidate for conversion to
> > ReStructuredText format. Some effort has already been made to do this
> > conversion even thought the suffix is currently .txt
> > 
> > Changes required to complete conversion
> > 
> > - Add double backticks where needed.
> > - Add entry to Documentation/index.rst
> > - Use flat-table instead of ASCII table.
> > - Fix minor grammatical errors.
> > - Capitalize headers and correctly order heading adornments.
> 
> That's a style choice and an unneeded change (referring to Capitalize 
> headers).
> 
> > - Use 'Passed by reference' uniformly.
> > - Update pointer documentation around %px specifier.
> > - Fix erroneous double backticks (to commas).
> > - Simplify documentation for kobject.
> > - Convert lib/vsnprintf.c function docs to use kernel-docs and
> >   include in Documentation/printk-formats.rst
> 
> good idea.
> 
> > 
> > Signed-off-by: Tobin C. Harding 
> > ---
> > 
> > The last two need special reviewing please. In particular the conversion
> > of kernel-docs in vsnprintf.c attempt was made to reduce documentation
> > duplication with comments in the source code being simplified in order
> > to be suitable for inclusion in Documentation/printk-formats.rst
> > 
> > I used -M when formatting the patch. If you don't like the diff with
> > this flag just holla.
> > 
> > thanks,
> > Tobin.
> > 
> >  Documentation/index.rst|  10 +
> >  .../{printk-formats.txt => printk-formats.rst} | 295 
> > -
> >  lib/vsprintf.c | 160 +--
> >  3 files changed, 235 insertions(+), 230 deletions(-)
> >  rename Documentation/{printk-formats.txt => printk-formats.rst} (61%)
> 
> > diff --git a/Documentation/printk-formats.txt 
> > b/Documentation/printk-formats.rst
> > similarity index 61%
> > rename from Documentation/printk-formats.txt
> > rename to Documentation/printk-formats.rst
> > index aa0a776c817a..51449d213748 100644
> > --- a/Documentation/printk-formats.txt
> > +++ b/Documentation/printk-formats.rst
> > @@ -1,6 +1,6 @@
> > -=
> > -How to get printk format specifiers right
> > -=
> > +=
> > +How to Get ``printk`` Format Specifiers Right
> > +=
> >  
> >  :Author: Randy Dunlap 
> >  :Author: Andrew Murray 
> > @@ -8,56 +8,91 @@ How to get printk format specifiers right
> >  Integer types
> >  =
> >  
> > -::
> > +For printing integer types, we have the following format specifiers:
> > +   
> > +   .. flat-table:: 
> > +  :widths: 2 2
> > +
> > +  * - **Type**
> > +   - **Specifier**
> > +
> > +  * - ``int``
> > +- ``%d`` or ``%x``
> > +
> > +  * - ``unsigned int``
> > +   - ``%u`` or ``%x``
> > +
> > +  * - ``long``
> > +   - ``%ld`` or ``%lx``
> > +
> > +  * - ``unsigned long``
> > +   - ``%lu`` or ``%lx``
> > +
> > +  * - ``long long``
> > +   - ``%lld`` or ``%llx``
> >  
> > -   If variable is of Type, use printk format specifier:
> > -   
> > -   int %d or %x
> > -   unsigned int%u or %x
> > -   long%ld or %lx
> > -   unsigned long   %lu or %lx
> > -   long long   %lld or %llx
> > -   unsigned long long  %llu or %llx
> > -   size_t  %zu or %zx
> > -   ssize_t %zd or %zx
> > -   s32 %d or %x
> > -   u32 %u or %x
> > -   s64 %lld or %llx
> > -   u64 %llu or %llx
> > -
> > -If  is dependent on a config option for its size (e.g., ``sector_t``,
> > +  * - ``unsigned long long``
> > +   - ``%llu`` or ``%llx``
> > +
> > +  * - ``size_t``
> > +   - ``%zu`` or ``%zx``
> > +
> > +  * - ``ssize_t``
> > +   - ``%zd`` or ``%zx``
> > +
> > +  * - ``s32``
> &

[PATCH] docs: add documentation on printing kernel addresses

[Tobin C. Harding]

Hashing addresses printed with printk specifier %p was implemented
recently. During development a number of issues were raised regarding
leaking kernel addresses to userspace. We should update the
documentation appropriately.

Add documentation regarding printing kernel addresses.

Signed-off-by: Tobin C. Harding 
---

Is there a proffered method for subscripts in sphinx kernel docs? Here
we use '[*]' 

thanks,
Tobin.

 Documentation/security/self-protection.rst | 14 ++
 1 file changed, 14 insertions(+)

diff --git a/Documentation/security/self-protection.rst 
b/Documentation/security/self-protection.rst
index 60c8bd8b77bf..e711280cfdd7 100644
--- a/Documentation/security/self-protection.rst
+++ b/Documentation/security/self-protection.rst
@@ -270,6 +270,20 @@ attacks, it is important to defend against exposure of 
both kernel memory
 addresses and kernel memory contents (since they may contain kernel
 addresses or other sensitive things like canary values).
 
+Kernel addresses
+
+
+Printing kernel addresses to userspace leaks sensitive information about
+the kernel memory layout. Care should be exercised when using any printk
+specifier that prints the raw address, currently %px, %p[ad], (and %p[sSb]
+in certain circumstances [*]).  Any file written to using one of these
+specifiers should be readable only by privileged processes.
+
+Kernels 4.14 and older printed the raw address using %p. As of 4.15-rc1
+addresses printed with the specifier %p are hashed before printing.
+
+[*] If symbol lookup fails, the raw address is currently printed.
+
 Unique identifiers
 --
 
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] docs: add documentation on printing kernel addresses

[Tobin C. Harding]

On Wed, Dec 06, 2017 at 04:43:40PM -0800, Kees Cook wrote:
> On Wed, Dec 6, 2017 at 4:26 PM, Tobin C. Harding  wrote:
> > Hashing addresses printed with printk specifier %p was implemented
> > recently. During development a number of issues were raised regarding
> > leaking kernel addresses to userspace. We should update the
> > documentation appropriately.
> >
> > Add documentation regarding printing kernel addresses.
> >
> > Signed-off-by: Tobin C. Harding 
> 
> Acked-by: Kees Cook 
> 
> > ---
> >
> > Is there a proffered method for subscripts in sphinx kernel docs? Here
> > we use '[*]'
> 
> Great question... I can't find an answer to this. :P
> 
> >
> > thanks,
> > Tobin.
> >
> >  Documentation/security/self-protection.rst | 14 ++
> >  1 file changed, 14 insertions(+)
> >
> > diff --git a/Documentation/security/self-protection.rst 
> > b/Documentation/security/self-protection.rst
> > index 60c8bd8b77bf..e711280cfdd7 100644
> > --- a/Documentation/security/self-protection.rst
> > +++ b/Documentation/security/self-protection.rst
> > @@ -270,6 +270,20 @@ attacks, it is important to defend against exposure of 
> > both kernel memory
> >  addresses and kernel memory contents (since they may contain kernel
> >  addresses or other sensitive things like canary values).
> >
> > +Kernel addresses
> > +
> > +
> > +Printing kernel addresses to userspace leaks sensitive information about
> > +the kernel memory layout. Care should be exercised when using any printk
> > +specifier that prints the raw address, currently %px, %p[ad], (and %p[sSb]
> > +in certain circumstances [*]).  Any file written to using one of these
> > +specifiers should be readable only by privileged processes.
> > +
> > +Kernels 4.14 and older printed the raw address using %p. As of 4.15-rc1
> > +addresses printed with the specifier %p are hashed before printing.
> > +
> > +[*] If symbol lookup fails, the raw address is currently printed.
> 
> Is there a plan to adjust this case?

RFC is in flight at the moment

[RFC 0/3] kallsyms: don't leak address when printing symbol

You commented already that you liked it. Had no response from Steve, I
was intending to give him two weeks and then put in the patch for
real.

Or I could put it in without the ftrace stuff and just break tracing -
just kidding, I wouldn't do that :)

thanks,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc: convert printk-formats.txt to rst

[Tobin C. Harding]

On Wed, Dec 06, 2017 at 04:39:58PM -0800, Randy Dunlap wrote:
> On 12/06/2017 01:16 PM, Tobin C. Harding wrote:
> > On Wed, Dec 06, 2017 at 10:18:49AM -0800, Randy Dunlap wrote:
> > 
> > Thanks for your comments Randy.
> > 
> 
> >>>  Documentation/index.rst|  10 +
> >>>  .../{printk-formats.txt => printk-formats.rst} | 295 
> >>> -
> >>>  lib/vsprintf.c | 160 +--
> >>>  3 files changed, 235 insertions(+), 230 deletions(-)
> >>>  rename Documentation/{printk-formats.txt => printk-formats.rst} (61%)
> >>
> >>> diff --git a/Documentation/printk-formats.txt 
> >>> b/Documentation/printk-formats.rst
> >>> similarity index 61%
> >>> rename from Documentation/printk-formats.txt
> >>> rename to Documentation/printk-formats.rst
> >>> index aa0a776c817a..51449d213748 100644
> >>> --- a/Documentation/printk-formats.txt
> >>> +++ b/Documentation/printk-formats.rst
> 
> >>> @@ -194,8 +233,8 @@ printing SSIDs.
> >>>  
> >>>  If field width is omitted the 1 byte only will be escaped.
> >>
> >>  then
> >> I think...
> > 
> > Ha ha, I was borderline with this change when doing this patch. It may
> > not appear so but I did try to do the minimal amount of changes while
> > improving correctness. I appreciate your comments since hopefully I can
> > better make these judgment calls next time.
> 
> I wasn't so sure about that attempt (at minimal changes).  :)

ROFL

> > Will change as suggested.
> 
> >>>  Where no additional specifiers are used the default big endian
> >>> -order with lower case hex characters will be printed.
> >>> +order with lower case hex digits will be printed.
> >>
> >> digits could imply base 10. but no big deal.
> > 
> > Are you sure about this? I was under the impression that when
> > representing a number the character set used are refereed to as 'digits'
> > irrespective of base.
> > 
> > hexadecimal digit
> > octal digit
> > digit (assumed base 10)
> > 
> > Open to correction though.
> 
> Like I said, I don't care strongly about this. (I'm easy.)
> but hex notation (like you said later) sounds good.

Got it.

thanks,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2] doc: convert printk-formats.txt to rst

[Tobin C. Harding]

Documentation/printk-formats.txt is a candidate for conversion to
ReStructuredText format. Some effort has already been made to do this
conversion even thought the suffix is currently .txt

Changes required to complete conversion

 - Move printk-formats.txt to core-api/printk-formats.rst
 - Add entry to Documentation/core-api/index.rst
 - Remove entry from Documentation/00-INDEX

 - Fix minor grammatical errors.
 - Order heading adornments as suggested by rst docs.
 - Use 'Passed by reference' uniformly.
 - Update pointer documentation around %px specifier.
 - Fix erroneous double backticks (to commas).
 - Simplify documentation for kobject.
 - Convert lib/vsnprintf.c function docs to use kernel-docs and
   include in Documentation/printk-formats.rst

Signed-off-by: Tobin C. Harding 
---

v2:
 - Revert to use ASCII table.
 - Implement (or revert) changes as suggested by Randy Dunlap.
 - Change file location to core-api/ (inc required index changes) 
 - Remove some of the double back ticks.

Last two suggested by Jonathan Corbet.


This patch is quite a bit bigger because of removing the extra double
back ticks. It has been already (lightheartedly) observed that I may be
making more changes than necessary. The back ticks stuff may incur the
same reaction :)

 Documentation/00-INDEX |   2 -
 Documentation/core-api/index.rst   |   1 +
 .../printk-formats.rst}| 268 +++--
 lib/vsprintf.c | 155 +---
 4 files changed, 196 insertions(+), 230 deletions(-)
 rename Documentation/{printk-formats.txt => core-api/printk-formats.rst} (59%)

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 3bec49c33bbb..7023bfaec21c 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -346,8 +346,6 @@ prctl/
- directory with info on the priveledge control subsystem
 preempt-locking.txt
- info on locking under a preemptive kernel.
-printk-formats.txt
-   - how to get printk format specifiers right
 process/
- how to work with the mainline kernel development process.
 pps/
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index d5bbe035316d..2f9df634a726 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -21,6 +21,7 @@ Core utilities
flexible-arrays
librs
genalloc
+   printk-formats
 
 Interfaces for kernel debugging
 ===
diff --git a/Documentation/printk-formats.txt 
b/Documentation/core-api/printk-formats.rst
similarity index 59%
rename from Documentation/printk-formats.txt
rename to Documentation/core-api/printk-formats.rst
index aa0a776c817a..f1262a617dec 100644
--- a/Documentation/printk-formats.txt
+++ b/Documentation/core-api/printk-formats.rst
@@ -5,6 +5,7 @@ How to get printk format specifiers right
 :Author: Randy Dunlap 
 :Author: Andrew Murray 
 
+
 Integer types
 =
 
@@ -25,39 +26,49 @@ Integer types
s64 %lld or %llx
u64 %llu or %llx
 
-If  is dependent on a config option for its size (e.g., ``sector_t``,
-``blkcnt_t``) or is architecture-dependent for its size (e.g., ``tcflag_t``),
-use a format specifier of its largest possible type and explicitly cast to it.
+
+If  is dependent on a config option for its size (e.g., sector_t,
+blkcnt_t) or is architecture-dependent for its size (e.g., tcflag_t), use a
+format specifier of its largest possible type and explicitly cast to it.
 
 Example::
 
printk("test: sector number/total blocks: %llu/%llu\n",
(unsigned long long)sector, (unsigned long long)blockcount);
 
-Reminder: ``sizeof()`` result is of type ``size_t``.
+Reminder: sizeof() returns type size_t.
 
-The kernel's printf does not support ``%n``. For obvious reasons, floating
-point formats (``%e, %f, %g, %a``) are also not recognized. Use of any
+The kernel's printf does not support %n. Floating point formats (%e, %f,
+%g, %a) are also not recognized, for obvious reasons. Use of any
 unsupported specifier or length qualifier results in a WARN and early
-return from vsnprintf.
-
-Raw pointer value SHOULD be printed with %p. The kernel supports
-the following extended format specifiers for pointer types:
+return from vsnprintf().
 
-Pointer Types
+Pointer types
 =
 
-Pointers printed without a specifier extension (i.e unadorned %p) are
-hashed to give a unique identifier without leaking kernel addresses to user
-space. On 64 bit machines the first 32 bits are zeroed. If you _really_
-want the address see %px below.
+A raw pointer value may be printed with %p which will hash the address
+before printing. The Kernel also supports extended specifiers for printing
+pointers of different types.
+
+.. kernel-doc:: lib/vsprintf.c
+ :doc: Extended Format Point

Re: [PATCH] docs: add documentation on printing kernel addresses

[Tobin C. Harding]

Please drop this patch, needs amendment (commented inline).

On Thu, Dec 07, 2017 at 11:26:38AM +1100, Tobin C. Harding wrote:
> Hashing addresses printed with printk specifier %p was implemented
> recently. During development a number of issues were raised regarding
> leaking kernel addresses to userspace. We should update the
> documentation appropriately.
> 
> Add documentation regarding printing kernel addresses.
> 
> Signed-off-by: Tobin C. Harding 
> ---
> 
> Is there a proffered method for subscripts in sphinx kernel docs? Here
> we use '[*]' 
> 
> thanks,
> Tobin.
> 
>  Documentation/security/self-protection.rst | 14 ++
>  1 file changed, 14 insertions(+)
> 
> diff --git a/Documentation/security/self-protection.rst 
> b/Documentation/security/self-protection.rst
> index 60c8bd8b77bf..e711280cfdd7 100644
> --- a/Documentation/security/self-protection.rst
> +++ b/Documentation/security/self-protection.rst
> @@ -270,6 +270,20 @@ attacks, it is important to defend against exposure of 
> both kernel memory
>  addresses and kernel memory contents (since they may contain kernel
>  addresses or other sensitive things like canary values).
>  
> +Kernel addresses
> +
> +
> +Printing kernel addresses to userspace leaks sensitive information about
> +the kernel memory layout. Care should be exercised when using any printk
> +specifier that prints the raw address, currently %px, %p[ad], (and %p[sSb]
> +in certain circumstances [*]).  Any file written to using one of these
> +specifiers should be readable only by privileged processes.
> +
> +Kernels 4.14 and older printed the raw address using %p. As of 4.15-rc1
> +addresses printed with the specifier %p are hashed before printing.
> +
> +[*] If symbol lookup fails, the raw address is currently printed.

[*] If KALLSYMS is enabled and symbol lookup fails, the raw address is
currently printed. If KALLSYMS is not enabled the address is printed. 

thanks,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2] doc: convert printk-formats.txt to rst

[Tobin C. Harding]

On Thu, Dec 07, 2017 at 08:44:37AM +0100, Markus Heiser wrote:
> 
> > Am 07.12.2017 um 06:49 schrieb Tobin C. Harding :
> > 
> > Documentation/printk-formats.txt is a candidate for conversion to
> > ReStructuredText format. Some effort has already been made to do this
> > conversion even thought the suffix is currently .txt
> > 
> [...]
> > 
> > Signed-off-by: Tobin C. Harding 
> > ---
> > 
> > v2:
> > - Revert to use ASCII table.
> > - Implement (or revert) changes as suggested by Randy Dunlap.
> > - Change file location to core-api/ (inc required index changes) 
> > - Remove some of the double back ticks.
> > 
> > Last two suggested by Jonathan Corbet.
> > 
> 
> Hm, can't apply v2 on Jon's docs-next .. is the v2 patch on top of your v1?

My mistake, it applies on top of the mainline

commit: "ae64f9bd1d36 Linux 4.15-rc2""

Where is Jon's tree hosted please, I don't see it on kernel.org

thanks,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2] doc: convert printk-formats.txt to rst

[Tobin C. Harding]

On Thu, Dec 07, 2017 at 01:52:56PM -0700, Jonathan Corbet wrote:
> On Fri, 8 Dec 2017 07:44:34 +1100
> "Tobin C. Harding"  wrote:
> 
> > Where is Jon's tree hosted please, I don't see it on kernel.org
> 
> From the MAINTAINERS file:
> 
>   T:  git git://git.lwn.net/linux.git docs-next
> 
> jon

Amateur hour at my house.

thanks Jon,
Tobin
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2] doc: convert printk-formats.txt to rst

[Tobin C. Harding]

On Thu, Dec 07, 2017 at 01:52:56PM -0700, Jonathan Corbet wrote:
> On Fri, 8 Dec 2017 07:44:34 +1100
> "Tobin C. Harding"  wrote:
> 
> > Where is Jon's tree hosted please, I don't see it on kernel.org
> 
> From the MAINTAINERS file:
> 
>   T:  git git://git.lwn.net/linux.git docs-next

Unless I'm a proper wombat that entry is not in the mainline MAINTAINERS
file.

You have two entries

CAFE CMOS INTEGRATED CAMERA CONTROLLER DRIVER
OMNIVISION OV7670 SENSOR DRIVER

but none for docs?

thanks,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2] doc: convert printk-formats.txt to rst

[Tobin C. Harding]

On Thu, Dec 07, 2017 at 01:52:56PM -0700, Jonathan Corbet wrote:
> On Fri, 8 Dec 2017 07:44:34 +1100
> "Tobin C. Harding"  wrote:
> 
> > Where is Jon's tree hosted please, I don't see it on kernel.org
> 
> From the MAINTAINERS file:
> 
>   T:  git git://git.lwn.net/linux.git docs-next

Just in case it is of any use to you Jon

Adding a remote using the above URL

# Jon's docs tree
[remote "corbet"]
url = git://git.lwn.net/linux.git
fetch = +refs/heads/*:refs/remotes/corbet/*
pushurl = no_push


fails to git fetch, but ping showed me

git://git3.lwn.net/linux.git

Using that URL, fetched just fine.

thanks,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2] doc: convert printk-formats.txt to rst

[Tobin C. Harding]

On Thu, Dec 07, 2017 at 08:44:37AM +0100, Markus Heiser wrote:
> 
> > Am 07.12.2017 um 06:49 schrieb Tobin C. Harding :
> > 
> > Documentation/printk-formats.txt is a candidate for conversion to
> > ReStructuredText format. Some effort has already been made to do this
> > conversion even thought the suffix is currently .txt
> > 
> [...]
> > 
> > Signed-off-by: Tobin C. Harding 
> > ---
> > 
> > v2:
> > - Revert to use ASCII table.
> > - Implement (or revert) changes as suggested by Randy Dunlap.
> > - Change file location to core-api/ (inc required index changes) 
> > - Remove some of the double back ticks.
> > 
> > Last two suggested by Jonathan Corbet.
> > 
> 
> Hm, can't apply v2 on Jon's docs-next .. is the v2 patch on top of your v1?

Ok, this doesn't apply because of a commit Linus did to lib/vsprintf.c

Not that that matters because it has been pointed out in another thread
that the kptr_restrict documentation is incomplete.

Please drop, will amend and re-spin.

thanks,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2] doc: convert printk-formats.txt to rst

[Tobin C. Harding]

On Thu, Dec 07, 2017 at 02:30:53PM -0700, Jonathan Corbet wrote:
> On Fri, 8 Dec 2017 08:21:09 +1100
> "Tobin C. Harding"  wrote:
> 
> > Unless I'm a proper wombat that entry is not in the mainline MAINTAINERS
> > file.
> 
> Um...from current git...

Foiled by me automatic Emacs buffer syncing (maggit), who knows what
version of MAINTAINERS I was looking at.

Please accept my apologies.

> DOCUMENTATION
> M:Jonathan Corbet 
> L:linux-doc@vger.kernel.org
> S:Maintained
> F:Documentation/
> F:scripts/kernel-doc
> X:Documentation/ABI/
> X:Documentation/devicetree/
> X:Documentation/acpi
> X:Documentation/power
> X:Documentation/spi
> X:Documentation/media
> T:git git://git.lwn.net/linux.git docs-next
> 
> I've never called anybody a "wombat" before and don't plan to start now,
> but...you might want to take another look?

It's a totally acceptable term in the Australian vernacular, similar to
calling someone a 'goose'. A perfectly pleasant form of abuse :)

thanks,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 1/3] doc: convert printk-formats.txt to rst

[Tobin C. Harding]

Documentation/printk-formats.txt is a candidate for conversion to
ReStructuredText format. Some effort has already been made to do this
conversion even thought the suffix is currently .txt

Changes required to complete conversion

 - Move printk-formats.txt to core-api/printk-formats.rst
 - Add entry to Documentation/core-api/index.rst
 - Remove entry from Documentation/00-INDEX

 - Fix minor grammatical errors.
 - Order heading adornments as suggested by rst docs.
 - Use 'Passed by reference' uniformly.
 - Update pointer documentation around %px specifier.
 - Fix erroneous double backticks (to commas).
 - Simplify documentation for kobject.
 - Convert lib/vsnprintf.c function docs to use kernel-docs and
   include in Documentation/printk-formats.rst

Signed-off-by: Tobin C. Harding 
---
 Documentation/00-INDEX |   2 -
 Documentation/core-api/index.rst   |   1 +
 .../printk-formats.rst}| 268 +++--
 lib/vsprintf.c | 155 +---
 4 files changed, 196 insertions(+), 230 deletions(-)
 rename Documentation/{printk-formats.txt => core-api/printk-formats.rst} (59%)

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 3bec49c33bbb..7023bfaec21c 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -346,8 +346,6 @@ prctl/
- directory with info on the priveledge control subsystem
 preempt-locking.txt
- info on locking under a preemptive kernel.
-printk-formats.txt
-   - how to get printk format specifiers right
 process/
- how to work with the mainline kernel development process.
 pps/
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index d5bbe035316d..2f9df634a726 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -21,6 +21,7 @@ Core utilities
flexible-arrays
librs
genalloc
+   printk-formats
 
 Interfaces for kernel debugging
 ===
diff --git a/Documentation/printk-formats.txt 
b/Documentation/core-api/printk-formats.rst
similarity index 59%
rename from Documentation/printk-formats.txt
rename to Documentation/core-api/printk-formats.rst
index aa0a776c817a..f1262a617dec 100644
--- a/Documentation/printk-formats.txt
+++ b/Documentation/core-api/printk-formats.rst
@@ -5,6 +5,7 @@ How to get printk format specifiers right
 :Author: Randy Dunlap 
 :Author: Andrew Murray 
 
+
 Integer types
 =
 
@@ -25,39 +26,49 @@ Integer types
s64 %lld or %llx
u64 %llu or %llx
 
-If  is dependent on a config option for its size (e.g., ``sector_t``,
-``blkcnt_t``) or is architecture-dependent for its size (e.g., ``tcflag_t``),
-use a format specifier of its largest possible type and explicitly cast to it.
+
+If  is dependent on a config option for its size (e.g., sector_t,
+blkcnt_t) or is architecture-dependent for its size (e.g., tcflag_t), use a
+format specifier of its largest possible type and explicitly cast to it.
 
 Example::
 
printk("test: sector number/total blocks: %llu/%llu\n",
(unsigned long long)sector, (unsigned long long)blockcount);
 
-Reminder: ``sizeof()`` result is of type ``size_t``.
+Reminder: sizeof() returns type size_t.
 
-The kernel's printf does not support ``%n``. For obvious reasons, floating
-point formats (``%e, %f, %g, %a``) are also not recognized. Use of any
+The kernel's printf does not support %n. Floating point formats (%e, %f,
+%g, %a) are also not recognized, for obvious reasons. Use of any
 unsupported specifier or length qualifier results in a WARN and early
-return from vsnprintf.
-
-Raw pointer value SHOULD be printed with %p. The kernel supports
-the following extended format specifiers for pointer types:
+return from vsnprintf().
 
-Pointer Types
+Pointer types
 =
 
-Pointers printed without a specifier extension (i.e unadorned %p) are
-hashed to give a unique identifier without leaking kernel addresses to user
-space. On 64 bit machines the first 32 bits are zeroed. If you _really_
-want the address see %px below.
+A raw pointer value may be printed with %p which will hash the address
+before printing. The Kernel also supports extended specifiers for printing
+pointers of different types.
+
+.. kernel-doc:: lib/vsprintf.c
+ :doc: Extended Format Pointer Specifiers
+
+
+Plain pointers
+--
 
 ::
 
%p  abcdef12 or abcdef12
 
-Symbols/Function Pointers
-=
+Pointers printed without a specifier extension (i.e unadorned %p) are
+hashed to prevent leaking information about the kernel memory layout. This
+has the added benefit of providing a unique identifier. On 64-bit machines
+the first 32 bits are zeroed. If you *really* want the address see %px
+below.
+
+Symbols/Function pointers
+--

[PATCH 3/3] doc: add documentation on printing kernel addresses

[Tobin C. Harding]

Hashing addresses printed with printk specifier %p was implemented
recently. During development a number of issues were raised regarding
leaking kernel addresses to userspace. Other documentation was updated but
security/self-protection missed out.

Add self-protection documentation regarding printing kernel addresses.

Signed-off-by: Tobin C. Harding 
Acked-by: Kees Cook 
---
 Documentation/security/self-protection.rst | 15 +++
 1 file changed, 15 insertions(+)

diff --git a/Documentation/security/self-protection.rst 
b/Documentation/security/self-protection.rst
index 60c8bd8b77bf..392b5660337e 100644
--- a/Documentation/security/self-protection.rst
+++ b/Documentation/security/self-protection.rst
@@ -270,6 +270,21 @@ attacks, it is important to defend against exposure of 
both kernel memory
 addresses and kernel memory contents (since they may contain kernel
 addresses or other sensitive things like canary values).
 
+Kernel addresses
+
+
+Printing kernel addresses to userspace leaks sensitive information about
+the kernel memory layout. Care should be exercised when using any printk
+specifier that prints the raw address, currently %px, %p[ad], (and %p[sSb]
+in certain circumstances [*]).  Any file written to using one of these
+specifiers should be readable only by privileged processes.
+
+Kernels 4.14 and older printed the raw address using %p. As of 4.15-rc1
+addresses printed with the specifier %p are hashed before printing.
+
+[*] If KALLSYMS is enabled and symbol lookup fails, the raw address is
+currently printed. If KALLSYMS is not enabled the address is printed.
+
 Unique identifiers
 --
 
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 0/3] doc: update printk documentation

[Tobin C. Harding]

This set merges two previous patch attempts

[PATCH v2] doc: convert printk-formats.txt to rst
[PATCH] docs: add documentation on printing kernel addresses

And adds patch amending docs for sysctl kptr_restrict

Applies on top of

commit: "ae64f9bd1d36 Linux 4.15-rc2"

(Doesn't apply on top of Jon's docs-next tree (at time of writing at
rc-1) because of commit made to lib/vsprintf.c)

thanks,
Tobin.

Tobin C. Harding (3):
  doc: convert printk-formats.txt to rst
  doc: update kpt_restrict documentation
  doc: add documentation on printing kernel addresses

 Documentation/00-INDEX |   2 -
 Documentation/core-api/index.rst   |   1 +
 .../printk-formats.rst}| 268 +++--
 Documentation/security/self-protection.rst |  15 ++
 Documentation/sysctl/kernel.txt|   3 +-
 lib/vsprintf.c | 155 +---
 6 files changed, 213 insertions(+), 231 deletions(-)
 rename Documentation/{printk-formats.txt => core-api/printk-formats.rst} (59%)

-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 2/3] doc: update kpt_restrict documentation

[Tobin C. Harding]

Recently the behaviour of printk specifier %pK was changed. The
documentation does not currently mirror this.

Update documentation for sysctl kpt_restrict.

Reported-by: Alexander Popov 
Signed-off-by: Tobin C. Harding 
---
 Documentation/sysctl/kernel.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt
index 694968c7523c..1698cd2ef16b 100644
--- a/Documentation/sysctl/kernel.txt
+++ b/Documentation/sysctl/kernel.txt
@@ -377,7 +377,8 @@ kptr_restrict:
 This toggle indicates whether restrictions are placed on
 exposing kernel addresses via /proc and other interfaces.
 
-When kptr_restrict is set to (0), the default, there are no restrictions.
+When kptr_restrict is set to (0), the default, the address is hashed before
+printing. (This is the equivalent to %p.)
 
 When kptr_restrict is set to (1), kernel pointers printed using the %pK
 format specifier will be replaced with 0's unless the user has CAP_SYSLOG
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/3] doc: convert printk-formats.txt to rst

[Tobin C. Harding]

On Fri, Dec 08, 2017 at 09:27:54AM +1100, Tobin C. Harding wrote:
[snip]

New comments have come in from Kees Cook in thread for previous
version. Please drop this set so Kees's suggestions can be implemented.

thanks,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc: convert printk-formats.txt to rst

[Tobin C. Harding]

On Thu, Dec 07, 2017 at 02:50:42PM -0800, Kees Cook wrote:
> On Tue, Dec 5, 2017 at 5:45 PM, Tobin C. Harding  wrote:
> > Documentation/printk-formats.txt is a candidate for conversion to
> > ReStructuredText format. Some effort has already been made to do this
> > conversion even thought the suffix is currently .txt
> >
> > Changes required to complete conversion
> >
> > - Add double backticks where needed.
> > - Add entry to Documentation/index.rst
> > - Use flat-table instead of ASCII table.
> > - Fix minor grammatical errors.
> > - Capitalize headers and correctly order heading adornments.
> > - Use 'Passed by reference' uniformly.
> > - Update pointer documentation around %px specifier.
> > - Fix erroneous double backticks (to commas).
> > - Simplify documentation for kobject.
> > - Convert lib/vsnprintf.c function docs to use kernel-docs and
> >   include in Documentation/printk-formats.rst
> 
> Awesome!

Hi Kees,

I've managed to muddle up the patches for this. New version went in as
part of a larger patch set. As you will no doubt see I've requested that
set to be dropped so I can implement your suggestions.

> >
> > Signed-off-by: Tobin C. Harding 
> > ---
> >
> > The last two need special reviewing please. In particular the conversion
> > of kernel-docs in vsnprintf.c attempt was made to reduce documentation
> > duplication with comments in the source code being simplified in order
> > to be suitable for inclusion in Documentation/printk-formats.rst
> >
> > I used -M when formatting the patch. If you don't like the diff with
> > this flag just holla.
> >
> > thanks,
> > Tobin.
> >
> >  Documentation/index.rst|  10 +
> >  .../{printk-formats.txt => printk-formats.rst} | 295 
> > -
> >  lib/vsprintf.c | 160 +--
> >  3 files changed, 235 insertions(+), 230 deletions(-)
> >  rename Documentation/{printk-formats.txt => printk-formats.rst} (61%)
> >
> > diff --git a/Documentation/index.rst b/Documentation/index.rst
> > index cb7f1ba5b3b1..83ace60efbe7 100644
> > --- a/Documentation/index.rst
> > +++ b/Documentation/index.rst
> > @@ -87,6 +87,16 @@ implementation.
> >
> > sh/index
> >
> > +Miscellaneous documentation
> > +---
> > +
> > +These guides contain general information useful when writing kernel code.
> > +
> > +.. toctree::
> > +   :maxdepth: 1
> > +
> > +   printk-formats
> 
> I actually think this belongs in the kernel core API documentation
> list (Documentation/core-api/index.rst). I defer to Jon's opinion,
> though.

Your right, Jon has told me as such.

> > [...]
> > +.. kernel-doc:: lib/vsprintf.c
> > + :doc: Extended Format Pointer Specifiers
> 
> Awesome!
> 
> > [...]
> > +For printing pointers when you *really* want to print the address. Please
> >  consider whether or not you are leaking sensitive information about the
> > -Kernel layout in memory before printing pointers with %px. %px is
> > -functionally equivalent to %lx. %px is preferred to %lx because it is more
> > -uniquely grep'able. If, in the future, we need to modify the way the Kernel
> > -handles printing pointers it will be nice to be able to find the call
> > -sites.
> > +kernel memory layout before printing pointers with ``%px``. ``%px`` is
> > +functionally equivalent to ``%lx`` (or ``%lu``). ``%px``, however, is
> > +preferable because it is more uniquely grep'able. If, in the future, we 
> > need
> > +to modify the way the Kernel handles printing pointers we will be better
> > +equipped to find the call sites.
> 
> nit? You de-capitalized Kernel at the start but not at the end. "the
> Kernel handles ..."

Yeah, this was intentional. I guess it's wrong. I'm struggling with
capitalization of 'kernel' at the moment. In previous discussion it was
suggested to me that when referring to _the_ Kernel it should be capital
because it implies the Linux Kernel. And when referring to what could be
any kernel it should be lower case. The sticking point, and why I did
this patch as it is, is that I never refer to any other kernels so its
hard to tell when it should be lowercase. On top of this, loads of other
developers just us lowercase all the time.

Grammar is harder than C :)

> > [...]
> > diff --git a/lib/vsprintf.c b/lib/vsprintf.c
> > index 01c3957b2de6..f9247b78e8ef 100644
> > --- a/lib/vsprintf.c
> > +++ b/lib/vs

Re: [PATCH] doc: convert printk-formats.txt to rst

[Tobin C. Harding]

On Thu, Dec 07, 2017 at 04:01:46PM -0700, Jonathan Corbet wrote:
> On Thu, 7 Dec 2017 14:50:42 -0800
> Kees Cook  wrote:
> 
> > > +These guides contain general information useful when writing kernel code.
> > > +
> > > +.. toctree::
> > > +   :maxdepth: 1
> > > +
> > > +   printk-formats  
> > 
> > I actually think this belongs in the kernel core API documentation
> > list (Documentation/core-api/index.rst). I defer to Jon's opinion,
> > though.
> 
> That's my opinion too, and what I had suggested in response to the 
> previous version.  I suspect the pernicious influence of wombats! :)

Steady on! Don't overuse it, you'll hurt my feelings :) Just kidding. I
believe I got this right in the current version. If you are getting
confused trying to follow these patches just try and follow the
discussion my previous effort when hashing %p

I'll let it settle a bit and re-spin after the weekend.

thanks,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc: convert printk-formats.txt to rst

[Tobin C. Harding]

On Thu, Dec 07, 2017 at 04:19:56PM -0800, Kees Cook wrote:
> On Thu, Dec 7, 2017 at 3:44 PM, Tobin C. Harding  wrote:
> > Cheers Kees. FTR, changes to implement are:
> >
> >  - Fix the capitalization of 'kernel'.
> 
> I don't really have an opinion about which way is right. I personally
> don't capitalize it unless I speak about it as a single thing "The
> Linux Kernel". In this case I just noticed you had mixed usage.
> 
> >  - Add ESCAPE_* flags back into kernel-docs in lib/vsprintf.c
> 
> I actually meant each of the sections. Several of the formats have
> per-item breakdowns that went missing in the new kernel-doc (ESCAPE_*
> was just an example).

Oh dear, you don't like that. This is actually the part of the patch
that I was least sure about doing. I'm happy to revert, can I give you
my thought process for comment?

When the kernel-docs get included into printk-formats.rst it seems
overly verbose to have all the information given twice. And then it
seems odd to bother having the extra descriptions in printk-formats.rst
if _all_ the required information is already in the kernel-docs?

So I guessed that it would be nice for devs to get a bit of a hint at
the specifiers when having lib/vsprintf.c open (and they have the code
too) then if they needed more information going to printk-formats.rst.

Also, since there is more space in printk-fomats.rst the info can be
spaced better and easier to read.

Your thoughts?

thanks,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc: convert printk-formats.txt to rst

[Tobin C. Harding]

On Fri, Dec 08, 2017 at 01:22:37PM -0800, Joe Perches wrote:
> On Fri, 2017-12-08 at 13:06 -0800, Kees Cook wrote:
> > Well ... my sense is that lib/vsprintf.c should remain the canonical
> > documentation.
> 
> I agree.
> 
> > Anyone working on the code has the docs all together in
> > one file. If it helps the .rst file to reformat the comments into
> > kernel-doc, that's fine, but it shouldn't reduce the detail that is
> > present, IMO. Now, expanding on it in printk-formats.rst is certainly
> > a great idea, but I don't think it should come at the expense of
> > someone just reading through vsprintf.c. That said, I can certainly
> > see that redundancy is annoying, and it's possible for
> > printk-formats.rst and vsprintf.c get get out of sync, but that
> > doesn't seem to be a new problem.
> 
> Nor has it been a real problem in practice.
> 
> There is a comment in vsprintf.c that tells people
> to update the doc.
> 
>  * ** Please update also Documentation/printk-formats.txt when making changes 
> **
> > 
> > I'd be curious to see what Jon or Joe think about this.
> > 
> > (Perhaps the best first step would be to leave vsprintf.c as-is
> > without kernel-doc-ification?)
> 
> I think adding kernel-doc to vsprintf.c is unnecessary.

Ok, thanks. Will re-spin without kernel-doc-ification in vsprintf.c

> Outside of the documentation, what could be useful is for
> someone to add a tool to verify %p extension to
> the typeof address actually passed as an argument.

This sounds interesting to work no. At first glance I have no idea how
one would go about this. Some form of static analysis would be a good
place to start, right? I'd like to allocate some cycles to this, any
pointers most appreciated.

thanks,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc: convert printk-formats.txt to rst

[Tobin C. Harding]

[Adding Laura]

On Fri, Dec 08, 2017 at 06:18:45PM -0800, Joe Perches wrote:
> On Sat, 2017-12-09 at 12:27 +1100, Tobin C. Harding wrote:
> > On Fri, Dec 08, 2017 at 01:22:37PM -0800, Joe Perches wrote:
> 
> > > Outside of the documentation, what could be useful is for
> > > someone to add a tool to verify %p extension to
> > > the typeof address actually passed as an argument.
> > 
> > This sounds interesting to work no. At first glance I have no idea how
> > one would go about this. Some form of static analysis would be a good
> > place to start, right? I'd like to allocate some cycles to this, any
> > pointers most appreciated.
> 
> A gcc-plugin would likely work best.

What's the learning curve like in your opinion to do a gcc-plugin. I
recall reading someplace 'deep understanding of how the compiler works'
or some such thing. I suppose reading the Dragon book would be a good
place to start?

We could also catch pointers being cast to longs and printed with %x
(and %u) or so I would guess.

> There was some discussion about such a thing here:
> http://www.openwall.com/lists/kernel-hardening/2017/02/14/38

Did you make much progress with this Laura?

> I vaguely recall someone else doing a broader use tool
> which I believe was not smatch, but my google-fu isn't
> finding it.
> 
> It might have been coccinelle based.

thanks,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 0/3] doc: update printk documentation

[Tobin C. Harding]

This set converts printk-formats.txt -> core-api/printk-formats.rst

We also update the documentation around printing kernel addresses.

For v2 I have attempted to toe the line more in regards to 'make as
few changes as possible to complete the conversion'.

This is my first documentation conversion. Please do be hard on this
patch series. I'd like to get it _realy_ correct so that future
conversions will require less review effort. Also if there are any
peculiarities to patching docs (as apposed to C files) please say so.

Thank you for the time already given to reviewing previous versions.

thanks,
Tobin.

v2:
 - Remove conversion/inclusion of kernel-docs from lib/vsprintf.c
 - Add '<>' around file name (in section 'Thanks').
 - Remove a few more double back ticks. 
 - Remove unnecessary [style] edits.

Tobin C. Harding (3):
  doc: convert printk-formats.txt to rst
  doc: update kpt_restrict documentation
  doc: add documentation on printing kernel addresses

 Documentation/00-INDEX |   2 -
 Documentation/core-api/index.rst   |   1 +
 .../printk-formats.rst}| 271 +++--
 Documentation/security/self-protection.rst |  15 ++
 Documentation/sysctl/kernel.txt|   3 +-
 5 files changed, 158 insertions(+), 134 deletions(-)
 rename Documentation/{printk-formats.txt => core-api/printk-formats.rst} (57%)

-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 2/3] doc: update kpt_restrict documentation

[Tobin C. Harding]

Recently the behaviour of printk specifier %pK was changed. The
documentation does not currently mirror this.

Update documentation for sysctl kpt_restrict.

Signed-off-by: Tobin C. Harding 
---
 Documentation/sysctl/kernel.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt
index 63663039acb7..6b039aa1427a 100644
--- a/Documentation/sysctl/kernel.txt
+++ b/Documentation/sysctl/kernel.txt
@@ -391,7 +391,8 @@ kptr_restrict:
 This toggle indicates whether restrictions are placed on
 exposing kernel addresses via /proc and other interfaces.
 
-When kptr_restrict is set to (0), the default, there are no restrictions.
+When kptr_restrict is set to (0), the default, the address is hashed before
+printing. (This is the equivalent to %p.)
 
 When kptr_restrict is set to (1), kernel pointers printed using the %pK
 format specifier will be replaced with 0's unless the user has CAP_SYSLOG
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 1/3] doc: convert printk-formats.txt to rst

[Tobin C. Harding]

Documentation/printk-formats.txt is a candidate for conversion to
ReStructuredText format. Some effort has already been made to do this
conversion even thought the suffix is currently .txt

Changes required to complete conversion

 - Move printk-formats.txt to core-api/printk-formats.rst
 - Add entry to Documentation/core-api/index.rst
 - Remove entry from Documentation/00-INDEX
 - Fix minor grammatical errors.
 - Order heading adornments as suggested by rst docs.
 - Use 'Passed by reference' uniformly.
 - Update pointer documentation around %px specifier.
 - Fix erroneous double backticks (to commas).
 - Simplify documentation for kobject.

Signed-off-by: Tobin C. Harding 
---
 Documentation/00-INDEX |   2 -
 Documentation/core-api/index.rst   |   1 +
 .../printk-formats.rst}| 271 +++--
 3 files changed, 141 insertions(+), 133 deletions(-)
 rename Documentation/{printk-formats.txt => core-api/printk-formats.rst} (57%)

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 3bec49c33bbb..7023bfaec21c 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -346,8 +346,6 @@ prctl/
- directory with info on the priveledge control subsystem
 preempt-locking.txt
- info on locking under a preemptive kernel.
-printk-formats.txt
-   - how to get printk format specifiers right
 process/
- how to work with the mainline kernel development process.
 pps/
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index d4d54b05d6c5..d55ee6b006ed 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -22,6 +22,7 @@ Core utilities
flexible-arrays
librs
genalloc
+   printk-formats
 
 Interfaces for kernel debugging
 ===
diff --git a/Documentation/printk-formats.txt 
b/Documentation/core-api/printk-formats.rst
similarity index 57%
rename from Documentation/printk-formats.txt
rename to Documentation/core-api/printk-formats.rst
index aa0a776c817a..cf266992261e 100644
--- a/Documentation/printk-formats.txt
+++ b/Documentation/core-api/printk-formats.rst
@@ -5,6 +5,7 @@ How to get printk format specifiers right
 :Author: Randy Dunlap 
 :Author: Andrew Murray 
 
+
 Integer types
 =
 
@@ -25,39 +26,45 @@ Integer types
s64 %lld or %llx
u64 %llu or %llx
 
-If  is dependent on a config option for its size (e.g., ``sector_t``,
-``blkcnt_t``) or is architecture-dependent for its size (e.g., ``tcflag_t``),
-use a format specifier of its largest possible type and explicitly cast to it.
+
+If  is dependent on a config option for its size (e.g., sector_t,
+blkcnt_t) or is architecture-dependent for its size (e.g., tcflag_t), use a
+format specifier of its largest possible type and explicitly cast to it.
 
 Example::
 
printk("test: sector number/total blocks: %llu/%llu\n",
(unsigned long long)sector, (unsigned long long)blockcount);
 
-Reminder: ``sizeof()`` result is of type ``size_t``.
+Reminder: sizeof() returns type size_t.
 
-The kernel's printf does not support ``%n``. For obvious reasons, floating
-point formats (``%e, %f, %g, %a``) are also not recognized. Use of any
+The kernel's printf does not support %n. Floating point formats (%e, %f,
+%g, %a) are also not recognized, for obvious reasons. Use of any
 unsupported specifier or length qualifier results in a WARN and early
-return from vsnprintf.
-
-Raw pointer value SHOULD be printed with %p. The kernel supports
-the following extended format specifiers for pointer types:
+return from vsnprintf().
 
-Pointer Types
+Pointer types
 =
 
-Pointers printed without a specifier extension (i.e unadorned %p) are
-hashed to give a unique identifier without leaking kernel addresses to user
-space. On 64 bit machines the first 32 bits are zeroed. If you _really_
-want the address see %px below.
+A raw pointer value may be printed with %p which will hash the address
+before printing. The Kernel also supports extended specifiers for printing
+pointers of different types.
+
+Plain pointers
+--
 
 ::
 
%p  abcdef12 or abcdef12
 
-Symbols/Function Pointers
-=
+Pointers printed without a specifier extension (i.e unadorned %p) are
+hashed to prevent leaking information about the kernel memory layout. This
+has the added benefit of providing a unique identifier. On 64-bit machines
+the first 32 bits are zeroed. If you *really* want the address see %px
+below.
+
+Symbols/Function pointers
+-
 
 ::
 
@@ -69,22 +76,22 @@ Symbols/Function Pointers
%ps versatile_init
%pB prev_fn_of_versatile_init+0x88/0x88
 
-The ``F`` and ``f`` specifiers are for printing function pointers,
-for example, f->func, &gettimeofday.

[PATCH v2 3/3] doc: add documentation on printing kernel addresses

[Tobin C. Harding]

Hashing addresses printed with printk specifier %p was implemented
recently. During development a number of issues were raised regarding
leaking kernel addresses to userspace. Other documentation was updated but
security/self-protection missed out.

Add self-protection documentation regarding printing kernel addresses.

Signed-off-by: Tobin C. Harding 
---
 Documentation/security/self-protection.rst | 15 +++
 1 file changed, 15 insertions(+)

diff --git a/Documentation/security/self-protection.rst 
b/Documentation/security/self-protection.rst
index 60c8bd8b77bf..0f53826c78b9 100644
--- a/Documentation/security/self-protection.rst
+++ b/Documentation/security/self-protection.rst
@@ -270,6 +270,21 @@ attacks, it is important to defend against exposure of 
both kernel memory
 addresses and kernel memory contents (since they may contain kernel
 addresses or other sensitive things like canary values).
 
+Kernel addresses
+
+
+Printing kernel addresses to userspace leaks sensitive information about
+the kernel memory layout. Care should be exercised when using any printk
+specifier that prints the raw address, currently %px, %p[ad], (and %p[sSb]
+in certain circumstances [*]).  Any file written to using one of these
+specifiers should be readable only by privileged processes.
+
+Kernels 4.14 and older printed the raw address using %p. As of 4.15-rc1
+addresses printed with the specifier %p are hashed before printing.
+
+[*] If KALLSYMS is enabled and symbol lookup fails, the raw address is
+printed. If KALLSYMS is not enabled the raw address is printed.
+
 Unique identifiers
 --
 
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 0/3] doc: update printk documentation

[Tobin C. Harding]

On Sun, Dec 17, 2017 at 02:34:25PM -0800, Joe Perches wrote:
> On Mon, 2017-12-18 at 09:30 +1100, Tobin C. Harding wrote:
> > This set converts printk-formats.txt -> core-api/printk-formats.rst
> > 
> > We also update the documentation around printing kernel addresses.
> 
> Please also update the comment in lib/vsprintf.c
> 
>  * ** Please update also Documentation/printk-formats.txt when making changes 
> **
> 
> > I'd like to get it _realy_ correct so that future
> 
> sp: realy->really
> 

Damn emphasis plays havoc with the spell checker. I do believe you have
made this comment before Joe ;) I'll learn to spell one day.

Will fix as suggested and re-spin.

thanks,
Tobin
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v3 0/3] doc: update printk documentation

[Tobin C. Harding]

This set converts printk-formats.txt -> core-api/printk-formats.rst

We also update the documentation around printing kernel addresses.

This is my first documentation conversion. Please do be hard on this
patch series. I'd like to get it _really_ correct so that future
conversions will require less review effort. Also if there are any
peculiarities to patching docs (as apposed to C files) please say so.

Thank you for the time already given to reviewing previous versions.

thanks,
Tobin.

v3:
 - Update filename .txt -> .rst in lib/vsnprintf.c comment (Joe Perches)
 - Remove unnecessary commas (as suggested by Randy Dunlap)
 - Re-apply theory 'make as few changes as possible to complete the
   conversion'

v2:
 - Remove conversion/inclusion of kernel-docs from lib/vsprintf.c
 - Add '<>' around file name (in section 'Thanks').
 - Remove a few more double back ticks. 
 - Apply theory 'make as few changes as possible to complete the
   conversion' 

Tobin C. Harding (3):
  doc: convert printk-formats.txt to rst
  doc: update kpt_restrict documentation
  doc: add documentation on printing kernel addresses

 Documentation/00-INDEX |   2 -
 Documentation/core-api/index.rst   |   1 +
 .../printk-formats.rst}| 229 +++--
 Documentation/security/self-protection.rst |  15 ++
 Documentation/sysctl/kernel.txt|   3 +-
 lib/vsprintf.c |   3 +-
 6 files changed, 139 insertions(+), 114 deletions(-)
 rename Documentation/{printk-formats.txt => core-api/printk-formats.rst} (63%)

-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v3 1/3] doc: convert printk-formats.txt to rst

[Tobin C. Harding]

Documentation/printk-formats.txt is a candidate for conversion to
ReStructuredText format. Some effort has already been made to do this
conversion even thought the suffix is currently .txt

Changes required to complete conversion

 - Move printk-formats.txt to core-api/printk-formats.rst
 - Add entry to Documentation/core-api/index.rst
 - Remove entry from Documentation/00-INDEX
 - Fix minor grammatical errors.
 - Order heading adornments as suggested by rst docs.
 - Use 'Passed by reference' uniformly.
 - Update pointer documentation around %px specifier.
 - Fix erroneous double backticks (to commas).
 - Remove extraneous double backticks (suggested by Jonathan Corbet).
 - Simplify documentation for kobject.

Signed-off-by: Tobin C. Harding 
---
 Documentation/00-INDEX |   2 -
 Documentation/core-api/index.rst   |   1 +
 .../printk-formats.rst}| 229 +++--
 lib/vsprintf.c |   3 +-
 4 files changed, 122 insertions(+), 113 deletions(-)
 rename Documentation/{printk-formats.txt => core-api/printk-formats.rst} (63%)

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 3bec49c33bbb..7023bfaec21c 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -346,8 +346,6 @@ prctl/
- directory with info on the priveledge control subsystem
 preempt-locking.txt
- info on locking under a preemptive kernel.
-printk-formats.txt
-   - how to get printk format specifiers right
 process/
- how to work with the mainline kernel development process.
 pps/
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index d4d54b05d6c5..d55ee6b006ed 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -22,6 +22,7 @@ Core utilities
flexible-arrays
librs
genalloc
+   printk-formats
 
 Interfaces for kernel debugging
 ===
diff --git a/Documentation/printk-formats.txt 
b/Documentation/core-api/printk-formats.rst
similarity index 63%
rename from Documentation/printk-formats.txt
rename to Documentation/core-api/printk-formats.rst
index aa0a776c817a..2c542e30b13b 100644
--- a/Documentation/printk-formats.txt
+++ b/Documentation/core-api/printk-formats.rst
@@ -5,6 +5,7 @@ How to get printk format specifiers right
 :Author: Randy Dunlap 
 :Author: Andrew Murray 
 
+
 Integer types
 =
 
@@ -25,39 +26,45 @@ Integer types
s64 %lld or %llx
u64 %llu or %llx
 
-If  is dependent on a config option for its size (e.g., ``sector_t``,
-``blkcnt_t``) or is architecture-dependent for its size (e.g., ``tcflag_t``),
-use a format specifier of its largest possible type and explicitly cast to it.
+
+If  is dependent on a config option for its size (e.g., sector_t,
+blkcnt_t) or is architecture-dependent for its size (e.g., tcflag_t), use a
+format specifier of its largest possible type and explicitly cast to it.
 
 Example::
 
printk("test: sector number/total blocks: %llu/%llu\n",
(unsigned long long)sector, (unsigned long long)blockcount);
 
-Reminder: ``sizeof()`` result is of type ``size_t``.
+Reminder: sizeof() returns type size_t.
 
-The kernel's printf does not support ``%n``. For obvious reasons, floating
-point formats (``%e, %f, %g, %a``) are also not recognized. Use of any
+The Kernel's printf does not support %n. Floating point formats (%e, %f,
+%g, %a) are also not recognized, for obvious reasons. Use of any
 unsupported specifier or length qualifier results in a WARN and early
-return from vsnprintf.
-
-Raw pointer value SHOULD be printed with %p. The kernel supports
-the following extended format specifiers for pointer types:
+return from vsnprintf().
 
-Pointer Types
+Pointer types
 =
 
-Pointers printed without a specifier extension (i.e unadorned %p) are
-hashed to give a unique identifier without leaking kernel addresses to user
-space. On 64 bit machines the first 32 bits are zeroed. If you _really_
-want the address see %px below.
+A raw pointer value may be printed with %p which will hash the address
+before printing. The Kernel also supports extended specifiers for printing
+pointers of different types.
+
+Plain Pointers
+--
 
 ::
 
%p  abcdef12 or abcdef12
 
+Pointers printed without a specifier extension (i.e unadorned %p) are
+hashed to prevent leaking information about the Kernel memory layout. This
+has the added benefit of providing a unique identifier. On 64-bit machines
+the first 32 bits are zeroed. If you *really* want the address see %px
+below.
+
 Symbols/Function Pointers
-=
+-
 
 ::
 
@@ -69,6 +76,7 @@ Symbols/Function Pointers
%ps versatile_init
%pB prev_fn_of_versatile_init+0x88/0x88
 
+
 The `

[PATCH v3 3/3] doc: add documentation on printing kernel addresses

[Tobin C. Harding]

Hashing addresses printed with printk specifier %p was implemented
recently. During development a number of issues were raised regarding
leaking kernel addresses to userspace. Other documentation was updated but
security/self-protection missed out.

Add self-protection documentation regarding printing kernel addresses.

Signed-off-by: Tobin C. Harding 
---
 Documentation/security/self-protection.rst | 15 +++
 1 file changed, 15 insertions(+)

diff --git a/Documentation/security/self-protection.rst 
b/Documentation/security/self-protection.rst
index 60c8bd8b77bf..0f53826c78b9 100644
--- a/Documentation/security/self-protection.rst
+++ b/Documentation/security/self-protection.rst
@@ -270,6 +270,21 @@ attacks, it is important to defend against exposure of 
both kernel memory
 addresses and kernel memory contents (since they may contain kernel
 addresses or other sensitive things like canary values).
 
+Kernel addresses
+
+
+Printing kernel addresses to userspace leaks sensitive information about
+the kernel memory layout. Care should be exercised when using any printk
+specifier that prints the raw address, currently %px, %p[ad], (and %p[sSb]
+in certain circumstances [*]).  Any file written to using one of these
+specifiers should be readable only by privileged processes.
+
+Kernels 4.14 and older printed the raw address using %p. As of 4.15-rc1
+addresses printed with the specifier %p are hashed before printing.
+
+[*] If KALLSYMS is enabled and symbol lookup fails, the raw address is
+printed. If KALLSYMS is not enabled the raw address is printed.
+
 Unique identifiers
 --
 
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v3 2/3] doc: update kpt_restrict documentation

[Tobin C. Harding]

Recently the behaviour of printk specifier %pK was changed. The
documentation does not currently mirror this.

Update documentation for sysctl kpt_restrict.

Signed-off-by: Tobin C. Harding 
---
 Documentation/sysctl/kernel.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt
index 63663039acb7..412314eebda6 100644
--- a/Documentation/sysctl/kernel.txt
+++ b/Documentation/sysctl/kernel.txt
@@ -391,7 +391,8 @@ kptr_restrict:
 This toggle indicates whether restrictions are placed on
 exposing kernel addresses via /proc and other interfaces.
 
-When kptr_restrict is set to (0), the default, there are no restrictions.
+When kptr_restrict is set to 0 (the default) the address is hashed before
+printing. (This is the equivalent to %p.)
 
 When kptr_restrict is set to (1), kernel pointers printed using the %pK
 format specifier will be replaced with 0's unless the user has CAP_SYSLOG
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3 2/3] doc: update kpt_restrict documentation

[Tobin C. Harding]

On Mon, Dec 18, 2017 at 03:50:06PM -0800, Randy Dunlap wrote:
> On 12/18/2017 02:29 PM, Tobin C. Harding wrote:
> > Recently the behaviour of printk specifier %pK was changed. The
> > documentation does not currently mirror this.
> > 
> > Update documentation for sysctl kpt_restrict.
> 
> Fix subject and here  .

Oh thanks. Took quite a few minutes of staring to see the mistake ;)

Will fix and re-spin.

thanks,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v4 0/3] doc: update printk documentation

[Tobin C. Harding]

This set converts printk-formats.txt -> core-api/printk-formats.rst

We also update the documentation around printing kernel addresses.

This is my first documentation conversion. Please do be hard on this
patch series. I'd like to get it _really_ correct so that future
conversions will require less review effort. Also if there are any
peculiarities to patching docs (as apposed to C files) please say so.

Thank you for the time already given to reviewing previous versions.

thanks,
Tobin.

v4:
 - fix typo 'kpt_restrict' -> 'kptr_restrict' (thanks Randy).

v3:
 - Update filename .txt -> .rst in lib/vsnprintf.c comment (Joe Perches)
 - Remove unnecessary commas (as suggested by Randy Dunlap)
 - Re-apply theory 'make as few changes as possible to complete the
   conversion'

v2:
 - Remove conversion/inclusion of kernel-docs from lib/vsprintf.c
 - Add '<>' around file name (in section 'Thanks').
 - Remove a few more double back ticks.
 - Apply theory 'make as few changes as possible to complete the
   conversion'

Tobin C. Harding (3):
  doc: convert printk-formats.txt to rst
  doc: update kptr_restrict documentation
  doc: add documentation on printing kernel addresses

 Documentation/00-INDEX |   2 -
 Documentation/core-api/index.rst   |   1 +
 .../printk-formats.rst}| 229 +++--
 Documentation/security/self-protection.rst |  15 ++
 Documentation/sysctl/kernel.txt|   3 +-
 lib/vsprintf.c |   3 +-
 6 files changed, 139 insertions(+), 114 deletions(-)
 rename Documentation/{printk-formats.txt => core-api/printk-formats.rst} (63%)

-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v4 2/3] doc: update kptr_restrict documentation

[Tobin C. Harding]

Recently the behaviour of printk specifier %pK was changed. The
documentation does not currently mirror this.

Update documentation for sysctl kptr_restrict.

Signed-off-by: Tobin C. Harding 
---
 Documentation/sysctl/kernel.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt
index 63663039acb7..412314eebda6 100644
--- a/Documentation/sysctl/kernel.txt
+++ b/Documentation/sysctl/kernel.txt
@@ -391,7 +391,8 @@ kptr_restrict:
 This toggle indicates whether restrictions are placed on
 exposing kernel addresses via /proc and other interfaces.
 
-When kptr_restrict is set to (0), the default, there are no restrictions.
+When kptr_restrict is set to 0 (the default) the address is hashed before
+printing. (This is the equivalent to %p.)
 
 When kptr_restrict is set to (1), kernel pointers printed using the %pK
 format specifier will be replaced with 0's unless the user has CAP_SYSLOG
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v4 3/3] doc: add documentation on printing kernel addresses

[Tobin C. Harding]

Hashing addresses printed with printk specifier %p was implemented
recently. During development a number of issues were raised regarding
leaking kernel addresses to userspace. Other documentation was updated but
security/self-protection missed out.

Add self-protection documentation regarding printing kernel addresses.

Signed-off-by: Tobin C. Harding 
---
 Documentation/security/self-protection.rst | 15 +++
 1 file changed, 15 insertions(+)

diff --git a/Documentation/security/self-protection.rst 
b/Documentation/security/self-protection.rst
index 60c8bd8b77bf..0f53826c78b9 100644
--- a/Documentation/security/self-protection.rst
+++ b/Documentation/security/self-protection.rst
@@ -270,6 +270,21 @@ attacks, it is important to defend against exposure of 
both kernel memory
 addresses and kernel memory contents (since they may contain kernel
 addresses or other sensitive things like canary values).
 
+Kernel addresses
+
+
+Printing kernel addresses to userspace leaks sensitive information about
+the kernel memory layout. Care should be exercised when using any printk
+specifier that prints the raw address, currently %px, %p[ad], (and %p[sSb]
+in certain circumstances [*]).  Any file written to using one of these
+specifiers should be readable only by privileged processes.
+
+Kernels 4.14 and older printed the raw address using %p. As of 4.15-rc1
+addresses printed with the specifier %p are hashed before printing.
+
+[*] If KALLSYMS is enabled and symbol lookup fails, the raw address is
+printed. If KALLSYMS is not enabled the raw address is printed.
+
 Unique identifiers
 --
 
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v4 1/3] doc: convert printk-formats.txt to rst

[Tobin C. Harding]

Documentation/printk-formats.txt is a candidate for conversion to
ReStructuredText format. Some effort has already been made to do this
conversion even thought the suffix is currently .txt

Changes required to complete conversion

 - Move printk-formats.txt to core-api/printk-formats.rst
 - Add entry to Documentation/core-api/index.rst
 - Remove entry from Documentation/00-INDEX
 - Fix minor grammatical errors.
 - Order heading adornments as suggested by rst docs.
 - Use 'Passed by reference' uniformly.
 - Update pointer documentation around %px specifier.
 - Fix erroneous double backticks (to commas).
 - Remove extraneous double backticks (suggested by Jonathan Corbet).
 - Simplify documentation for kobject.

Signed-off-by: Tobin C. Harding 
---
 Documentation/00-INDEX |   2 -
 Documentation/core-api/index.rst   |   1 +
 .../printk-formats.rst}| 229 +++--
 lib/vsprintf.c |   3 +-
 4 files changed, 122 insertions(+), 113 deletions(-)
 rename Documentation/{printk-formats.txt => core-api/printk-formats.rst} (63%)

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 3bec49c33bbb..7023bfaec21c 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -346,8 +346,6 @@ prctl/
- directory with info on the priveledge control subsystem
 preempt-locking.txt
- info on locking under a preemptive kernel.
-printk-formats.txt
-   - how to get printk format specifiers right
 process/
- how to work with the mainline kernel development process.
 pps/
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index d4d54b05d6c5..d55ee6b006ed 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -22,6 +22,7 @@ Core utilities
flexible-arrays
librs
genalloc
+   printk-formats
 
 Interfaces for kernel debugging
 ===
diff --git a/Documentation/printk-formats.txt 
b/Documentation/core-api/printk-formats.rst
similarity index 63%
rename from Documentation/printk-formats.txt
rename to Documentation/core-api/printk-formats.rst
index aa0a776c817a..2c542e30b13b 100644
--- a/Documentation/printk-formats.txt
+++ b/Documentation/core-api/printk-formats.rst
@@ -5,6 +5,7 @@ How to get printk format specifiers right
 :Author: Randy Dunlap 
 :Author: Andrew Murray 
 
+
 Integer types
 =
 
@@ -25,39 +26,45 @@ Integer types
s64 %lld or %llx
u64 %llu or %llx
 
-If  is dependent on a config option for its size (e.g., ``sector_t``,
-``blkcnt_t``) or is architecture-dependent for its size (e.g., ``tcflag_t``),
-use a format specifier of its largest possible type and explicitly cast to it.
+
+If  is dependent on a config option for its size (e.g., sector_t,
+blkcnt_t) or is architecture-dependent for its size (e.g., tcflag_t), use a
+format specifier of its largest possible type and explicitly cast to it.
 
 Example::
 
printk("test: sector number/total blocks: %llu/%llu\n",
(unsigned long long)sector, (unsigned long long)blockcount);
 
-Reminder: ``sizeof()`` result is of type ``size_t``.
+Reminder: sizeof() returns type size_t.
 
-The kernel's printf does not support ``%n``. For obvious reasons, floating
-point formats (``%e, %f, %g, %a``) are also not recognized. Use of any
+The Kernel's printf does not support %n. Floating point formats (%e, %f,
+%g, %a) are also not recognized, for obvious reasons. Use of any
 unsupported specifier or length qualifier results in a WARN and early
-return from vsnprintf.
-
-Raw pointer value SHOULD be printed with %p. The kernel supports
-the following extended format specifiers for pointer types:
+return from vsnprintf().
 
-Pointer Types
+Pointer types
 =
 
-Pointers printed without a specifier extension (i.e unadorned %p) are
-hashed to give a unique identifier without leaking kernel addresses to user
-space. On 64 bit machines the first 32 bits are zeroed. If you _really_
-want the address see %px below.
+A raw pointer value may be printed with %p which will hash the address
+before printing. The Kernel also supports extended specifiers for printing
+pointers of different types.
+
+Plain Pointers
+--
 
 ::
 
%p  abcdef12 or abcdef12
 
+Pointers printed without a specifier extension (i.e unadorned %p) are
+hashed to prevent leaking information about the Kernel memory layout. This
+has the added benefit of providing a unique identifier. On 64-bit machines
+the first 32 bits are zeroed. If you *really* want the address see %px
+below.
+
 Symbols/Function Pointers
-=
+-
 
 ::
 
@@ -69,6 +76,7 @@ Symbols/Function Pointers
%ps versatile_init
%pB prev_fn_of_versatile_init+0x88/0x88
 
+
 The `

Maintainer docs for patch merging

[Tobin C. Harding]

Hi,

Recently we started a maintainer book (merged into Jonathan's docs-next
branch).

Would any current maintainers please be willing to explain how they go
about generating the automated emails one often receives when a patch
[set] is applied.

This may also be related to tree/branch management for maintainers
kernel.org shows some people like to use multiple trees and some use
branches? 

If deemed relevant we could add a section to the new book (and I'd also
like to know how to do it for my own tree please so I can copy ;)

I have CC'd Greg and Andrew because they seem to have a system in place
for this.

No rush on this, I know Christmas is soon.

thanks,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Maintainer docs for patch merging

[Tobin C. Harding]

On Wed, Dec 20, 2017 at 08:56:03AM +0100, Greg Kroah-Hartman wrote:
> On Wed, Dec 20, 2017 at 11:25:41AM +1100, Tobin C. Harding wrote:
> > Hi,
> > 
> > Recently we started a maintainer book (merged into Jonathan's docs-next
> > branch).
> > 
> > Would any current maintainers please be willing to explain how they go
> > about generating the automated emails one often receives when a patch
> > [set] is applied.
> > 
> > This may also be related to tree/branch management for maintainers
> > kernel.org shows some people like to use multiple trees and some use
> > branches? 
> > 
> > If deemed relevant we could add a section to the new book (and I'd also
> > like to know how to do it for my own tree please so I can copy ;)
> > 
> > I have CC'd Greg and Andrew because they seem to have a system in place
> > for this.
> 
> I "stole" Andrew's scripts for this a long time ago.  I guess I can
> write up something "real" for the documentation so that others can see
> the shell mess that drives those emails :)
> 
> > No rush on this, I know Christmas is soon.
> 
> Yeah, this will have to wait until mid January at the earliest...

Cool, thanks. Don't stress, I can give you a friendly reminder after LCA
(end of Jan) if you like save you wasting memory on it.

thanks,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v4 0/3] doc: update printk documentation

[Tobin C. Harding]

On Thu, Dec 21, 2017 at 11:26:22AM -0800, Randy Dunlap wrote:
> On 12/21/2017 11:21 AM, Jonathan Corbet wrote:
> > On Wed, 20 Dec 2017 08:17:14 +1100
> > "Tobin C. Harding"  wrote:
> > 
> >> This set converts printk-formats.txt -> core-api/printk-formats.rst
> >>
> >> We also update the documentation around printing kernel addresses.
> >>
> >> This is my first documentation conversion. Please do be hard on this
> >> patch series. I'd like to get it _really_ correct so that future
> >> conversions will require less review effort. Also if there are any
> >> peculiarities to patching docs (as apposed to C files) please say so.
> >>
> >> Thank you for the time already given to reviewing previous versions.
> > 
> > So I spent a while thinking hard about how I could make Tobin do another
> > round or two on these patches.  But then I figure that it's the holidays,
> > and I should just apply them.  So that's done.  Thanks for all of your
> > work on this!
> > 
> > That said...
> > 
> >  - I don't quite understand why you capitalize "kernel" everywhere.  I
> >vaguely recall some sort of discussion on that.  To me it looks
> >strange...oh well.
> 
> Mauro explained that he capitalizes Kernel when it is being used as a
> shortened version of "the Linux kernel," i.e., as a proper name,
> so I think that Tobin appropriated that style.
> 
> It would be OK to undo that IMO.

I'm happy to write it however, if everyone is happy with 'kernel'
everywhere then that is good (and easier). I think Mauro is correct but
I also think Jon is correct, it does look funny. Code language doesn't
always follow English grammar rules after all.

thanks,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v4 0/3] doc: update printk documentation

[Tobin C. Harding]

On Thu, Dec 21, 2017 at 12:21:41PM -0700, Jonathan Corbet wrote:
> On Wed, 20 Dec 2017 08:17:14 +1100
> "Tobin C. Harding"  wrote:
> 
> > This set converts printk-formats.txt -> core-api/printk-formats.rst
> > 
> > We also update the documentation around printing kernel addresses.
> > 
> > This is my first documentation conversion. Please do be hard on this
> > patch series. I'd like to get it _really_ correct so that future
> > conversions will require less review effort. Also if there are any
> > peculiarities to patching docs (as apposed to C files) please say so.
> > 
> > Thank you for the time already given to reviewing previous versions.
> 
> So I spent a while thinking hard about how I could make Tobin do another
> round or two on these patches.  But then I figure that it's the holidays,
> and I should just apply them.  So that's done.  Thanks for all of your
> work on this!

Oh ok, I would have been happy to drag it over the holiday period and
get it super correct. I'm always chasing perfection (even if seemingly a
long way from it ;) so please never feel you have to rush things
through. I'm happy to learn how to do it correctly and that will save
everyone time in the future.

> That said...

I am happy also to patch on top of what was applied after Christmas
break :) I don't want to create any extra work for anyone else.

>  - I don't quite understand why you capitalize "kernel" everywhere.  I
>vaguely recall some sort of discussion on that.  To me it looks
>strange...oh well.

Ok, I'm going to go with 'kernel' everywhere from now on. Despite having
two degrees I am particularly crap at English [grammar]. Please do pick
me up on any mistakes no matter how trivial. That is the only way to
learn IMO.

>  - There's a dangling reference to printk-formats.txt in lib/vsprintf.c
>that we'll want to fix up.

Bad Tobin, no biscuit.

>  - The vsprintf kerneldoc currently gets pulled into the big "kernel API"
>dumpster.  Someday, it would be nice to turn printk-formats.rst into a
>"how to output data from the kernel" section, with documentation on
>vnsprintf, printk, trace_printk, and format strings all in one place.
>What a fine day that would be...

I don't quite understand this yet. (I added to my kernel list of things
to learn and work on ;)

thanks Jon. Merry Christmas,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] docs: add index entry for networking/msg_zerocopy

[Tobin C. Harding]

Currently msg_zerocopy is not included in any toctree. Sphinx emits a
build warning to this effect. The other three rst files in
Documentation/networking are all indexed. We can add msg_zerocopy to the
toctree to enable navigation of the document via HTML kernel docs.

Add msg_zerocopy to the networking/ toctree.

Signed-off-by: Tobin C. Harding 
---
 Documentation/networking/index.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/networking/index.rst 
b/Documentation/networking/index.rst
index 66e620866245..19e8a927d79b 100644
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -9,6 +9,7 @@ Contents:
batman-adv
kapi
z8530book
+   msg_zerocopy
 
 .. only::  subproject
 
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

docs tree

[Tobin C. Harding]

Hi Jon,

Has the docs tree moved?  I haven't fetched it lately and this morning I
get:

$ git fetch corbet
fatal: unable to connect to git3.lwn.net:
git3.lwn.net[0: 45.79.184.34]: errno=Connection refused

All my other trees fetch ok.  Relevant .git/config entry is:

[remote "corbet"]
url = git://git3.lwn.net/linux.git
fetch = +refs/heads/*:refs/remotes/corbet/*
pushurl = no_push


thanks,
Tobin.

Re: docs tree

[Tobin C. Harding]

On Thu, Jan 31, 2019, at 12:37, Randy Dunlap wrote:
> On 1/30/19 5:25 PM, Tobin C. Harding wrote:
> > Hi Jon,
> > 
> > Has the docs tree moved?  I haven't fetched it lately and this morning I
> > get:
> > 
> > $ git fetch corbet
> > fatal: unable to connect to git3.lwn.net:
> > git3.lwn.net[0: 45.79.184.34]: errno=Connection refused
> > 
> > All my other trees fetch ok.  Relevant .git/config entry is:
> > 
> > [remote "corbet"]
> > url = git://git3.lwn.net/linux.git
> > fetch = +refs/heads/*:refs/remotes/corbet/*
> > pushurl = no_push
> > 
> > 
> > thanks,
> > Tobin.
> 
> 
> Hi Tobin,
> 
> The MAINTAINERS file says:
> T:git git://git.lwn.net/linux.git docs-next

Ouch, failing in public is fun.  Thanks Randy

[PATCH 1/3] docs: Fix SLUB docs typo

[Tobin C. Harding]

From: "Tobin C. Harding" 

There is a minor typo in SLUB documentation.

Fix typo.

Signed-off-by: Tobin C. Harding 
---
 Documentation/vm/slub.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/vm/slub.rst b/Documentation/vm/slub.rst
index 195928808..0871c5849 100644
--- a/Documentation/vm/slub.rst
+++ b/Documentation/vm/slub.rst
@@ -141,7 +141,7 @@ can be influenced by kernel parameters:
(list_lock) where contention may occur.
 
 ``slub_min_order``
-   specifies a minim order of slabs. A similar effect like
+   specifies a minimum order of slabs. A similar effect like
``slub_min_objects``.
 
 ``slub_max_order``
-- 
2.20.1

[PATCH 0/3] docs: vm: Fix typo and build warnings

[Tobin C. Harding]

From: "Tobin C. Harding" 

Hi Jon,

This patchset started as a spelling typo fix to the SLUB docs, while
doing this I noticed a few build warnings for vm/ so build warning fixes
make up the rest of the set.

Patch 3 uses an underscore instead of a hyphen in the label name.  This
clears the warning but I am not 100% sure this is the correct fix.

thanks,
Tobin.


Tobin C. Harding (3):
  docs: Fix SLUB docs typo
  docs: Add missing colon
  docs: Use underscore not hyphen in label

 Documentation/core-api/memory-allocation.rst | 2 +-
 Documentation/vm/index.rst   | 2 +-
 Documentation/vm/slub.rst| 4 ++--
 3 files changed, 4 insertions(+), 4 deletions(-)

-- 
2.20.1

[PATCH 2/3] docs: Add missing colon

[Tobin C. Harding]

From: "Tobin C. Harding" 

sphinx emits warning

   WARNING: Inline emphasis start-string without end-string.

This is caused by a missing colon.

Add missing colon, clearing shpinx build warning.

Signed-off-by: Tobin C. Harding 
---
 Documentation/vm/slub.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/vm/slub.rst b/Documentation/vm/slub.rst
index 0871c5849..933ada436 100644
--- a/Documentation/vm/slub.rst
+++ b/Documentation/vm/slub.rst
@@ -66,7 +66,7 @@ Trying to find an issue in the dentry cache? Try::
 to only enable debugging on the dentry cache.  You may use an asterisk at the
 end of the slab name, in order to cover all slabs with the same prefix.  For
 example, here's how you can poison the dentry cache as well as all kmalloc
-slabs:
+slabs::
 
slub_debug=P,kmalloc-*,dentry
 
-- 
2.20.1

[PATCH 3/3] docs: Use underscore not hyphen in label

[Tobin C. Harding]

From: "Tobin C. Harding" 

sphinx emits warning

   WARNING: undefined label: memory-allocation ...

This seems to be caused by the use of a hyphen in the label name instead
of an underscore.  Using an underscore for the label name and the
reference clears the warning.

Use underscore not hyphen in label and reference.

Signed-off-by: Tobin C. Harding 
---

Not 100% sure this is the correct fix, please review.

thanks

 Documentation/core-api/memory-allocation.rst | 2 +-
 Documentation/vm/index.rst   | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/core-api/memory-allocation.rst 
b/Documentation/core-api/memory-allocation.rst
index 8954a88ff..39f35ebdc 100644
--- a/Documentation/core-api/memory-allocation.rst
+++ b/Documentation/core-api/memory-allocation.rst
@@ -1,4 +1,4 @@
-.. _memory-allocation:
+.. _memory_allocation:
 
 ===
 Memory Allocation Guide
diff --git a/Documentation/vm/index.rst b/Documentation/vm/index.rst
index 2b3ab3a1c..b58cc3bfe 100644
--- a/Documentation/vm/index.rst
+++ b/Documentation/vm/index.rst
@@ -4,7 +4,7 @@ Linux Memory Management Documentation
 
 This is a collection of documents about the Linux memory management (mm)
 subsystem.  If you are looking for advice on simply allocating memory,
-see the :ref:`memory-allocation`.
+see the :ref:`memory_allocation`.
 
 User guides for MM features
 ===
-- 
2.20.1

Re: [PATCH 3/3] docs: Use underscore not hyphen in label

[Tobin C. Harding]

On Thu, Jan 31, 2019 at 11:27:57AM +0200, Mike Rapoport wrote:
> On Thu, Jan 31, 2019 at 03:06:23PM +1100, Tobin C. Harding wrote:
> > From: "Tobin C. Harding" 
> > 
> > sphinx emits warning
> > 
> >WARNING: undefined label: memory-allocation ...
> 
> Weird, for me it works fine. The generated html at kernel.org [1] also
> seems to be Ok...
> 
> What version of sphinx do you use?

Thanks for looking at this Mike.  I was running 1.4, I see there is a v2
out so I'll upgrade but if the warning doesn't show for you then I'd say
we just drop this patch.

Jon,

Is it within your usual workflow to take just the first two patches from
this series or would you like me to spin another version without the
final patch in it?


thanks,
Tobin.

Re: docs tree

[Tobin C. Harding]

On Fri, Feb 1, 2019, at 14:41, Jonathan Corbet wrote:
> On Wed, 30 Jan 2019 21:16:21 -0500
> "Tobin C. Harding"  wrote:
> 
> > Ouch, failing in public is fun.  Thanks Randy
> 
> That's how kernel development is done in the end...:)

It is actually one of the things I like about it.  Keeps one honest and humble.

> I'd be curious to know how you got the git3.lwn.net name in your remote,
> though, if by any chance you can remember.  That shouldn't have leaked
> out anywhere...

I don't remember how I got that remote set up, it worked at some stage because 
I fetched your tree when I set it up. git complained yesterday when I tried 
though.  Also I cannot remember the last time I successfully fetched from that 
remote.  If I ever see it again I'll email you.

thanks,
Tobin.

Re: [PATCH 3/3] docs: Use underscore not hyphen in label

[Tobin C. Harding]

On Sat, Feb 02, 2019 at 04:32:10PM +0200, Mike Rapoport wrote:
> On Fri, Feb 01, 2019 at 04:03:10PM -0700, Jonathan Corbet wrote:
> > On Fri, 1 Feb 2019 07:56:08 +1100
> > "Tobin C. Harding"  wrote:
> > 
> > > > > From: "Tobin C. Harding" 
> > > > > 
> > > > > sphinx emits warning
> > > > > 
> > > > >WARNING: undefined label: memory-allocation ...  
> > > > 
> > > > Weird, for me it works fine. The generated html at kernel.org [1] also
> > > > seems to be Ok...
> > > > 
> > > > What version of sphinx do you use?  
> > > 
> > > Thanks for looking at this Mike.  I was running 1.4, I see there is a v2
> > > out so I'll upgrade but if the warning doesn't show for you then I'd say
> > > we just drop this patch.
> > > 
> > > Jon,
> > > 
> > > Is it within your usual workflow to take just the first two patches from
> > > this series or would you like me to spin another version without the
> > > final patch in it?
> > 
> > We currently document that 1.4 is supposed to work, so we should stick to
> > that; I think I'll go ahead and apply all three patches.
> >
> > We should maybe consider dragging our minimum version forward a bit, or
> > else we might want to document this particular gotcha.
> 
> I have 1.4.6 (the one listed in sphinx.rst) and everything worked just
> fine...

FWIW I'm running 1.4.9


thanks,
Tobin.

Re: [PATCH 3/3] docs: Use underscore not hyphen in label

[Tobin C. Harding]

On Sat, Feb 02, 2019 at 04:32:10PM +0200, Mike Rapoport wrote:
> On Fri, Feb 01, 2019 at 04:03:10PM -0700, Jonathan Corbet wrote:
> > On Fri, 1 Feb 2019 07:56:08 +1100
> > "Tobin C. Harding"  wrote:
> > 
> > > > > From: "Tobin C. Harding" 
> > > > > 
> > > > > sphinx emits warning
> > > > > 
> > > > >WARNING: undefined label: memory-allocation ...  
> > > > 
> > > > Weird, for me it works fine. The generated html at kernel.org [1] also
> > > > seems to be Ok...
> > > > 
> > > > What version of sphinx do you use?  
> > > 
> > > Thanks for looking at this Mike.  I was running 1.4, I see there is a v2
> > > out so I'll upgrade but if the warning doesn't show for you then I'd say
> > > we just drop this patch.
> > > 
> > > Jon,
> > > 
> > > Is it within your usual workflow to take just the first two patches from
> > > this series or would you like me to spin another version without the
> > > final patch in it?
> > 
> > We currently document that 1.4 is supposed to work, so we should stick to
> > that; I think I'll go ahead and apply all three patches.
> >
> > We should maybe consider dragging our minimum version forward a bit, or
> > else we might want to document this particular gotcha.
> 
> I have 1.4.6 (the one listed in sphinx.rst) and everything worked just
> fine...

I tried to investigate this further and I am unable to reproduce the
original warning.  I'm using python virtual environment as directed by
the output of `make htmldocs` so the environment should not have
changed.  The only other plausible explanation seems to be that I've
gone mad and can't remember what I was doing three days ago.

Thanks for your patience.


Tobin.

Re: [PATCH 3/3] docs: Use underscore not hyphen in label

[Tobin C. Harding]

On Tue, Feb 05, 2019 at 09:30:46AM +0100, Markus Heiser wrote:
> Am 05.02.19 um 00:03 schrieb Jonathan Corbet:
> > On Tue, 5 Feb 2019 08:12:20 +1100
> > "Tobin C. Harding"  wrote:
> > 
> > > I tried to investigate this further and I am unable to reproduce the
> > > original warning.  I'm using python virtual environment as directed by
> > > the output of `make htmldocs` so the environment should not have
> > > changed.  The only other plausible explanation seems to be that I've
> > > gone mad and can't remember what I was doing three days ago.
> > 
> > You are not the first to have reported such issues, though; I've seen a
> > couple of things go by in the past.  Until we understand what is going on,
> > it's probably best to avoid hyphens in labels.

This statement is not sitting well with me Jon, we are using hyphens in
labels all over the place with *almost* no issue.  Seems we either
change them all or none of them.  (FTR I think we should not change any
of them.)

> Many errors are not reported again in rebuilds.

It's more than that.  Seems that no .o files means dependencies are not
the same in docs directories to *usual* source code directories, as in
this example, a file with an outdated label was not rebuilt since it
wasn't touched.

Note to self, always do clean build for docs patches.  Thanks.

> To reproduce this error run 'make cleandocs htmldocs' first.  Then you will 
> see
> this error message (I'am on current docs-next from Jon using Sphinx v1.8.3 ):
> 
>   Documentation/core-api/mm-api.rst:22: WARNING: undefined label: \
> memory-allocation (if the link has no caption ...)

Can confirm I also get this warning, sloppy work by me I missed one
label.  Second note to self, grep the whole tree not just /Documentation

Thanks for reporting this.

> In mm-api.rst you find this include:
> 
> .. kernel-doc:: include/linux/slab.h
>:internal:
> 
> 
> And in slab.h you see a kmalloc DOC with a :ref:`..`
> 
> 
> /**
>  * kmalloc - allocate memory
>  * @size: how many bytes of memory are required.
>  * @flags: the type of memory to allocate.
>  *
>  * kmalloc is the normal method of allocating memory
>  * for objects smaller than page size in the kernel.
>  *
>  * The @flags argument may be one of the GFP flags defined at
>  * include/linux/gfp.h and described at
>  * :ref:`Documentation/core-api/mm-api.rst `
>  *
>  * The recommended usage of the @flags is described at
>  * :ref:`Documentation/core-api/memory-allocation.rst `
> 
> 
> With Tobin's patch applied to Jon's docs-next (cd7198fc959), this error comes 
> up
> the first time (for me).
> 
>   Can we please revert cd7198fc959 / Thanks

I agree with you Markus, I'd like to see this reverted.  Jon, your the
boss, if you want this patch to stay I can send in a patch to fix the
undefined label that this patch misses.

> @Tobin can you pleases test to revert cd7198fc959 and make a full build with
> 'cleandocs' first .. may this error comes up again for you and we can
> investigate any further .. if this depends to sphinx-Version or what ever.

With patch reverted, on docs-next, I've got 0 'undefined labels'
warnings.

Hope this adds more help than confusion :)


Tobin

Re: [PATCH 3/3] docs: Use underscore not hyphen in label

[Tobin C. Harding]

On Wed, Feb 06, 2019 at 08:49:38AM +0100, Markus Heiser wrote:
> Am 06.02.19 um 05:27 schrieb Tobin C. Harding:
> > Seems we either change them all or none of them.
> 
> Both are OK .. from the spec ...
> 
> "Simple reference names are single words consisting of alphanumerics plus
> isolated (no two adjacent) internal hyphens, underscores, periods, colons
> and plus signs; no whitespace or other characters are allowed." [1]
> 
> 
> >> Many errors are not reported again in rebuilds.
> >
> > It's more than that.  Seems that no .o files means dependencies are not
> > the same in docs directories to *usual* source code directories, as in
> > this example, a file with an outdated label was not rebuilt since it
> > wasn't touched.
> 
> Right, this is what they call the 'doctree' files (see [2] for build
> phases), one for every source file.  ATM they are located in the hidden
> folder 'output/.doctree'.  OT here, just to mentioning: this will result in
> the folder being exported at the end, e.g. kernel.org:
> 
>   https://www.kernel.org/doc/html/latest/.doctrees/
> 
> > Note to self, always do clean build for docs patches.  Thanks.
> >
> >> To reproduce this error run 'make cleandocs htmldocs' first.  Then you 
> >> will see
> >> this error message (I'am on current docs-next from Jon using Sphinx v1.8.3 
> >> ):
> >>
> >>Documentation/core-api/mm-api.rst:22: WARNING: undefined label: \
> >>  memory-allocation (if the link has no caption ...)
> >
> > Can confirm I also get this warning,
> ..
> > With patch reverted, on docs-next, I've got 0 'undefined labels'
> > warnings.
> 
> Thanks for verification.
> 
> [1] 
> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#reference-names
> [2] http://www.sphinx-doc.org/en/master/extdev/index.html#build-phases
> 
> 
>  -- Markus --
> 

Thanks Markus, I appreciate the information.


Tobin.

[PATCH 0/1] Start conversion of PowerPC docs

[Tobin C. Harding]

Hi Michael,

As discussed at LCA here is the start to the docs conversion for PowerPC
to RST.

This applies cleanly on top of the mainline (5.20-rc5) and Jon's tree
(docs-next branch).

I'm guessing it should go in through the PowerPC tree because I doubt
you want to review this Jon, it's one big single patch (all blame for
that falls on mpe ;)

This patch converts all the files that do _not_ contain ASCII art - I'm
not sure how to go about doing those, suggestions please.

>From the commit message:

 - Add SPDX license identifier to each new RST file.

.. SPDX-License-Identifier: GPL-2.0

 - User correct heading adornments.

 - Make all lines < 72 characters in width.

 - Use correct indentation for code blocks, add syntax highlighting

 - Sparingly use double ticks if it makes the files easier to parse
   both in text and on the web.

 - Fix any super obvious typos (lean towards not making changes so that
   we don't introduce errors).

Edited as text files (obviously) and formatted as HTML to verify
rendering, no other formats verified.

thanks,
Tobin.

Tobin C. Harding (1):
  docs: powerpc: Convert docs to RST format.

 Documentation/index.rst   |   1 +
 Documentation/powerpc/DAWR-POWER9.rst |  60 
 Documentation/powerpc/DAWR-POWER9.txt |  58 ---
 Documentation/powerpc/bootwrapper.rst | 140 
 Documentation/powerpc/bootwrapper.txt | 141 
 Documentation/powerpc/conf.py |  10 +
 Documentation/powerpc/cpu_features.rst|  62 
 Documentation/powerpc/cpu_features.txt|  56 ---
 .../powerpc/eeh-pci-error-recovery.rst| 319 +
 .../powerpc/eeh-pci-error-recovery.txt| 334 --
 Documentation/powerpc/index.rst   |  21 ++
 Documentation/powerpc/isa-versions.rst| 234 
 Documentation/powerpc/mpc52xx.rst |  52 +++
 Documentation/powerpc/mpc52xx.txt |  39 --
 Documentation/powerpc/pmu-ebb.rst | 148 
 Documentation/powerpc/pmu-ebb.txt | 137 ---
 Documentation/powerpc/ptrace.rst  | 177 ++
 Documentation/powerpc/ptrace.txt  | 151 
 .../{syscall64-abi.txt => syscall64-abi.rst}  |  80 +++--
 .../powerpc/transactional_memory.rst  | 259 ++
 .../powerpc/transactional_memory.txt  | 244 -
 21 files changed, 1460 insertions(+), 1263 deletions(-)
 create mode 100644 Documentation/powerpc/DAWR-POWER9.rst
 delete mode 100644 Documentation/powerpc/DAWR-POWER9.txt
 create mode 100644 Documentation/powerpc/bootwrapper.rst
 delete mode 100644 Documentation/powerpc/bootwrapper.txt
 create mode 100644 Documentation/powerpc/conf.py
 create mode 100644 Documentation/powerpc/cpu_features.rst
 delete mode 100644 Documentation/powerpc/cpu_features.txt
 create mode 100644 Documentation/powerpc/eeh-pci-error-recovery.rst
 delete mode 100644 Documentation/powerpc/eeh-pci-error-recovery.txt
 create mode 100644 Documentation/powerpc/index.rst
 create mode 100644 Documentation/powerpc/mpc52xx.rst
 delete mode 100644 Documentation/powerpc/mpc52xx.txt
 create mode 100644 Documentation/powerpc/pmu-ebb.rst
 delete mode 100644 Documentation/powerpc/pmu-ebb.txt
 create mode 100644 Documentation/powerpc/ptrace.rst
 delete mode 100644 Documentation/powerpc/ptrace.txt
 rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (58%)
 create mode 100644 Documentation/powerpc/transactional_memory.rst
 delete mode 100644 Documentation/powerpc/transactional_memory.txt

-- 
2.20.1

undefined label

[Tobin C. Harding]

Hi Jon,

I hit that undefined label warning again today.  Then just now I was
sitting enjoying a quite scotch and the reason came to me.  It is caused
by building part of the docs instead of the whole tree i.e. using

make SPHINXDIRS=admin-guide htmldocs

Gives the warning

WARNING: undefined label: numa (if the link has no caption the label 
must precede a section header)

This is a hell of a gotcha, I wasted a bunch of cycles baffled as to why
that label was not defined today :(  Super excited that I worked out why
while day dreaming though.

Last time I sent in the 'fix' I must built with SPHINXDIRS, patched then
built without SPHINXDIRS and thought the patch fixed it.

Anyways, hope you get a chuckle out of this.

All the best,
Tobin.

Re: undefined label

[Tobin C. Harding]

On Thu, Mar 07, 2019 at 10:58:07AM +0100, Markus Heiser wrote:
> Am 07.03.19 um 10:17 schrieb Tobin C. Harding:
> > Hi Jon,
> > 
> > I hit that undefined label warning again today.  Then just now I was
> > sitting enjoying a quite scotch and the reason came to me.  It is caused
> > by building part of the docs instead of the whole tree i.e. using
> > 
> > make SPHINXDIRS=admin-guide htmldocs
> > 
> > Gives the warning
> > 
> > WARNING: undefined label: numa (if the link has no caption the label 
> > must precede a section header)
> 
> The label 'numa' is not a part of the admin-guide (book), it is set in
> the vm (book): Documentation/vm/numa.rst:1
> 
> If compiling only a book like admin-guide, those links are broken.  Its not 
> only
> 'numa' which is broken and its not only the admin-guide which has cross-books
> links in.
> 
> To close such cross-books links we can use intersphinx [1] and map to e.g.
> 
>   intersphinx_mapping = {
>   'kernel': ('https://www.kernel.org/doc/html/latest/', None)}
> 
> If there is any interest in, I can implement a RFC for this.

Cool!  I think this would be super useful, I for one like using
SPHINXDIRS when developing docs incrementally so removing false warnings
would be nice.  I doubt I'm the only one to be baffled about Sphinx
references.  I'd be happy to review and test your RFC if you CC me.

thanks,
Tobin.

[PATCH 0/9] docs: Fix various build warnings/errors

[Tobin C. Harding]

Hi,

I had a few hours to spare so I thought I'd clear some Sphinx build
warnings/errors.  There isn't anything too controversial here.  The only
interesting thing I hit was in patch 7 (docs: Remove unknown 'hint'
directive), I couldn't work out if this was a serious directive, a joke,
or a typo.  Please review that patch more carefully than the others.

Patch 4 adds :ref: and raises an issue I've come across a few times now,
could I have your opinion on it please (if you have the time/inclination
to share it)

:ref:`/Documentation/path/to/file.rst `

vs

:ref:`label`

Undeniably the second is better in HTML.  The first is, on one hand,
arguable better to parse when reading the textual file (since you can
see which file it refers to) but on the other hand kinda looks ugly
since it often line wraps poorly and is a bit cluttered if all you want to
see is the path.  Having only the label doesn't _really_ make it worse
in text because often you already know (or don't care) what the path is
(e.g. when there are multiple refs to the same label) and if you do care
you can just grep the docs for the label.

Do you have an opinion on this?

Oh also, do you have a script by any chance that does a clean build of
the docs, saves stderr output, applies a patch, cleanly re-builds the
docs and then diffs the two outputs?  Then rinse-and-repeat for a whole
patch series. Thought I'd ask before I write one.

thanks,
Tobin.

Tobin C. Harding (9):
  docs: Fix spelling mistake
  docs: Add colon clearing sphinx warning
  docs: Remove unnecessary reference link title
  docs: Use reference to link to rst file
  docs: Replace backtick with apostrophe.
  docs: Use correct list markup character
  docs: Remove unknown 'hint' directive
  docs: Fix Title underline too short warning
  docs: Add blank line after SPDX licence identifier

 .../admin-guide/mm/numa_memory_policy.rst |  9 ++-
 .../driver-api/dmaengine/dmatest.rst  |  4 +-
 Documentation/driver-api/gpio/board.rst   |  5 +-
 Documentation/filesystems/path-lookup.rst | 24 
 Documentation/laptops/lg-laptop.rst   | 13 +++--
 Documentation/misc-devices/ibmvmc.rst |  1 +
 Documentation/networking/snmp_counter.rst | 58 +--
 Documentation/process/howto.rst   |  2 +-
 Documentation/vm/numa.rst |  4 +-
 Documentation/vm/slub.rst |  2 +-
 include/linux/kernel.h|  2 +-
 include/linux/wait.h  |  2 +-
 12 files changed, 64 insertions(+), 62 deletions(-)

-- 
2.21.0

[PATCH 5/9] docs: Replace backtick with apostrophe.

[Tobin C. Harding]

Sphinx emits:

WARNING: Inline interpreted text or phrase reference
start-string without end-string.

This is caused by a spurious backtick.

Replace backtick with apostrophe.

Signed-off-by: Tobin C. Harding 
---
 include/linux/kernel.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/linux/kernel.h b/include/linux/kernel.h
index 8f0e68e250a7..59c16c763086 100644
--- a/include/linux/kernel.h
+++ b/include/linux/kernel.h
@@ -134,7 +134,7 @@
  * Rounds @x up to next multiple of @y. If @y will always be a power
  * of 2, consider using the faster round_up().
  *
- * The `const' here prevents gcc-3.3 from calling __divdi3
+ * The 'const' here prevents gcc-3.3 from calling __divdi3
  */
 #define roundup(x, y) (\
 {  \
-- 
2.21.0

[PATCH 9/9] docs: Add blank line after SPDX licence identifier

[Tobin C. Harding]

Sphinx emits warning

WARNING: Explicit markup ends without a blank line; unexpected
unindent.

This is caused by a missing line after the SPDX license identifier.

Add blank line after SPDX licence identifier.

Signed-off-by: Tobin C. Harding 
---
 Documentation/laptops/lg-laptop.rst   | 1 +
 Documentation/misc-devices/ibmvmc.rst | 1 +
 2 files changed, 2 insertions(+)

diff --git a/Documentation/laptops/lg-laptop.rst 
b/Documentation/laptops/lg-laptop.rst
index d9e560dfd045..f2012d2dcb9d 100644
--- a/Documentation/laptops/lg-laptop.rst
+++ b/Documentation/laptops/lg-laptop.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GPL-2.0+
+
 LG Gram laptop extra features
 =
 
diff --git a/Documentation/misc-devices/ibmvmc.rst 
b/Documentation/misc-devices/ibmvmc.rst
index 46ded79554d4..b46df4ea2b81 100644
--- a/Documentation/misc-devices/ibmvmc.rst
+++ b/Documentation/misc-devices/ibmvmc.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GPL-2.0+
+
 ==
 IBM Virtual Management Channel Kernel Driver (IBMVMC)
 ==
-- 
2.21.0

[PATCH 8/9] docs: Fix Title underline too short warning

[Tobin C. Harding]

Sphinx emits a bunch of 'Title underline too short' warnings.  We can
fix these by using the correct length underlines.

Fix Title underline too short warning by amending heading underline.

Signed-off-by: Tobin C. Harding 
---
 Documentation/filesystems/path-lookup.rst | 24 +-
 Documentation/networking/snmp_counter.rst | 58 +++
 2 files changed, 41 insertions(+), 41 deletions(-)

diff --git a/Documentation/filesystems/path-lookup.rst 
b/Documentation/filesystems/path-lookup.rst
index 9d6b68853f5b..80e22eda4132 100644
--- a/Documentation/filesystems/path-lookup.rst
+++ b/Documentation/filesystems/path-lookup.rst
@@ -344,7 +344,7 @@ In particular it is held while scanning chains in the 
dcache hash
 table, and the mount point hash table.
 
 Bringing it together with ``struct nameidata``
-
+--
 
 .. _First edition Unix: http://minnie.tuhs.org/cgi-bin/utree.pl?file=V1/u2.s
 
@@ -355,7 +355,7 @@ converts a "name" to an "inode".  ``struct nameidata`` 
contains (among
 other fields):
 
 ``struct path path``
-~~
+
 
 A ``path`` contains a ``struct vfsmount`` (which is
 embedded in a ``struct mount``) and a ``struct dentry``.  Together these
@@ -366,13 +366,13 @@ step.  A reference through ``d_lockref`` and 
``mnt_count`` is always
 held.
 
 ``struct qstr last``
-~~
+
 
 This is a string together with a length (i.e. _not_ ``nul`` terminated)
 that is the "next" component in the pathname.
 
 ``int last_type``
-~~~
+~
 
 This is one of ``LAST_NORM``, ``LAST_ROOT``, ``LAST_DOT``, ``LAST_DOTDOT``, or
 ``LAST_BIND``.  The ``last`` field is only valid if the type is
@@ -381,7 +381,7 @@ components of the symlink have been processed yet.  Others 
should be
 fairly self-explanatory.
 
 ``struct path root``
-~~
+
 
 This is used to hold a reference to the effective root of the
 filesystem.  Often that reference won't be needed, so this field is
@@ -510,7 +510,7 @@ potentially interesting things about these dentries 
corresponding
 to three different flags that might be set in ``dentry->d_flags``:
 
 ``DCACHE_MANAGE_TRANSIT``
-~~~
+~
 
 If this flag has been set, then the filesystem has requested that the
 ``d_manage()`` dentry operation be called before handling any possible
@@ -529,7 +529,7 @@ filesystem, which will then give it a special pass through
 ``d_manage()`` by returning ``-EISDIR``.
 
 ``DCACHE_MOUNTED``
-
+~~
 
 This flag is set on every dentry that is mounted on.  As Linux
 supports multiple filesystem namespaces, it is possible that the
@@ -542,7 +542,7 @@ If this flag is set, and ``d_manage()`` didn't return 
``-EISDIR``,
 and a new ``dentry`` (both with counted references).
 
 ``DCACHE_NEED_AUTOMOUNT``
-~~~
+~
 
 If ``d_manage()`` allowed us to get this far, and ``lookup_mnt()`` didn't
 find a mount point, then this flag causes the ``d_automount()`` dentry
@@ -698,7 +698,7 @@ With that little refresher on seqlocks out of the way we 
can look at
 the bigger picture of how RCU-walk uses seqlocks.
 
 ``mount_lock`` and ``nd->m_seq``
-
+
 
 We already met the ``mount_lock`` seqlock when REF-walk used it to
 ensure that crossing a mount point is performed safely.  RCU-walk uses
@@ -727,7 +727,7 @@ results would have been the same.  This ensures the 
invariant holds,
 at least for vfsmount structures.
 
 ``dentry->d_seq`` and ``nd->seq``
-~~
+~
 
 In place of taking a count or lock on ``d_reflock``, RCU-walk samples
 the per-dentry ``d_seq`` seqlock, and stores the sequence number in the
@@ -774,7 +774,7 @@ getting a counted reference to the new dentry before 
dropping that for
 the old dentry which we saw in REF-walk.
 
 No ``inode->i_rwsem`` or even ``rename_lock``
-~
+~
 
 A semaphore is a fairly heavyweight lock that can only be taken when it is
 permissible to sleep.  As ``rcu_read_lock()`` forbids sleeping,
@@ -796,7 +796,7 @@ locking.  This neatly handles all cases, so adding extra 
checks on
 rename_lock would bring no significant value.
 
 ``unlazy walk()`` and ``complete_walk()``
--
+-
 
 That "dropping down to REF-walk" typically involves a call to
 ``unlazy_walk()``, so named because "RCU-walk" is also sometimes
diff --git a/Documentation/networking/snmp_counter.rst 
b/Documentation/networking/snmp_counter.rst
index fe8f741193be..4054f3614730 100644
--- a/Documentatio

[PATCH 7/9] docs: Remove unknown 'hint' directive

[Tobin C. Harding]

Current RST file contains an unknown directive causing Sphinx to emit

ERROR: Unexpected indentation.

Use normal language construct instead.

Signed-off-by: Tobin C. Harding 
---
 Documentation/driver-api/dmaengine/dmatest.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/driver-api/dmaengine/dmatest.rst 
b/Documentation/driver-api/dmaengine/dmatest.rst
index 8d81f1a7169b..25eecd2769b0 100644
--- a/Documentation/driver-api/dmaengine/dmatest.rst
+++ b/Documentation/driver-api/dmaengine/dmatest.rst
@@ -59,8 +59,8 @@ parameter, that specific channel is requested using the 
dmaengine and a thread
 is created with the existing parameters. This thread is set as pending
 and will be executed once run is set to 1. Any parameters set after the thread
 is created are not applied.
-.. hint::
-  available channel list could be extracted by running the following command::
+
+Hint: available channel list could be extracted by running the following 
command::
 
 % ls -1 /sys/class/dma/
 
-- 
2.21.0

[PATCH 1/9] docs: Fix spelling mistake

[Tobin C. Harding]

Documentation contains a spelling mistake / typo.

s/descibed/described/

Fix spelling mistake.

Signed-off-by: Tobin C. Harding 
---
 Documentation/process/howto.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst
index 58b2f46c4f98..5cac67f8fb17 100644
--- a/Documentation/process/howto.rst
+++ b/Documentation/process/howto.rst
@@ -62,7 +62,7 @@ Legal Issues
 The Linux kernel source code is released under the GPL.  Please see the file
 COPYING in the main directory of the source tree. The Linux kernel licensing
 rules and how to use `SPDX <https://spdx.org/>`_ identifiers in source code are
-descibed in :ref:`Documentation/process/license-rules.rst `.
+described in :ref:`Documentation/process/license-rules.rst `.
 If you have further questions about the license, please contact a lawyer, and 
do
 not ask on the Linux kernel mailing list.  The people on the mailing lists are
 not lawyers, and you should not rely on their statements on legal matters.
-- 
2.21.0

[PATCH 2/9] docs: Add colon clearing sphinx warning

[Tobin C. Harding]

Sphinx emits various warnings all caused by missing colons before code
blocks:

WARNING: Inline emphasis start-string without end-string.
WARNING: Block quote ends without a blank line; unexpected unindent.
ERROR: Unexpected indentation.
WARNING: Block quote ends without a blank line; unexpected unindent.

Add the colon, clearing sphinx warnings.

Signed-off-by: Tobin C. Harding 
---
 Documentation/vm/slub.rst | 2 +-
 include/linux/wait.h  | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/vm/slub.rst b/Documentation/vm/slub.rst
index 195928808bac..610510d90c33 100644
--- a/Documentation/vm/slub.rst
+++ b/Documentation/vm/slub.rst
@@ -66,7 +66,7 @@ Trying to find an issue in the dentry cache? Try::
 to only enable debugging on the dentry cache.  You may use an asterisk at the
 end of the slab name, in order to cover all slabs with the same prefix.  For
 example, here's how you can poison the dentry cache as well as all kmalloc
-slabs:
+slabs::
 
slub_debug=P,kmalloc-*,dentry
 
diff --git a/include/linux/wait.h b/include/linux/wait.h
index ed7c122cb31f..deedfe2b9ffe 100644
--- a/include/linux/wait.h
+++ b/include/linux/wait.h
@@ -101,7 +101,7 @@ init_waitqueue_func_entry(struct wait_queue_entry 
*wq_entry, wait_queue_func_t f
  * lead to sporadic and non-obvious failure.
  *
  * Use either while holding wait_queue_head::lock or when used for wakeups
- * with an extra smp_mb() like:
+ * with an extra smp_mb() like::
  *
  *  CPU0 - wakerCPU1 - waiter
  *
-- 
2.21.0

[PATCH 4/9] docs: Use reference to link to rst file

[Tobin C. Harding]

Current document includes the path to an RST doc file.  Since this is an
RST file we can make this a link.  Keeps the path as the link title
since that what the original author wrote.

Use reference to link to rst file.

Signed-off-by: Tobin C. Harding 
---
 Documentation/vm/numa.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/vm/numa.rst b/Documentation/vm/numa.rst
index 185d8a568168..5cae13e9a08b 100644
--- a/Documentation/vm/numa.rst
+++ b/Documentation/vm/numa.rst
@@ -109,8 +109,8 @@ System administrators and application designers can 
restrict a task's migration
 to improve NUMA locality using various CPU affinity command line interfaces,
 such as taskset(1) and numactl(1), and program interfaces such as
 sched_setaffinity(2).  Further, one can modify the kernel's default local
-allocation behavior using Linux NUMA memory policy.
-[see Documentation/admin-guide/mm/numa_memory_policy.rst.]
+allocation behavior using Linux NUMA memory policy. [see
+:ref:`Documentation/admin-guide/mm/numa_memory_policy.rst 
`].
 
 System administrators can restrict the CPUs and nodes' memories that a non-
 privileged user can specify in the scheduling or NUMA commands and functions
-- 
2.21.0

[PATCH 6/9] docs: Use correct list markup character

[Tobin C. Harding]

Sphinx uses a star not a hyphen for lists.

Use correct list markup character.

Signed-off-by: Tobin C. Harding 
---
 Documentation/driver-api/gpio/board.rst |  5 +++--
 Documentation/laptops/lg-laptop.rst | 12 ++--
 2 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/Documentation/driver-api/gpio/board.rst 
b/Documentation/driver-api/gpio/board.rst
index a0f294e2e250..a5d5c22ab610 100644
--- a/Documentation/driver-api/gpio/board.rst
+++ b/Documentation/driver-api/gpio/board.rst
@@ -204,8 +204,9 @@ between a caller and a respective .get/set_multiple() 
callback of a GPIO chip.
 
 In order to qualify for fast bitmap processing, the array must meet the
 following requirements:
-- pin hardware number of array member 0 must also be 0,
-- pin hardware numbers of consecutive array members which belong to the same
+
+* pin hardware number of array member 0 must also be 0.
+* pin hardware numbers of consecutive array members which belong to the same
   chip as member 0 does must also match their array indexes.
 
 Otherwise fast bitmap processing path is not used in order to avoid consecutive
diff --git a/Documentation/laptops/lg-laptop.rst 
b/Documentation/laptops/lg-laptop.rst
index e486fe7ddc35..d9e560dfd045 100644
--- a/Documentation/laptops/lg-laptop.rst
+++ b/Documentation/laptops/lg-laptop.rst
@@ -9,12 +9,12 @@ Hotkeys
 ---
 
 The following FN keys are ignored by the kernel without this driver:
-- FN-F1 (LG control panel)   - Generates F15
-- FN-F5 (Touchpad toggle)- Generates F13
-- FN-F6 (Airplane mode)  - Generates RFKILL
-- FN-F8 (Keyboard backlight) - Generates F16.
-  This key also changes keyboard backlight mode.
-- FN-F9 (Reader mode)- Generates F14
+
+* FN-F1 (LG control panel)   - Generates F15
+* FN-F5 (Touchpad toggle)- Generates F13
+* FN-F6 (Airplane mode)  - Generates RFKILL
+* FN-F8 (Keyboard backlight) - Generates F16 (This key also changes keyboard 
backlight mode)
+* FN-F9 (Reader mode)- Generates F14
 
 The rest of the FN key work without a need for a special driver.
 
-- 
2.21.0

[PATCH 3/9] docs: Remove unnecessary reference link title

[Tobin C. Harding]

Labels that precede a heading use the heading as the link title.
Explicitly adding the link title defeats the purpose of this feature
i.e. makes the reference less maintainable.

Remove unnecessary reference link title.

Signed-off-by: Tobin C. Harding 
---
 Documentation/admin-guide/mm/numa_memory_policy.rst | 9 -
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/Documentation/admin-guide/mm/numa_memory_policy.rst 
b/Documentation/admin-guide/mm/numa_memory_policy.rst
index d78c5b315f72..1ef0146eaa4d 100644
--- a/Documentation/admin-guide/mm/numa_memory_policy.rst
+++ b/Documentation/admin-guide/mm/numa_memory_policy.rst
@@ -20,8 +20,7 @@ which is an administrative mechanism for restricting the 
nodes from which
 memory may be allocated by a set of processes. Memory policies are a
 programming interface that a NUMA-aware application can take advantage of.  
When
 both cpusets and policies are applied to a task, the restrictions of the cpuset
-takes priority.  See :ref:`Memory Policies and cpusets `
-below for more details.
+takes priority.  See :ref:`mem_pol_and_cpusets` below for more details.
 
 Memory Policy Concepts
 ==
@@ -56,7 +55,7 @@ Task/Process Policy
[clone() w/o the CLONE_VM flag] and exec*().  This allows a parent task
to establish the task policy for a child task exec()'d from an
executable image that has no awareness of memory policy.  See the
-   :ref:`Memory Policy APIs ` section,
+   :ref:`memory_policy_apis` section,
below, for an overview of the system call
that a task may use to set/change its task/process policy.
 
@@ -77,7 +76,7 @@ VMA Policy
A "VMA" or "Virtual Memory Area" refers to a range of a task's
virtual address space.  A task may define a specific policy for a range
of its virtual address space.   See the
-   :ref:`Memory Policy APIs ` section,
+   :ref:`memory_policy_apis` section,
below, for an overview of the mbind() system call used to set a VMA
policy.
 
@@ -142,7 +141,7 @@ Shared Policy
Although hugetlbfs segments now support lazy allocation, their support
for shared policy has not been completed.
 
-   As mentioned above in :ref:`VMA policies ` section,
+   As mentioned above in :ref:`vma_policy` section,
allocations of page cache pages for regular files mmap()ed
with MAP_SHARED ignore any VMA policy installed on the virtual
address range backed by the shared file mapping.  Rather,
-- 
2.21.0

Re: [PATCH 8/9] docs: Fix Title underline too short warning

[Tobin C. Harding]

On Thu, Mar 07, 2019 at 07:42:03PM -0800, Randy Dunlap wrote:
> On 3/7/19 1:11 PM, Tobin C. Harding wrote:
> > Sphinx emits a bunch of 'Title underline too short' warnings.  We can
> > fix these by using the correct length underlines.
> > 
> > Fix Title underline too short warning by amending heading underline.
> > 
> > Signed-off-by: Tobin C. Harding 
> > ---
> >  Documentation/filesystems/path-lookup.rst | 24 +-
> >  Documentation/networking/snmp_counter.rst | 58 +++
> >  2 files changed, 41 insertions(+), 41 deletions(-)
> 
> Hi,
> 
> These are already fixed.  Did you try the pending docs tree
> (for which a pull request was sent a few hours ago)?

Oh man, - face palm.  I've been hacking on mm lately and they use
mainline, thanks for response.

  Tobin

Re: [PATCH 6/9] docs: Use correct list markup character

[Tobin C. Harding]

On Thu, Mar 07, 2019 at 07:40:14PM -0800, Randy Dunlap wrote:
> On 3/7/19 1:11 PM, Tobin C. Harding wrote:
> > Sphinx uses a star not a hyphen for lists.
> > 
> > Use correct list markup character.
> > 
> > Signed-off-by: Tobin C. Harding 
> 
> Hi Tobin,
> 
> The blank line insertions are all that is needed.
> And I have already sent a patch for that.
> 
> Also, a list can begin with any of:
> "A text block which begins with a "*", "+", "-", "•", "‣", or "⁃", followed 
> by whitespace, is a bullet list item (a.k.a. "unordered" list item)."

Oh, cool.  I didn't realise.  Thanks Randy.

Tobin

Re: [PATCH 0/9] docs: Fix various build warnings/errors

[Tobin C. Harding]

On Fri, Mar 08, 2019 at 09:40:03AM +0100, Markus Heiser wrote:
> 
> Am 07.03.19 um 22:11 schrieb Tobin C. Harding:
> > Hi,
> > 
> > I had a few hours to spare so I thought I'd clear some Sphinx build
> > warnings/errors.  There isn't anything too controversial here.  The only
> > interesting thing I hit was in patch 7 (docs: Remove unknown 'hint'
> > directive), I couldn't work out if this was a serious directive, a joke,
> > or a typo.
> 
> Hi Tobin,
> 
> the problem was a missing empty line (see my comment on this patch).
> 
> The reST primer from sphinx-doc is always a good reference for the daily work
> 
>   
> http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives

Thanks Marcus, that's actually how I came to the conclusion that they
should by asterisks.


http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#lists-and-quote-like-blocks

Anyways, as usual LKML sorted me out :)

thanks,
Tobin.

Documenting struct function pointers (methods)

[Tobin C. Harding]

Hi,

Is documenting 'methods' i.e. function pointers in structs like 'struct
file_operations' something that we do anywhere?  Is this handled by RST?
Is it something that has been discussed already?

I'm in the process of trying to grok the dcache and update the docs.
For each function pointer I'm reading various implementations and trying
to work out what the method is supposed to do.  Surely this is a good
candidate for improving kernel documentation in order to help devs come
up to speed more quickly?

An example from include/linux/fs.h (adding docstring comments to struct
file_system_type).  This is _not_ handled correctly by Sphinx, is there
a way to do this?  Or are hard-core hackers going to scream that this is
too much documentation :)


/**
 * struct file_system_type
 * @name: Name of the filesystem type, such as "ext2", "iso9660",
 *"msdos" and so on.
 * @fs_flags: Various flags (i.e. FS_REQUIRES_DEV, FS_NO_DCACHE, etc.).
 * ...
 */
struct file_system_type {
   [snip]
const struct fs_parameter_description *parameters;
/**
 * @mount: The method to call when a new instance of this
 * filesystem should be mounted.
 *
 * The mount() method has the following arguments:
 * @fs_type: Describes the filesystem, partly initialized by the
 *   specific filesystem code.
 * @flags: Mount flags.
 * @dev_name: The device name we are mounting.
 * @data: Arbitrary mount options, usually comes as an ASCII
 *string (see "Mount Options" section).
 */
struct dentry *(*mount) (struct file_system_type *fs_type, int flags,
 const char *dev_name, void *data);
void (*kill_sb) (struct super_block *);


thanks,
Tobin.

[PATCH v4 1/9] docs: filesystems: vfs: Remove space before tab

[Tobin C. Harding]

Currently the file has a bunch of spaces before tabspaces.  This is a
nuisance when patching the file because they show up whenever we touch
these lines.  Let's just fix them all now in preparation for doing the
RST conversion.

Remove spaces before tabspaces.

Tested-by: Randy Dunlap 
Signed-off-by: Tobin C. Harding 
---
 Documentation/filesystems/vfs.txt | 78 +++
 1 file changed, 39 insertions(+), 39 deletions(-)

diff --git a/Documentation/filesystems/vfs.txt 
b/Documentation/filesystems/vfs.txt
index 761c6fd24a53..637fd1756b89 100644
--- a/Documentation/filesystems/vfs.txt
+++ b/Documentation/filesystems/vfs.txt
@@ -136,7 +136,7 @@ struct file_system_type {
should be shut down
 
   owner: for internal VFS use: you should initialize this to THIS_MODULE in
-   most cases.
+   most cases.
 
   next: for internal VFS use: you should initialize this to NULL
 
@@ -145,7 +145,7 @@ struct file_system_type {
 The mount() method has the following arguments:
 
   struct file_system_type *fs_type: describes the filesystem, partly 
initialized
-   by the specific filesystem code
+   by the specific filesystem code
 
   int flags: mount flags
 
@@ -182,12 +182,12 @@ and provides a fill_super() callback instead. The generic 
variants are:
   mount_nodev: mount a filesystem that is not backed by a device
 
   mount_single: mount a filesystem which shares the instance between
-   all mounts
+   all mounts
 
 A fill_super() callback implementation has the following arguments:
 
   struct super_block *sb: the superblock structure. The callback
-   must initialize this properly.
+   must initialize this properly.
 
   void *data: arbitrary mount options, usually comes as an ASCII
string (see "Mount Options" section)
@@ -238,14 +238,14 @@ only called from a process context (i.e. not from an 
interrupt handler
 or bottom half).
 
   alloc_inode: this method is called by alloc_inode() to allocate memory
-   for struct inode and initialize it.  If this function is not
-   defined, a simple 'struct inode' is allocated.  Normally
-   alloc_inode will be used to allocate a larger structure which
-   contains a 'struct inode' embedded within it.
+   for struct inode and initialize it.  If this function is not
+   defined, a simple 'struct inode' is allocated.  Normally
+   alloc_inode will be used to allocate a larger structure which
+   contains a 'struct inode' embedded within it.
 
   destroy_inode: this method is called by destroy_inode() to release
-   resources allocated for struct inode.  It is only required if
-   ->alloc_inode was defined and simply undoes anything done by
+   resources allocated for struct inode.  It is only required if
+   ->alloc_inode was defined and simply undoes anything done by
->alloc_inode.
 
   dirty_inode: this method is called by the VFS to mark an inode dirty.
@@ -273,15 +273,15 @@ or bottom half).
(i.e. unmount). This is called with the superblock lock held
 
   sync_fs: called when VFS is writing out all dirty data associated with
-   a superblock. The second parameter indicates whether the method
+   a superblock. The second parameter indicates whether the method
should wait until the write out has been completed. Optional.
 
   freeze_fs: called when VFS is locking a filesystem and
-   forcing it into a consistent state.  This method is currently
-   used by the Logical Volume Manager (LVM).
+   forcing it into a consistent state.  This method is currently
+   used by the Logical Volume Manager (LVM).
 
   unfreeze_fs: called when VFS is unlocking a filesystem and making it writable
-   again.
+   again.
 
   statfs: called when the VFS needs to get filesystem statistics.
 
@@ -472,30 +472,30 @@ otherwise noted.
that.
 
   permission: called by the VFS to check for access rights on a POSIX-like
-   filesystem.
+   filesystem.
 
May be called in rcu-walk mode (mask & MAY_NOT_BLOCK). If in rcu-walk
-mode, the filesystem must check the permission without blocking or
+   mode, the filesystem must check the permission without blocking or
storing to the inode.
 
If a situation is encountered that rcu-walk cannot handle, return
-ECHILD and it will be called again in ref-walk mode.
 
   setattr: called by the VFS to set attributes for a file. This method
-   is called by chmod(2) and related system calls.
+   is called by chmod(2) and related system calls.
 
   getattr: called by the VFS to get attributes of a file. This method
-   is called by stat(2) and related system calls.
+   is called by stat(2) and related system calls.
 
   listxattr: called by the VFS to list all extended attributes for a
given file. This method is called by the listxattr(2) system call.

[PATCH v4 0/9] docs: Convert VFS doc to RST

[Tobin C. Harding]

Hi Jon,

Here is an updated version of the VFS doc conversion.  This series in no
way represents a final point for the VFS documentation rather it is a
small step towards getting VFS docs updated.  This series does not
update the content of vfs.txt, only does formatting.

Testing: the following produces no new build warnings

make cleandocs
make htmldocs 2> pre.stderr

# apply this patch series

make cleandocs
make htmldocs 2> post.stderr
diff pre.stderr post.stderr


thanks,
Tobin.


Tobin C. Harding (9):
  docs: filesystems: vfs: Remove space before tab
  docs: filesystems: vfs: Use uniform space after period.
  docs: filesystems: vfs: Use 72 character column width
  docs: filesystems: vfs: Use uniform spacing around headings
  docs: filesystems: vfs: Use correct initial heading
  docs: filesystems: vfs: Use SPDX identifier
  docs: filesystems: vfs: Fix pre-amble indentation
  docs: filesystems: vfs: Convert spaces to tabs
  docs: filesystems: vfs: Convert vfs.txt to RST

 Documentation/filesystems/index.rst |1 +
 Documentation/filesystems/vfs.rst   | 1286 +++
 Documentation/filesystems/vfs.txt   | 1264 --
 3 files changed, 1287 insertions(+), 1264 deletions(-)
 create mode 100644 Documentation/filesystems/vfs.rst
 delete mode 100644 Documentation/filesystems/vfs.txt

-- 
2.21.0

[PATCH v4 2/9] docs: filesystems: vfs: Use uniform space after period.

[Tobin C. Harding]

Currently sometimes document has a single space after a period and
sometimes it has double.  Whichever we use it should be uniform.

Use double space after period, be uniform.

Tested-by: Randy Dunlap 
Signed-off-by: Tobin C. Harding 
---
 Documentation/filesystems/vfs.txt | 246 +++---
 1 file changed, 123 insertions(+), 123 deletions(-)

diff --git a/Documentation/filesystems/vfs.txt 
b/Documentation/filesystems/vfs.txt
index 637fd1756b89..2a610b9355e0 100644
--- a/Documentation/filesystems/vfs.txt
+++ b/Documentation/filesystems/vfs.txt
@@ -16,12 +16,12 @@ Introduction
 
 The Virtual File System (also known as the Virtual Filesystem Switch)
 is the software layer in the kernel that provides the filesystem
-interface to userspace programs. It also provides an abstraction
+interface to userspace programs.  It also provides an abstraction
 within the kernel which allows different filesystem implementations to
 coexist.
 
 VFS system calls open(2), stat(2), read(2), write(2), chmod(2) and so
-on are called from a process context. Filesystem locking is described
+on are called from a process context.  Filesystem locking is described
 in the document Documentation/filesystems/Locking.
 
 
@@ -29,37 +29,37 @@ Directory Entry Cache (dcache)
 --
 
 The VFS implements the open(2), stat(2), chmod(2), and similar system
-calls. The pathname argument that is passed to them is used by the VFS
+calls.  The pathname argument that is passed to them is used by the VFS
 to search through the directory entry cache (also known as the dentry
-cache or dcache). This provides a very fast look-up mechanism to
-translate a pathname (filename) into a specific dentry. Dentries live
+cache or dcache).  This provides a very fast look-up mechanism to
+translate a pathname (filename) into a specific dentry.  Dentries live
 in RAM and are never saved to disc: they exist only for performance.
 
-The dentry cache is meant to be a view into your entire filespace. As
+The dentry cache is meant to be a view into your entire filespace.  As
 most computers cannot fit all dentries in the RAM at the same time,
-some bits of the cache are missing. In order to resolve your pathname
+some bits of the cache are missing.  In order to resolve your pathname
 into a dentry, the VFS may have to resort to creating dentries along
-the way, and then loading the inode. This is done by looking up the
+the way, and then loading the inode.  This is done by looking up the
 inode.
 
 
 The Inode Object
 
 
-An individual dentry usually has a pointer to an inode. Inodes are
+An individual dentry usually has a pointer to an inode.  Inodes are
 filesystem objects such as regular files, directories, FIFOs and other
 beasts.  They live either on the disc (for block device filesystems)
-or in the memory (for pseudo filesystems). Inodes that live on the
+or in the memory (for pseudo filesystems).  Inodes that live on the
 disc are copied into the memory when required and changes to the inode
-are written back to disc. A single inode can be pointed to by multiple
+are written back to disc.  A single inode can be pointed to by multiple
 dentries (hard links, for example, do this).
 
 To look up an inode requires that the VFS calls the lookup() method of
-the parent directory inode. This method is installed by the specific
-filesystem implementation that the inode lives in. Once the VFS has
+the parent directory inode.  This method is installed by the specific
+filesystem implementation that the inode lives in.  Once the VFS has
 the required dentry (and hence the inode), we can do all those boring
 things like open(2) the file, or stat(2) it to peek at the inode
-data. The stat(2) operation is fairly simple: once the VFS has the
+data.  The stat(2) operation is fairly simple: once the VFS has the
 dentry, it peeks at the inode data and passes some of it back to
 userspace.
 
@@ -69,17 +69,17 @@ The File Object
 
 Opening a file requires another operation: allocation of a file
 structure (this is the kernel-side implementation of file
-descriptors). The freshly allocated file structure is initialized with
+descriptors).  The freshly allocated file structure is initialized with
 a pointer to the dentry and a set of file operation member functions.
-These are taken from the inode data. The open() file method is then
-called so the specific filesystem implementation can do its work. You
-can see that this is another switch performed by the VFS. The file
+These are taken from the inode data.  The open() file method is then
+called so the specific filesystem implementation can do its work.  You
+can see that this is another switch performed by the VFS.  The file
 structure is placed into the file descriptor table for the process.
 
 Reading, writing and closing files (and other assorted VFS operations)
 is done by using the userspace file descriptor to grab the appropriate
 file structure, and then calling the

[PATCH v4 4/9] docs: filesystems: vfs: Use uniform spacing around headings

[Tobin C. Harding]

Currently spacing before and after headings is non-uniform.  Use two
blank lines before a heading and one after the heading.

Use uniform spacing around headings.

Tested-by: Randy Dunlap 
Signed-off-by: Tobin C. Harding 
---
 Documentation/filesystems/vfs.txt | 9 +
 1 file changed, 9 insertions(+)

diff --git a/Documentation/filesystems/vfs.txt 
b/Documentation/filesystems/vfs.txt
index 14839bc84d38..ed12d28bda62 100644
--- a/Documentation/filesystems/vfs.txt
+++ b/Documentation/filesystems/vfs.txt
@@ -321,6 +321,7 @@ Whoever sets up the inode is responsible for filling in the 
"i_op"
 field.  This is a pointer to a "struct inode_operations" which describes
 the methods that can be performed on individual inodes.
 
+
 struct xattr_handlers
 -
 
@@ -507,6 +508,7 @@ otherwise noted.
   tmpfile: called in the end of O_TMPFILE open().  Optional, equivalent to
atomically creating, opening and unlinking a file in given directory.
 
+
 The Address Space Object
 
 
@@ -580,8 +582,10 @@ and the constraints under which it is being done.  It is 
also used to
 return information back to the caller about the result of a writepage or
 writepages request.
 
+
 Handling errors during writeback
 
+
 Most applications that do buffered I/O will periodically call a file
 synchronization call (fsync, fdatasync, msync or sync_file_range) to
 ensure that data written has made it to the backing store.  When there
@@ -612,6 +616,7 @@ file->fsync operation, they should call 
file_check_and_advance_wb_err to
 ensure that the struct file's error cursor has advanced to the correct
 point in the stream of errors emitted by the backing device(s).
 
+
 struct address_space_operations
 ---
 
@@ -1203,9 +1208,11 @@ manipulate dentries:
and the dentry is returned.  The caller must use dput()
to free the dentry when it finishes using it.
 
+
 Mount Options
 =
 
+
 Parsing options
 ---
 
@@ -1220,6 +1227,7 @@ The  header defines an API that helps 
parse these
 options.  There are plenty of examples on how to use it in existing
 filesystems.
 
+
 Showing options
 ---
 
@@ -1241,6 +1249,7 @@ The underlying reason for the above rules is to make 
sure, that a mount
 can be accurately replicated (e.g. umounting and mounting again) based
 on the information found in /proc/mounts.
 
+
 Resources
 =
 
-- 
2.21.0

[PATCH v4 8/9] docs: filesystems: vfs: Convert spaces to tabs

[Tobin C. Harding]

There are bunch of places with 8 spaces, in preparation for correctly
indenting all code snippets (during conversion to RST) change these to
use tabspaces.

This patch is whitespace only.

Convert instances of 8 consecutive spaces to a single tabspace.

Signed-off-by: Tobin C. Harding 
---
 Documentation/filesystems/vfs.txt | 124 +++---
 1 file changed, 62 insertions(+), 62 deletions(-)

diff --git a/Documentation/filesystems/vfs.txt 
b/Documentation/filesystems/vfs.txt
index 43b18bafbc20..489bbdc6a40f 100644
--- a/Documentation/filesystems/vfs.txt
+++ b/Documentation/filesystems/vfs.txt
@@ -113,12 +113,12 @@ members are defined:
 struct file_system_type {
const char *name;
int fs_flags;
-struct dentry *(*mount) (struct file_system_type *, int,
-   const char *, void *);
-void (*kill_sb) (struct super_block *);
-struct module *owner;
-struct file_system_type * next;
-struct list_head fs_supers;
+   struct dentry *(*mount) (struct file_system_type *, int,
+  const char *, void *);
+   void (*kill_sb) (struct super_block *);
+   struct module *owner;
+   struct file_system_type * next;
+   struct list_head fs_supers;
struct lock_class_key s_lock_key;
struct lock_class_key s_umount_key;
 };
@@ -207,26 +207,26 @@ This describes how the VFS can manipulate the superblock 
of your
 filesystem.  As of kernel 2.6.22, the following members are defined:
 
 struct super_operations {
-struct inode *(*alloc_inode)(struct super_block *sb);
-void (*destroy_inode)(struct inode *);
-
-void (*dirty_inode) (struct inode *, int flags);
-int (*write_inode) (struct inode *, int);
-void (*drop_inode) (struct inode *);
-void (*delete_inode) (struct inode *);
-void (*put_super) (struct super_block *);
-int (*sync_fs)(struct super_block *sb, int wait);
-int (*freeze_fs) (struct super_block *);
-int (*unfreeze_fs) (struct super_block *);
-int (*statfs) (struct dentry *, struct kstatfs *);
-int (*remount_fs) (struct super_block *, int *, char *);
-void (*clear_inode) (struct inode *);
-void (*umount_begin) (struct super_block *);
-
-int (*show_options)(struct seq_file *, struct dentry *);
-
-ssize_t (*quota_read)(struct super_block *, int, char *, size_t, 
loff_t);
-ssize_t (*quota_write)(struct super_block *, int, const char *, 
size_t, loff_t);
+   struct inode *(*alloc_inode)(struct super_block *sb);
+   void (*destroy_inode)(struct inode *);
+
+   void (*dirty_inode) (struct inode *, int flags);
+   int (*write_inode) (struct inode *, int);
+   void (*drop_inode) (struct inode *);
+   void (*delete_inode) (struct inode *);
+   void (*put_super) (struct super_block *);
+   int (*sync_fs)(struct super_block *sb, int wait);
+   int (*freeze_fs) (struct super_block *);
+   int (*unfreeze_fs) (struct super_block *);
+   int (*statfs) (struct dentry *, struct kstatfs *);
+   int (*remount_fs) (struct super_block *, int *, char *);
+   void (*clear_inode) (struct inode *);
+   void (*umount_begin) (struct super_block *);
+
+   int (*show_options)(struct seq_file *, struct dentry *);
+
+   ssize_t (*quota_read)(struct super_block *, int, char *, size_t, 
loff_t);
+   ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, 
loff_t);
int (*nr_cached_objects)(struct super_block *);
void (*free_cached_objects)(struct super_block *, int);
 };
@@ -475,7 +475,7 @@ otherwise noted.
filesystem.
 
May be called in rcu-walk mode (mask & MAY_NOT_BLOCK).  If in rcu-walk
-mode, the filesystem must check the permission without blocking or
+   mode, the filesystem must check the permission without blocking or
storing to the inode.
 
If a situation is encountered that rcu-walk cannot handle, return
@@ -694,12 +694,12 @@ struct address_space_operations {
tagged as DIRTY and will pass them to ->writepage.
 
   set_page_dirty: called by the VM to set a page dirty.
-This is particularly needed if an address space attaches
-private data to a page, and that data needs to be updated when
-a page is dirtied.  This is called, for example, when a memory
+   This is particularly needed if an address space attaches
+   private data to a page, and that data needs to be updated when
+   a page is dirtied.  This is called, for example, when a memory
mapped page gets modified.
If defined, it should set the PageDirty flag, and the
-PAGECACHE_TAG_DIRTY tag in the radix tree.
+   PAGECACHE_TAG_DIRTY tag in the radix tree.
 
   readpages: called by the VM to read pages associated with the address_space
object.  This is essentially just a vector version of
@@

[PATCH v4 6/9] docs: filesystems: vfs: Use SPDX identifier

[Tobin C. Harding]

Currently the licence is indicated via a custom string.  We have SPDX
license identifiers now for this task.

Use SPDX license identifier matching current license string.

Tested-by: Randy Dunlap 
Signed-off-by: Tobin C. Harding 
---
 Documentation/filesystems/vfs.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/filesystems/vfs.txt 
b/Documentation/filesystems/vfs.txt
index 790feccca5f4..5c8358c73e30 100644
--- a/Documentation/filesystems/vfs.txt
+++ b/Documentation/filesystems/vfs.txt
@@ -1,3 +1,5 @@
+.. SPDX-License-Identifier: GPL-2.0
+
 =
 Overview of the Linux Virtual File System
 =
@@ -9,8 +11,6 @@ Overview of the Linux Virtual File System
   Copyright (C) 1999 Richard Gooch
   Copyright (C) 2005 Pekka Enberg
 
-  This file is released under the GPLv2.
-
 
 Introduction
 
-- 
2.21.0

[PATCH v4 7/9] docs: filesystems: vfs: Fix pre-amble indentation

[Tobin C. Harding]

Currently file pre-amble contains custom indentation.  RST is not going
to like this, lets left-align the text.  Put the copyright notices in a
list in preparation for converting document to RST.

Tested-by: Randy Dunlap 
Signed-off-by: Tobin C. Harding 
---
 Documentation/filesystems/vfs.txt | 8 
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/filesystems/vfs.txt 
b/Documentation/filesystems/vfs.txt
index 5c8358c73e30..43b18bafbc20 100644
--- a/Documentation/filesystems/vfs.txt
+++ b/Documentation/filesystems/vfs.txt
@@ -4,12 +4,12 @@
 Overview of the Linux Virtual File System
 =
 
-   Original author: Richard Gooch 
+Original author: Richard Gooch 
 
- Last updated on June 24, 2007.
+Last updated on June 24, 2007.
 
-  Copyright (C) 1999 Richard Gooch
-  Copyright (C) 2005 Pekka Enberg
+- Copyright (C) 1999 Richard Gooch
+- Copyright (C) 2005 Pekka Enberg
 
 
 Introduction
-- 
2.21.0