Re: [PATCH v2 3/3] tools: move pcmcia crc32hash tool from Documentation

[Dominik Brodowski]

On Wed, Sep 21, 2016 at 06:51:13PM -0600, Shuah Khan wrote:
> Move pcmcia crc32hash tool from Documentation to tools/pcmcia and
> remove it from Documentation Makefile. Update location information
> for this tool. Create a new Makefile to build pcmcia. It can be built
> from top level directory or from pcmcia directory:
> 
> Run make -C tools/pcmcia or cd tools/pcmcia; make
> 
> Signed-off-by: Shuah Khan 

Acked-by: Dominik Brodowski 


signature.asc
Description: Digital signature

Re: [RFC PATCH v2 3/5] futex: Throughput-optimized (TO) futexes

[Peter Zijlstra]

On Wed, Sep 21, 2016 at 07:37:34PM -0400, Waiman Long wrote:
> On 09/21/2016 02:59 AM, Mike Galbraith wrote:
> >On Tue, 2016-09-20 at 09:42 -0400, Waiman Long wrote:
> >>This patch introduces a new futex implementation called
> >>throughput-optimized (TO) futexes.
> >nit: 'TO' sounds way too much like timeout... TP?  You even use 'to' as
> >shorthand for timeout in the next patch.
> 
> I agree. I am not that satisfied with the TO name. So I will change it to TP
> in my next revision of the patch. Thanks for the suggestion.

I'd leave out the TO part entirely (or only mention it in changelogs).

That is, I'd call the futex ops: FUTEX_LOCK and FUTEX_UNLOCK.
--
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: "CodingStyle: Clarify and complete chapter 7" in docs-next

[Jean Delvare]

Hi Joe,

On Mon, 19 Sep 2016 23:32:03 -0700, Joe Perches wrote:
> On Tue, 2016-09-20 at 07:53 +0200, Julia Lawall wrote:
> > I think it is better to be clear.  CHECK was never really clear to me,
> > especially if you see it in isolation, on a file that doesn't also have
> > ERROR or WARNING.  NITS is a common word in this context, but not FLEAS
> > and GNATS, as far as I know.
> > There could also be a severity level: high medium and low
> 
> I agree clarity is good.
> 
> The seriousness with which some beginners take these message
> types though is troublesome,

You need to think in terms of actual use cases. Who uses checkpatch and
why? I think there are 3 groups of users:
* Beginners. They won't run the script by themselves, instead they will
  submit a patch which infringes a lot of coding style rules, and the
  maintainer will point them to checkpatch and ask for a resubmission
  which makes checkpatch happy. Being beginners, they can only rely on
  the script itself to only report things which need to be fixed, by
  default.
* Experienced developers. Who simply want to make sure they did not
  overlook anything before they post their work for review. They have
  the knowledge to decide if they want to ignore some of the warnings.
* People with too much spare time, looking for anything they could
  "contribute" to the kernel. They will use --subjective and piss off
  every maintainer they can find.

Sadly there's not much we can do about the third category, short of
killing option --subjective altogether.

The default settings should work out of the box for for the first
category.

> Maybe prefix various different types of style messages.
> 
> Something like:
> 
> ERROR -> CODE_STYLE_DEFECT
> WARNING -> CODE_STYLE_UNPREFERRED
> CHECK -> CODE_STYLE_NIT

I don't think you clarify anything with these changes, as they do not
carry the requirement from a submitter's perspective. If you really
want to change the names, I would rather suggest:

ERROR -> MUST_FIX
WARNING -> SHOULD_FIX
CHECK -> MAY_FIX

Or explain the categories in plain English, see below.

> I doubt additional external documentation would help much.

I agree. If anything needs to be explained, it should be included in
the output of checkpatch directly. For example, if any ERROR was
printed, include the following after the count summary:

"ERROR means the code is infringing a core coding style rule. This MUST
be fixed before the patch is submitted upstream."

And if any WARNING was printed, include the following:

"WARNING means the code is not following the best practice. This SHOULD
be fixed before the patch is submitted upstream, unless the maintainer
agreed otherwise."

Not sure if we need something for CHECK, as these messages are not
printed by default so I'd assume people who get them know what they
asked for. But apparently these confused Julia so maybe a similar
explanation would be needed for them too.

-- 
Jean Delvare
SUSE L3 Support
--
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: Remove space-before-label guidance from CodingStyle

[Jean Delvare]

Hi Jonathan,

On Wed, 21 Sep 2016 15:54:01 -0600, Jonathan Corbet wrote:
> Recent discussion has made it clear that there is no community consensus
> on this particular rule.  Remove it now, lest it inspire yet another set
> of unwanted "cleanup" patches.
> 
> This partially reverts 865a1caa4b6b (CodingStyle: Clarify and complete
> chapter 7).
> (...)
> @@ -481,7 +478,7 @@ The rationale for using gotos is:
>   goto out_buffer;
>   }
>   ...
> -  out_free_buffer:
> + out_free_buffer:
>   kfree(buffer);
>   return result;
>   }
> @@ -490,7 +487,7 @@ A common type of bug to be aware of is ``one err
> bugs`` which look like this: 
>  .. code-block:: c
>  
> -  err:
> + err:
>   kfree(foo->bar);
>   kfree(foo);
>   return ret;

There are 2 more occurrences after this point, which you probably want
to change too.

-- 
Jean Delvare
SUSE L3 Support
--
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 RESEND] crypto: doc - fix documentation for bulk registration functions

[Herbert Xu]

Eric Biggers  wrote:
> Update the documentation for crypto_register_algs() and
> crypto_unregister_algs() to match the actual behavior.
> 
> Signed-off-by: Eric Biggers 

Your previous submission has already been applied.

Cheers,
--
Email: Herbert Xu 
Home Page: http://gondor.apana.org.au/~herbert/
PGP Key: http://gondor.apana.org.au/~herbert/pubkey.txt
--
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: XDP (eXpress Data Path) documentation

[Jesper Dangaard Brouer]

On Wed, 21 Sep 2016 17:03:24 -0700
Tom Herbert  wrote:

> On Tue, Sep 20, 2016 at 2:08 AM, Jesper Dangaard Brouer
>  wrote:
> > Hi all,
> >
> > As promised, I've started documenting the XDP eXpress Data Path):
> >
> >  [1] 
> > https://prototype-kernel.readthedocs.io/en/latest/networking/XDP/index.html
> >
> > IMHO the documentation have reached a stage where it is useful for the
> > XDP project, BUT I request collaboration on improving the documentation
> > from all. (Native English speakers are encouraged to send grammar fixes ;-))
> >  
> Hi Jesper,
> 
> Thanks for taking the initiative on the this, The document reads more
> like a design doc than description right now, that's probably okay
> since we could use a design doc.

Yes, I fully agree.

I want to state very clearly, this document is not an attempt to hijack
the XDP project and control the "spec".  This is an attempt to collaborate.
We discuss things on the mailing list, each with our own vision of the
project, and most times we reach an agreement. But nobody document this
agreement. 

Month later, we make implementation choices that goes against these
agreements, because we simply forgot.  If someone remembers, we have to
reiterate the same arguments again (like it just happened with the
XDP_ABORTED action, my mistake).  And can anybody remember the
consensus around VLANs, it never got implemented that way...

I had to start the doc project somewhere, so I dumped my own vision
into the docs, and what I could remember from upstream discussions.
I need collaboration from others to adjust and "fix" my vision of the
project, into something that becomes a common ground we all can agree
on.

If some part of the docs provoke you, good, then you have a reason to
correct and fix it.  I'll do my best to keep an very open-mind about
any changes.  This should be a very "live" document.  


> Under "Important to understand" there are some disclaimers that XDP
> does not implement qdiscs or BQL and fairness otherwise. This is true
> for it's own traffic, but it does not (or at least should not) affect
> these mechanisms or normal stack traffic running simultaneously. I
> think we've made assumptions about fairness between XDP and non-XDP
> queues, we probably want to clarify fairness (and also validate
> whatever assumptions we've made with testing).

I love people pointing out mistakes in the documentation.  I want
update this ASAP when people point it out.  I'll even do the work of
integrating and committing these changes, for people too lazy to git
clone the repo themselves.

For you section Tom, I fully agree, but I don't know how to formulate
and adjust this in the text.

For people that want to edit the docs, notice the link "Edit on GitHub"
which takes you directly to the file you need to edit...



> > You wouldn't believe it: But this pretty looking documentation actually
> > follows the new Kernel documentation format.  It is actually just
> > ".rst" text files stored in my github repository under kernel/Documentation 
> > [2]
> >
> >  [2] 
> > https://github.com/netoptimizer/prototype-kernel/tree/master/kernel/Documentation
> >
> > Thus, just git clone my repository and started editing and send me
> > patches (or github pull requests). Like:
> >
> >  $ git clone https://github.com/netoptimizer/prototype-kernel
> >  $ cd prototype-kernel/kernel/Documentation/
> >  $ make html
> >  $ firefox _build/html/index.html &
> >
> > This new documentation format combines the best of two worlds, pretty
> > online browser documentation with almost plain text files, and changes
> > being tracked via git commits [3] (and auto git hooks to generate the
> > readthedocs.org page). You got to love it! :-)
> >
> > --
> > Best regards,
> >   Jesper Dangaard Brouer
> >   MSc.CS, Principal Kernel Engineer at Red Hat
> >   Author of http://www.iptv-analyzer.org
> >   LinkedIn: http://www.linkedin.com/in/brouer
> >
> > [3] https://github.com/netoptimizer/prototype-kernel/commits/master  

-- 
Best regards,
  Jesper Dangaard Brouer
  MSc.CS, Principal Kernel Engineer at Red Hat
  Author of http://www.iptv-analyzer.org
  LinkedIn: http://www.linkedin.com/in/brouer
--
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: "CodingStyle: Clarify and complete chapter 7" in docs-next

[Joe Perches]

On Thu, 2016-09-22 at 11:24 +0200, Jean Delvare wrote:
[]
> > The seriousness with which some beginners take these message
> > types though is troublesome,
[]
> You need to think in terms of actual use cases. Who uses checkpatch and
> why? I think there are 3 groups of users:
> * Beginners. They won't run the script by themselves, instead they will
>   submit a patch which infringes a lot of coding style rules, and the
>   maintainer will point them to checkpatch and ask for a resubmission
>   which makes checkpatch happy. Being beginners, they can only rely on
>   the script itself to only report things which need to be fixed, by
>   default.
> * Experienced developers. Who simply want to make sure they did not
>   overlook anything before they post their work for review. They have
>   the knowledge to decide if they want to ignore some of the warnings.
> * People with too much spare time, looking for anything they could
>   "contribute" to the kernel. They will use --subjective and piss off
>   every maintainer they can find.

I think you overlook the category of a beginner submitting
"my first kernel patch" which is a "coding style" defect of
some type.  The Eudyptula and Outreachy programs seem to
encourage these sorts of patches.

This is where "scripts/checkpatch.pl -f " is most used.

I believe adding the --force option might be useful to
restrict cleanup-style-only patches outside of staging.

There's nothing wrong with cleanup style patches, it can be
good introduction to compiler/config tool & kernel setup.
 
> I would rather suggest:
> 
> ERROR -> MUST_FIX
> WARNING -> SHOULD_FIX
> CHECK -> MAY_FIX

MUST is much stronger language than I would prefer.

There are still about a quarter million ERRORs just for
spacing issues in the kernel tree.

Here are the top 10 ERROR checkpatch messages treewide as of
a few days ago,

$ grep ERROR checkpatch.short_sorted_20160917
 268308  ERROR:SPACING
  37340  ERROR:CODE_INDENT
  27678  ERROR:TRAILING_WHITESPACE
  21024  ERROR:COMPLEX_MACRO
  14048  ERROR:POINTER_LOCATION
  12207  ERROR:TRAILING_STATEMENTS
  11079  ERROR:OPEN_BRACE
   6802  ERROR:ASSIGN_IN_IF
   3940  ERROR:RETURN_PARENTHESES
   2322  ERROR:NON_OCTAL_PERMISSIONS

Maybe there could be some better classifications of the various
messages.

But there are about two million checkpatch messages overall in
the kernel tree.

That's a lot.
--
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 PATCH 4/4] futex, doc: TO futexes document

[Thomas Gleixner]

On Tue, 6 Sep 2016, Waiman Long wrote:
> This patch adds a new document file on how to use the TO futexes.

Documentation is nice, but the proper place for documenting this is the
futex(2) man page.
 
Thanks,

tglx
--
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: "CodingStyle: Clarify and complete chapter 7" in docs-next

[Jani Nikula]

On Thu, 22 Sep 2016, Jean Delvare  wrote:
> Hi Joe,
>
> On Mon, 19 Sep 2016 23:32:03 -0700, Joe Perches wrote:
>> On Tue, 2016-09-20 at 07:53 +0200, Julia Lawall wrote:
>> > I think it is better to be clear.  CHECK was never really clear to me,
>> > especially if you see it in isolation, on a file that doesn't also have
>> > ERROR or WARNING.  NITS is a common word in this context, but not FLEAS
>> > and GNATS, as far as I know.
>> > There could also be a severity level: high medium and low
>> 
>> I agree clarity is good.
>> 
>> The seriousness with which some beginners take these message
>> types though is troublesome,
>
> You need to think in terms of actual use cases. Who uses checkpatch and
> why? I think there are 3 groups of users:
> * Beginners. They won't run the script by themselves, instead they will
>   submit a patch which infringes a lot of coding style rules, and the
>   maintainer will point them to checkpatch and ask for a resubmission
>   which makes checkpatch happy. Being beginners, they can only rely on
>   the script itself to only report things which need to be fixed, by
>   default.
> * Experienced developers. Who simply want to make sure they did not
>   overlook anything before they post their work for review. They have
>   the knowledge to decide if they want to ignore some of the warnings.
> * People with too much spare time, looking for anything they could
>   "contribute" to the kernel. They will use --subjective and piss off
>   every maintainer they can find.
>
> Sadly there's not much we can do about the third category, short of
> killing option --subjective altogether.

You could make checkpatch have different defaults for patches and files,
to encourage better style in new code, but to discourage finding
problems in existing code.

BR,
Jani.


>
> The default settings should work out of the box for for the first
> category.
>
>> Maybe prefix various different types of style messages.
>> 
>> Something like:
>> 
>> ERROR-> CODE_STYLE_DEFECT
>> WARNING -> CODE_STYLE_UNPREFERRED
>> CHECK-> CODE_STYLE_NIT
>
> I don't think you clarify anything with these changes, as they do not
> carry the requirement from a submitter's perspective. If you really
> want to change the names, I would rather suggest:
>
> ERROR -> MUST_FIX
> WARNING -> SHOULD_FIX
> CHECK -> MAY_FIX
>
> Or explain the categories in plain English, see below.
>
>> I doubt additional external documentation would help much.
>
> I agree. If anything needs to be explained, it should be included in
> the output of checkpatch directly. For example, if any ERROR was
> printed, include the following after the count summary:
>
> "ERROR means the code is infringing a core coding style rule. This MUST
> be fixed before the patch is submitted upstream."
>
> And if any WARNING was printed, include the following:
>
> "WARNING means the code is not following the best practice. This SHOULD
> be fixed before the patch is submitted upstream, unless the maintainer
> agreed otherwise."
>
> Not sure if we need something for CHECK, as these messages are not
> printed by default so I'd assume people who get them know what they
> asked for. But apparently these confused Julia so maybe a similar
> explanation would be needed for them too.

-- 
Jani Nikula, Intel Open Source Technology Center
--
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] [media] get rid of a number of problems at the cross references

[Mauro Carvalho Chehab]

As warned by linuxdoc[1] tool:

include/media/v4l2-mc.h:56 [kernel-doc WARN] : enum name from comment 
differs:  if_vid_dec_index <--> if_vid_dec_pad_index
include/media/v4l2-mc.h:71 [kernel-doc WARN] : enum name from comment 
differs:  if_aud_dec_index <--> if_aud_dec_pad_index
include/media/v4l2-mem2mem.h:396 [kernel-doc WARN] : function name from 
comment differs:  v4l2_m2m_num_src_bufs_ready <--> v4l2_m2m_num_dst_bufs_ready
drivers/media/dvb-core/dvb_math.h:28 [kernel-doc WARN] : function name from 
comment differs:  cintlog2 <--> intlog2
include/media/v4l2-subdev.h:215 [kernel-doc WARN] : struct name from 
comment differs:  s_radio <--> v4l2_subdev_tuner_ops
include/media/v4l2-subdev.h:890 [kernel-doc WARN] : function name from 
comment differs:  v4l2_set_subdevdata <--> v4l2_set_subdev_hostdata
include/media/v4l2-subdev.h:901 [kernel-doc WARN] : function name from 
comment differs:  v4l2_get_subdevdata <--> v4l2_get_subdev_hostdata
drivers/media/dvb-core/dvb_ringbuffer.h:196 [kernel-doc WARN] : function 
name from comment differs:  dvb_ringbuffer_writeuser <--> 
dvb_ringbuffer_write_user
include/media/videobuf2-core.h:399 [kernel-doc WARN] : struct name from 
comment differs:  vb2_ops <--> vb2_buf_ops
include/media/media-entity.h:132 [kernel-doc ERROR] : duplicate parameter 
definition 'source'
include/media/media-entity.h:477 [kernel-doc WARN] : function name from 
comment differs:  media_entity_enum_test <--> media_entity_enum_test_and_set
include/media/media-entity.h:535 [kernel-doc WARN] : function name from 
comment differs:  gobj_to_entity <--> gobj_to_pad
include/media/media-entity.h:544 [kernel-doc WARN] : function name from 
comment differs:  gobj_to_entity <--> gobj_to_link
include/media/media-entity.h:553 [kernel-doc WARN] : function name from 
comment differs:  gobj_to_entity <--> gobj_to_intf
include/media/media-entity.h:562 [kernel-doc WARN] : function name from 
comment differs:  gobj_to_entity <--> intf_to_devnode
include/media/rc-core.h:234 [kernel-doc WARN] : function name from comment 
differs:  rc_open <--> rc_close
include/media/v4l2-ctrls.h:397 [kernel-doc WARN] : missing initial short 
description of 'v4l2_ctrl_handler_init'
include/media/v4l2-dev.h:118 [kernel-doc WARN] : function name from comment 
differs:  v4l2_prio_close <--> v4l2_prio_check
include/media/v4l2-event.h:225 [kernel-doc WARN] : missing initial short 
description of 'v4l2_src_change_event_subscribe'

[1] https://return42.github.io/linuxdoc/linux.html

The above are real issues at the documentation. On several cases,
caused by cut-and-paste.

 Fix them.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/media/kapi/v4l2-dev.rst   |  2 +-
 drivers/media/dvb-core/dvb_math.h   |  2 +-
 drivers/media/dvb-core/dvb_ringbuffer.h |  2 +-
 include/media/media-entity.h| 13 +++--
 include/media/rc-core.h |  2 +-
 include/media/v4l2-ctrls.h  |  3 ++-
 include/media/v4l2-dev.h|  2 +-
 include/media/v4l2-event.h  |  3 ++-
 include/media/v4l2-mc.h |  4 ++--
 include/media/v4l2-mem2mem.h|  2 +-
 include/media/v4l2-subdev.h |  7 ---
 include/media/videobuf2-core.h  |  2 +-
 12 files changed, 24 insertions(+), 20 deletions(-)

diff --git a/Documentation/media/kapi/v4l2-dev.rst 
b/Documentation/media/kapi/v4l2-dev.rst
index 0a3b4503a89f..b29aa616c267 100644
--- a/Documentation/media/kapi/v4l2-dev.rst
+++ b/Documentation/media/kapi/v4l2-dev.rst
@@ -173,7 +173,7 @@ The implementation of a hotplug disconnect should also take 
the lock from
 using :c:type:`video_device`->queue->lock, then you have to first lock
 :c:type:`video_device`->queue->lock followed by :c:type:`video_device`->lock.
 That way you can be sure no ioctl is running when you call
-:c:type:`v4l2_device_disconnect`.
+:c:func:`v4l2_device_disconnect`.
 
 Video device registration
 -
diff --git a/drivers/media/dvb-core/dvb_math.h 
b/drivers/media/dvb-core/dvb_math.h
index 2f0326674ca6..4d11d3529c14 100644
--- a/drivers/media/dvb-core/dvb_math.h
+++ b/drivers/media/dvb-core/dvb_math.h
@@ -25,7 +25,7 @@
 #include 
 
 /**
- * cintlog2 - computes log2 of a value; the result is shifted left by 24 bits
+ * intlog2 - computes log2 of a value; the result is shifted left by 24 bits
  *
  * @value: The value (must be != 0)
  *
diff --git a/drivers/media/dvb-core/dvb_ringbuffer.h 
b/drivers/media/dvb-core/dvb_ringbuffer.h
index eae3f091b6a0..bbe94873d44d 100644
--- a/drivers/media/dvb-core/dvb_ringbuffer.h
+++ b/drivers/media/dvb-core/dvb_ringbuffer.h
@@ -193,7 +193,7 @@ extern ssize_t dvb_ringbuffer_write(struct dvb_ringbuffer 
*rbuf, const u8 *buf,
size_t len);
 
 /**
- * dvb_ringbuffer_writeuser - Writes a buffer received via an user pointer
+ * dvb_ringbuffer_write_user - Writes a buffer received via an user

[PATCH 01/17] Documentation/applying-patches.txt: fix a bad external link

[Mauro Carvalho Chehab]

We can't use :ref: for external links.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/applying-patches.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/applying-patches.txt 
b/Documentation/applying-patches.txt
index 02ce4924468e..3395da13d415 100644
--- a/Documentation/applying-patches.txt
+++ b/Documentation/applying-patches.txt
@@ -427,7 +427,7 @@ The -mm patches are experimental patches released by Andrew 
Morton.
 
 In the past, -mm tree were used to also test subsystem patches, but this
 function is now done via the
-:ref:`linux-next `
+`linux-next `
 tree. The Subsystem maintainers push their patches first to linux-next,
 and, during the merge window, sends them directly to Linus.
 
-- 
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 11/17] Documentation/basic_profiling.rst: convert to ReST markup

[Mauro Carvalho Chehab]

Convert it to ReST markup and add it to the user book:

- Add a title to the document;
- touch spaces/new lines to fix Sphinx format;
- use ``foo`` for commands;
- use quote blocks where needed;
- add it to the user book;

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/basic_profiling.txt  | 59 +-
 Documentation/user/basic_profiling.rst |  1 +
 Documentation/user/index.rst   |  1 +
 3 files changed, 38 insertions(+), 23 deletions(-)
 create mode 12 Documentation/user/basic_profiling.rst

diff --git a/Documentation/basic_profiling.txt 
b/Documentation/basic_profiling.txt
index 8764e9f70821..15a49dbd0189 100644
--- a/Documentation/basic_profiling.txt
+++ b/Documentation/basic_profiling.txt
@@ -1,56 +1,69 @@
+Basic kernel profiling
+==
+
+
 These instructions are deliberately very basic. If you want something clever,
-go read the real docs ;-) Please don't add more stuff, but feel free to 
+go read the real docs ;-)
+
+Please don't add more stuff, but feel free to
 correct my mistakes ;-)(mbl...@aracnet.com)
+
 Thanks to John Levon, Dave Hansen, et al. for help writing this.
 
- is the thing you're trying to measure.
-Make sure you have the correct System.map / vmlinux referenced!
+ is the thing you're trying to measure.
+Make sure you have the correct ``System.map`` / ``vmlinux`` referenced!
 
-It is probably easiest to use "make install" for linux and hack
-/sbin/installkernel to copy vmlinux to /boot, in addition to vmlinuz,
-config, System.map, which are usually installed by default.
+It is probably easiest to use ``make install`` for linux and hack
+``/sbin/installkernel`` to copy ``vmlinux`` to ``/boot``, in addition to
+``vmlinuz``, ``config``, ``System.map``, which are usually installed by 
default.
 
 Readprofile
 ---
-A recent readprofile command is needed for 2.6, such as found in util-linux
+
+A recent ``readprofile`` command is needed for 2.6, such as found in util-linux
 2.12a, which can be downloaded from:
 
-http://www.kernel.org/pub/linux/utils/util-linux/
+   http://www.kernel.org/pub/linux/utils/util-linux/
 
 Most distributions will ship it already.
 
-Add "profile=2" to the kernel command line.
+Add ``profile=2`` to the kernel command line.
 
-clear  readprofile -r
-   
-dump outputreadprofile -m /boot/System.map > captured_profile
+Some ``readprofile`` commands::
+
+   clear   readprofile -r
+   
+   dump output readprofile -m /boot/System.map > captured_profile
 
 Oprofile
 
 
 Get the source (see Changes for required version) from
-http://oprofile.sourceforge.net/ and add "idle=poll" to the kernel command
+http://oprofile.sourceforge.net/ and add ``idle=poll`` to the kernel command
 line.
 
-Configure with CONFIG_PROFILING=y and CONFIG_OPROFILE=y & reboot on new kernel
+Configure with ``CONFIG_PROFILING=y`` and ``CONFIG_OPROFILE=y`` & reboot on 
new kernel::
 
-./configure --with-kernel-support
-make install
+   ./configure --with-kernel-support
+   make install
 
 For superior results, be sure to enable the local APIC. If opreport sees
 a 0Hz CPU, APIC was not on. Be aware that idle=poll may mean a performance
 penalty.
 
-One time setup:
-   opcontrol --setup --vmlinux=/boot/vmlinux
+One time setup::
 
-clear  opcontrol --reset
-start  opcontrol --start
+   opcontrol --setup --vmlinux=/boot/vmlinux
+
+Some ``opcontrol`` commands::
+
+   clear   opcontrol --reset
+   start   opcontrol --start

-stop   opcontrol --stop
-dump outputopreport >  output_file
+   stopopcontrol --stop
+   dump output opreport >  output_file
 
-To only report on the kernel, run opreport -l /boot/vmlinux > output_file
+To only report on the kernel, run ``opreport -l /boot/vmlinux > output_file``
 
 A reset is needed to clear old statistics, which survive a reboot.
 
diff --git a/Documentation/user/basic_profiling.rst 
b/Documentation/user/basic_profiling.rst
new file mode 12
index ..5b1481ea0736
--- /dev/null
+++ b/Documentation/user/basic_profiling.rst
@@ -0,0 +1 @@
+../basic_profiling.txt
\ No newline at end of file
diff --git a/Documentation/user/index.rst b/Documentation/user/index.rst
index d4886e366b5a..6ac599ba0886 100644
--- a/Documentation/user/index.rst
+++ b/Documentation/user/index.rst
@@ -12,3 +12,4 @@ Contents:
SecurityBugs
kernel-parameters
bad_memory
+   basic_profiling
-- 
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 16/17] CodeOfConflict: add it to the development-process book

[Mauro Carvalho Chehab]

Add an extra blank line to improve its output and add it to
the development-process bookset.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/CodeOfConflict | 1 +
 Documentation/development-process/CodeOfConflict.rst | 1 +
 Documentation/development-process/index.rst  | 1 +
 3 files changed, 3 insertions(+)
 create mode 12 Documentation/development-process/CodeOfConflict.rst

diff --git a/Documentation/CodeOfConflict b/Documentation/CodeOfConflict
index 1684d0b4efa6..c498ca80fce2 100644
--- a/Documentation/CodeOfConflict
+++ b/Documentation/CodeOfConflict
@@ -19,6 +19,7 @@ please contact the Linux Foundation's Technical Advisory 
Board at
 will work to resolve the issue to the best of their ability.  For more
 information on who is on the Technical Advisory Board and what their
 role is, please see:
+
http://www.linuxfoundation.org/programs/advisory-councils/tab
 
 As a reviewer of code, please strive to keep things civil and focused on
diff --git a/Documentation/development-process/CodeOfConflict.rst 
b/Documentation/development-process/CodeOfConflict.rst
new file mode 12
index ..555f8a5d3424
--- /dev/null
+++ b/Documentation/development-process/CodeOfConflict.rst
@@ -0,0 +1 @@
+../CodeOfConflict
\ No newline at end of file
diff --git a/Documentation/development-process/index.rst 
b/Documentation/development-process/index.rst
index acb2c00fa5c1..fe765ec5b52d 100644
--- a/Documentation/development-process/index.rst
+++ b/Documentation/development-process/index.rst
@@ -24,6 +24,7 @@ Contents:
applying-patches
email-clients
SubmitChecklist
+   CodeOfConflict
adding-syscalls
 
development-process
-- 
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 15/17] Documentation/BUG-HUNTING: convert to ReST markup

[Mauro Carvalho Chehab]

- Add a document title and remove its own index;
- use monotonic fonts for paths;
- use quote blocks where needed;
- adjust/use spaces to properly format paragraphs;
- add it to the user book.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/BUG-HUNTING  | 162 +++--
 Documentation/user/BUG-HUNTING.rst |   1 +
 Documentation/user/index.rst   |   1 +
 3 files changed, 84 insertions(+), 80 deletions(-)
 create mode 12 Documentation/user/BUG-HUNTING.rst

diff --git a/Documentation/BUG-HUNTING b/Documentation/BUG-HUNTING
index 65022a87bf17..a8ef794aadae 100644
--- a/Documentation/BUG-HUNTING
+++ b/Documentation/BUG-HUNTING
@@ -1,18 +1,8 @@
-Table of contents
-=
+Bug hunting

 
 Last updated: 20 December 2005
 
-Contents
-
-
-- Introduction
-- Devices not appearing
-- Finding patch that caused a bug
--- Finding using git-bisect
--- Finding it the old way
-- Fixing the bug
-
 Introduction
 
 
@@ -24,7 +14,8 @@ Finding bugs is not always easy. Have a go though. If you 
can't find it don't
 give up. Report as much as you have found to the relevant maintainer. See
 MAINTAINERS for who that is for the subsystem you have worked on.
 
-Before you submit a bug report read REPORTING-BUGS.
+Before you submit a bug report read
+:ref:`Documentation/REPORTING-BUGS `.
 
 Devices not appearing
 =
@@ -37,15 +28,16 @@ Finding patch that caused a bug
 
 
 
-Finding using git-bisect
-
+Finding using ``git-bisect``
+
 
-Using the provided tools with git makes finding bugs easy provided the bug is
-reproducible.
+Using the provided tools with ``git`` makes finding bugs easy provided the bug
+is reproducible.
 
 Steps to do it:
+
 - start using git for the kernel source
-- read the man page for git-bisect
+- read the man page for ``git-bisect``
 - have fun
 
 Finding it the old way
@@ -58,22 +50,22 @@ It's a brute force approach but it works pretty well.
 
 You need:
 
-. A reproducible bug - it has to happen predictably (sorry)
-. All the kernel tar files from a revision that worked to the
+- A reproducible bug - it has to happen predictably (sorry)
+- All the kernel tar files from a revision that worked to the
   revision that doesn't
 
 You will then do:
 
-. Rebuild a revision that you believe works, install, and verify that.
-. Do a binary search over the kernels to figure out which one
+- Rebuild a revision that you believe works, install, and verify that.
+- Do a binary search over the kernels to figure out which one
   introduced the bug.  I.e., suppose 1.3.28 didn't have the bug, but
   you know that 1.3.69 does.  Pick a kernel in the middle and build
   that, like 1.3.50.  Build & test; if it works, pick the mid point
   between .50 and .69, else the mid point between .28 and .50.
-. You'll narrow it down to the kernel that introduced the bug.  You
+- You'll narrow it down to the kernel that introduced the bug.  You
   can probably do better than this but it gets tricky.
 
-. Narrow it down to a subdirectory
+- Narrow it down to a subdirectory
 
   - Copy kernel that works into "test".  Let's say that 3.62 works,
 but 3.63 doesn't.  So you diff -r those two kernels and come
@@ -83,7 +75,7 @@ You will then do:
 Copy the non-working directory next to the working directory
 as "dir.63".
 One directory at time, try moving the working directory to
-"dir.62" and mv dir.63 dir"time, try
+"dir.62" and mv dir.63 dir"time, try::
 
 mv dir dir.62
 mv dir.63 dir
@@ -97,15 +89,15 @@ You will then do:
 found in my case that they were self explanatory - you may
 or may not want to give up when that happens.
 
-. Narrow it down to a file
+- Narrow it down to a file
 
   - You can apply the same technique to each file in the directory,
 hoping that the changes in that file are self contained.
 
-. Narrow it down to a routine
+- Narrow it down to a routine
 
   - You can take the old file and the new file and manually create
-a merged file that has
+a merged file that has::
 
 #ifdef VER62
 routine()
@@ -120,7 +112,7 @@ You will then do:
 #endif
 
 And then walk through that file, one routine at a time and
-prefix it with
+prefix it with::
 
 #define VER62
 /* both routines here */
@@ -153,94 +145,104 @@ To debug a kernel, use objdump and look for the hex 
offset from the crash
 output to find the valid line of code/assembler. Without debug symbols, you

[PATCH 07/17] docs-rst: add documents to development-process

[Mauro Carvalho Chehab]

Add several documents to the development-process ReST book.

As we don't want renames, use symlinks instead, keeping those
documents on their original place.

Acked-by: Greg Kroah-Hartman 
Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/development-process/Changes.rst |  1 +
 Documentation/development-process/CodingStyle.rst |  1 +
 Documentation/development-process/HOWTO.rst   |  1 +
 Documentation/development-process/ManagementStyle.rst |  1 +
 Documentation/development-process/SubmitChecklist.rst |  1 +
 .../development-process/SubmittingDrivers.rst |  1 +
 .../development-process/SubmittingPatches.rst |  1 +
 .../development-process/applying-patches.rst  |  1 +
 Documentation/development-process/email-clients.rst   |  1 +
 Documentation/development-process/index.rst   | 19 +++
 Documentation/development-process/kernel-docs.rst |  1 +
 .../development-process/stable_api_nonsense.rst   |  1 +
 .../development-process/stable_kernel_rules.rst   |  1 +
 13 files changed, 31 insertions(+)
 create mode 12 Documentation/development-process/Changes.rst
 create mode 12 Documentation/development-process/CodingStyle.rst
 create mode 12 Documentation/development-process/HOWTO.rst
 create mode 12 Documentation/development-process/ManagementStyle.rst
 create mode 12 Documentation/development-process/SubmitChecklist.rst
 create mode 12 Documentation/development-process/SubmittingDrivers.rst
 create mode 12 Documentation/development-process/SubmittingPatches.rst
 create mode 12 Documentation/development-process/applying-patches.rst
 create mode 12 Documentation/development-process/email-clients.rst
 create mode 12 Documentation/development-process/kernel-docs.rst
 create mode 12 Documentation/development-process/stable_api_nonsense.rst
 create mode 12 Documentation/development-process/stable_kernel_rules.rst

diff --git a/Documentation/development-process/Changes.rst 
b/Documentation/development-process/Changes.rst
new file mode 12
index ..91698e7753f1
--- /dev/null
+++ b/Documentation/development-process/Changes.rst
@@ -0,0 +1 @@
+../Changes
\ No newline at end of file
diff --git a/Documentation/development-process/CodingStyle.rst 
b/Documentation/development-process/CodingStyle.rst
new file mode 12
index ..0377b2fe8778
--- /dev/null
+++ b/Documentation/development-process/CodingStyle.rst
@@ -0,0 +1 @@
+../CodingStyle
\ No newline at end of file
diff --git a/Documentation/development-process/HOWTO.rst 
b/Documentation/development-process/HOWTO.rst
new file mode 12
index ..10734efe8eab
--- /dev/null
+++ b/Documentation/development-process/HOWTO.rst
@@ -0,0 +1 @@
+../HOWTO
\ No newline at end of file
diff --git a/Documentation/development-process/ManagementStyle.rst 
b/Documentation/development-process/ManagementStyle.rst
new file mode 12
index ..a7d15159c108
--- /dev/null
+++ b/Documentation/development-process/ManagementStyle.rst
@@ -0,0 +1 @@
+../ManagementStyle
\ No newline at end of file
diff --git a/Documentation/development-process/SubmitChecklist.rst 
b/Documentation/development-process/SubmitChecklist.rst
new file mode 12
index ..7b75ef138e89
--- /dev/null
+++ b/Documentation/development-process/SubmitChecklist.rst
@@ -0,0 +1 @@
+../SubmitChecklist
\ No newline at end of file
diff --git a/Documentation/development-process/SubmittingDrivers.rst 
b/Documentation/development-process/SubmittingDrivers.rst
new file mode 12
index ..955fc75e6759
--- /dev/null
+++ b/Documentation/development-process/SubmittingDrivers.rst
@@ -0,0 +1 @@
+../SubmittingDrivers
\ No newline at end of file
diff --git a/Documentation/development-process/SubmittingPatches.rst 
b/Documentation/development-process/SubmittingPatches.rst
new file mode 12
index ..bd9bb84255d4
--- /dev/null
+++ b/Documentation/development-process/SubmittingPatches.rst
@@ -0,0 +1 @@
+../SubmittingPatches
\ No newline at end of file
diff --git a/Documentation/development-process/applying-patches.rst 
b/Documentation/development-process/applying-patches.rst
new file mode 12
index ..c124a067a16b
--- /dev/null
+++ b/Documentation/development-process/applying-patches.rst
@@ -0,0 +1 @@
+../applying-patches.txt
\ No newline at end of file
diff --git a/Documentation/development-process/email-clients.rst 
b/Documentation/development-process/email-clients.rst
new file mode 12
index ..b4bbad729cca
--- /dev/null
+++ b/Documentation/development-process/email-clients.rst
@@ -0,0 +1 @@
+../email-clients.txt
\ No newline at end of file
diff --git a/Documentation/development-process/index.rst 
b/Documentation/development-process/index.rst
index c37475d91090..e6faabd34ab8 100644
--- a/Documentation/development-process/index.rst
+++ b/Documentation/development-process/index.rst
@@ -1,3 +1,9 @@
+.. raw:: latex

[PATCH 09/17] Documentation/adding-syscalls.txt: convert it to ReST markup

[Mauro Carvalho Chehab]

Convert adding-syscalls.txt to ReST markup and add it to the
development-process book:

- add extra lines to make Sphinx to correctly parse paragraphs;
- use quote blocks for examples;
- use monotonic font for dirs, function calls, etc;
- mark manpage pages using the right markup;
- add cross-reference to SubmittingPatches.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/adding-syscalls.txt  | 263 +++--
 .../development-process/adding-syscalls.rst|   1 +
 Documentation/development-process/index.rst|   1 +
 3 files changed, 141 insertions(+), 124 deletions(-)
 create mode 12 Documentation/development-process/adding-syscalls.rst

diff --git a/Documentation/adding-syscalls.txt 
b/Documentation/adding-syscalls.txt
index bbb31e091b28..f5b5b1aa51b3 100644
--- a/Documentation/adding-syscalls.txt
+++ b/Documentation/adding-syscalls.txt
@@ -3,7 +3,7 @@ Adding a New System Call
 
 This document describes what's involved in adding a new system call to the
 Linux kernel, over and above the normal submission advice in
-Documentation/SubmittingPatches.
+:ref:`Documentation/SubmittingPatches `.
 
 
 System Call Alternatives
@@ -19,30 +19,33 @@ interface.
object, it may make more sense to create a new filesystem or device.  This
also makes it easier to encapsulate the new functionality in a kernel module
rather than requiring it to be built into the main kernel.
+
  - If the new functionality involves operations where the kernel notifies
userspace that something has happened, then returning a new file
descriptor for the relevant object allows userspace to use
-   poll/select/epoll to receive that notification.
- - However, operations that don't map to read(2)/write(2)-like operations
-   have to be implemented as ioctl(2) requests, which can lead to a
-   somewhat opaque API.
+   ``poll``/``select``/``epoll`` to receive that notification.
+ - However, operations that don't map to
+   :manpage:`read(2)`/:manpage:`write(2)`-like operations
+   have to be implemented as :manpage:`ioctl(2)` requests, which can lead
+   to a somewhat opaque API.
+
  - If you're just exposing runtime system information, a new node in sysfs
-   (see Documentation/filesystems/sysfs.txt) or the /proc filesystem may be
-   more appropriate.  However, access to these mechanisms requires that the
+   (see ``Documentation/filesystems/sysfs.txt``) or the ``/proc`` filesystem 
may
+   be more appropriate.  However, access to these mechanisms requires that the
relevant filesystem is mounted, which might not always be the case (e.g.
in a namespaced/sandboxed/chrooted environment).  Avoid adding any API to
debugfs, as this is not considered a 'production' interface to userspace.
  - If the operation is specific to a particular file or file descriptor, then
-   an additional fcntl(2) command option may be more appropriate.  However,
-   fcntl(2) is a multiplexing system call that hides a lot of complexity, so
+   an additional :manpage:`fcntl(2)` command option may be more appropriate.  
However,
+   :manpage:`fcntl(2)` is a multiplexing system call that hides a lot of 
complexity, so
this option is best for when the new function is closely analogous to
-   existing fcntl(2) functionality, or the new functionality is very simple
+   existing :manpage:`fcntl(2)` functionality, or the new functionality is 
very simple
(for example, getting/setting a simple flag related to a file descriptor).
  - If the operation is specific to a particular task or process, then an
-   additional prctl(2) command option may be more appropriate.  As with
-   fcntl(2), this system call is a complicated multiplexor so is best reserved
-   for near-analogs of existing prctl() commands or getting/setting a simple
-   flag related to a process.
+   additional :manpage:`prctl(2)` command option may be more appropriate.  As
+   with :manpage:`fcntl(2)`, this system call is a complicated multiplexor so
+   is best reserved for near-analogs of existing ``prctl()`` commands or
+   getting/setting a simple flag related to a process.
 
 
 Designing the API: Planning for Extension
@@ -54,15 +57,16 @@ interface on the kernel mailing list, and it's important to 
plan for future
 extensions of the interface.
 
 (The syscall table is littered with historical examples where this wasn't done,
-together with the corresponding follow-up system calls -- eventfd/eventfd2,
-dup2/dup3, inotify_init/inotify_init1,  pipe/pipe2, renameat/renameat2 -- so
+together with the corresponding follow-up system calls --
+``eventfd``/``eventfd2``, ``dup2``/``dup3``, 
``inotify_init``/``inotify_init1``,
+``pipe``/``pipe2``, ``renameat``/``renameat2`` -- so
 learn from the history of the kernel and plan for extensions from the start.)
 
 For simpler system calls that only take a couple of arguments, the preferred
 way to allow for future extensibility is to include a fl

[PATCH 10/17] Documentation/bad_memory.txt: convert it to ReST markup

[Mauro Carvalho Chehab]

- promote the section level of the document name;
- add/remove spaces/new lines where needed to format the output;
- use quote blocks.
- add it to the user book.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/bad_memory.txt  | 26 --
 Documentation/user/bad_memory.rst |  1 +
 Documentation/user/index.rst  |  1 +
 3 files changed, 18 insertions(+), 10 deletions(-)
 create mode 12 Documentation/user/bad_memory.rst

diff --git a/Documentation/bad_memory.txt b/Documentation/bad_memory.txt
index df8416213202..5cac93e27a97 100644
--- a/Documentation/bad_memory.txt
+++ b/Documentation/bad_memory.txt
@@ -1,9 +1,10 @@
+How to deal with bad memory e.g. reported by memtest86+ ?
+=
+
 March 2008
 Jan-Simon Moeller, dl...@gmx.de
 
 
-How to deal with bad memory e.g. reported by memtest86+ ?
-#
 
 There are three possibilities I know of:
 
@@ -19,6 +20,7 @@ This Howto is about number 3) .
 
 BadRAM
 ##
+
 BadRAM is the actively developed and available as kernel-patch
 here:  http://rick.vanrein.org/linux/badram/
 
@@ -31,15 +33,19 @@ memmap is already in the kernel and usable as 
kernel-parameter at
 boot-time.  Its syntax is slightly strange and you may need to
 calculate the values by yourself!
 
-Syntax to exclude a memory area (see kernel-parameters.txt for details):
-memmap=$
+Syntax to exclude a memory area (see kernel-parameters.txt for details)::
+
+   memmap=$
 
 Example: memtest86+ reported here errors at address 0x18691458, 0x18698424 and
- some others. All had 0x1869 in common, so I chose a pattern of
- 0x1869,0x.
+some others. All had 0x1869 in common, so I chose a pattern of
+0x1869,0x.
 
-With the numbers of the example above:
-memmap=64K$0x1869
- or
-memmap=0x1$0x1869
+With the numbers of the example above::
+
+   memmap=64K$0x1869
+
+or::
+
+   memmap=0x1$0x1869
 
diff --git a/Documentation/user/bad_memory.rst 
b/Documentation/user/bad_memory.rst
new file mode 12
index ..c5ffc33348f2
--- /dev/null
+++ b/Documentation/user/bad_memory.rst
@@ -0,0 +1 @@
+../bad_memory.txt
\ No newline at end of file
diff --git a/Documentation/user/index.rst b/Documentation/user/index.rst
index 280e62f21efa..d4886e366b5a 100644
--- a/Documentation/user/index.rst
+++ b/Documentation/user/index.rst
@@ -11,3 +11,4 @@ Contents:
REPORTING-BUGS
SecurityBugs
kernel-parameters
+   bad_memory
-- 
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 00/17] More files converted to ReST format

[Mauro Carvalho Chehab]

This series contain conversion of other files that, IMHO, belong to the
development-process book or to an user manual book.

Patch 1 is actually just a fixup;

Patch 2 is actually patch 28/29 from my past series that weren' t
applied because it was merging file renames on it;

Patch 3 add ReST cross references for the already converted
patches;

patches 4, 5 and 6 convert README, REPORTING-BUGS and kernel-parameter.txt
to be the basis of a Linux Kernel User' s manual;

patch 7 add the already converted text files that are meant to be
read by Linux developers at the development-process book;

patch 8 creates the Linux Kernel User' s manual.

The remaining patches convert generic documentation that, IMHO,
belongs to either the "user"  or "develoment"  book.

I'll keep working on converting those files, but we have already enough
patches to be flushed to linux-doc and LKML :)



Mauro Carvalho Chehab (17):
  Documentation/applying-patches.txt: fix a bad external link
  Documentation/email-clients.txt: convert it to ReST markup
  docs-rst: add inter-document cross references
  REPORTING-BUGS: convert to ReST markup
  README: convert it to ReST markup
  Documentation/kernel-parameters.txt: convert to ReST markup
  docs-rst: add documents to development-process
  docs-rst: create an user's manual book
  Documentation/adding-syscalls.txt: convert it to ReST markup
  Documentation/bad_memory.txt: convert it to ReST markup
  Documentation/basic_profiling.rst: convert to ReST markup
  Documentation/binfmt_misc.txt: convert it to ReST markup
  Documentation/serial-console.txt: convert it to ReST markup
  Documentation/braille-console: convert it to ReST markup
  Documentation/BUG-HUNTING: convert to ReST markup
  CodeOfConflict: add it to the development-process book
  Documentation/devices.rst: convert it to ReST markup

 Documentation/BUG-HUNTING  |  162 +--
 Documentation/CodeOfConflict   |1 +
 Documentation/SecurityBugs |   12 +-
 Documentation/SubmitChecklist  |   10 +-
 Documentation/SubmittingDrivers|7 +-
 Documentation/SubmittingPatches|   24 +-
 Documentation/adding-syscalls.txt  |  263 ++---
 Documentation/applying-patches.txt |2 +-
 Documentation/bad_memory.txt   |   26 +-
 Documentation/basic_profiling.txt  |   59 +-
 Documentation/binfmt_misc.txt  |  134 ++-
 Documentation/braille-console.txt  |   30 +-
 Documentation/development-process/Changes.rst  |1 +
 .../development-process/CodeOfConflict.rst |1 +
 Documentation/development-process/CodingStyle.rst  |1 +
 Documentation/development-process/HOWTO.rst|1 +
 .../development-process/ManagementStyle.rst|1 +
 .../development-process/SubmitChecklist.rst|1 +
 .../development-process/SubmittingDrivers.rst  |1 +
 .../development-process/SubmittingPatches.rst  |1 +
 .../development-process/adding-syscalls.rst|1 +
 .../development-process/applying-patches.rst   |1 +
 .../development-process/development-process.rst|2 +
 .../development-process/email-clients.rst  |1 +
 Documentation/development-process/index.rst|   21 +
 Documentation/development-process/kernel-docs.rst  |1 +
 .../development-process/stable_api_nonsense.rst|1 +
 .../development-process/stable_kernel_rules.rst|1 +
 Documentation/devices.txt  | 1090 ++--
 Documentation/email-clients.txt|  208 ++--
 Documentation/index.rst|1 +
 Documentation/kernel-parameters.txt|   33 +-
 Documentation/serial-console.txt   |   68 +-
 Documentation/stable_kernel_rules.txt  |7 +-
 Documentation/user/BUG-HUNTING.rst |1 +
 Documentation/user/README.rst  |1 +
 Documentation/user/REPORTING-BUGS.rst  |1 +
 Documentation/user/SecurityBugs.rst|1 +
 Documentation/user/bad_memory.rst  |1 +
 Documentation/user/basic_profiling.rst |1 +
 Documentation/user/binfmt_misc.rst |1 +
 Documentation/user/braile-console.rst  |1 +
 Documentation/user/devices.rst |1 +
 Documentation/user/index.rst   |   20 +
 Documentation/user/kernel-parameters.rst   |1 +
 Documentation/user/serial-console.rst  |1 +
 README |  105 +-
 REPORTING-BUGS |   66 +-
 48 files changed, 1297 insertions(+), 1079 deletions(-)
 create mode 12 Documentation/development-process/Changes.rst
 create mode 12 Documentation/development-process/CodeOfCo

[PATCH 06/17] Documentation/kernel-parameters.txt: convert to ReST markup

[Mauro Carvalho Chehab]

Adjust the file for it to be parsed by Sphinx:
- adjust the document title to be parsed;
- use :: for quote blocks;
- fix the horizontal bar markup;
- lower case the TODO title.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/kernel-parameters.txt | 33 +++--
 1 file changed, 19 insertions(+), 14 deletions(-)

diff --git a/Documentation/kernel-parameters.txt 
b/Documentation/kernel-parameters.txt
index 861f57514fbd..96cb618decf1 100644
--- a/Documentation/kernel-parameters.txt
+++ b/Documentation/kernel-parameters.txt
@@ -1,5 +1,5 @@
-  Kernel Parameters
-  ~
+Kernel Parameters
+~
 
 The following is a consolidated list of the kernel parameters as
 implemented by the __setup(), core_param() and module_param() macros
@@ -14,7 +14,7 @@ environment, others are passed as command line arguments to 
init.
 Everything after "--" is passed as an argument to init.
 
 Module parameters can be specified in two ways: via the kernel command
-line with a module name prefix, or via modprobe, e.g.:
+line with a module name prefix, or via modprobe, e.g.::
 
(kernel command line) usbcore.blinkenlights=1
(modprobe command line) modprobe usbcore blinkenlights=1
@@ -25,12 +25,16 @@ kernel command line (/proc/cmdline) and collects module 
parameters
 when it loads a module, so the kernel command line can be used for
 loadable modules too.
 
-Hyphens (dashes) and underscores are equivalent in parameter names, so
+Hyphens (dashes) and underscores are equivalent in parameter names, so::
+
log_buf_len=1M print-fatal-signals=1
-can also be entered as
+
+can also be entered as::
+
log-buf-len=1M print_fatal_signals=1
 
-Double-quotes can be used to protect spaces in values, e.g.:
+Double-quotes can be used to protect spaces in values, e.g.::
+
param="spaces in here"
 
 This document may not be entirely up to date and comprehensive. The command
@@ -38,12 +42,12 @@ This document may not be entirely up to date and 
comprehensive. The command
 module. Loadable modules, after being loaded into the running kernel, also
 reveal their parameters in /sys/module/${modulename}/parameters/. Some of these
 parameters may be changed at runtime by the command
-"echo -n ${value} > /sys/module/${modulename}/parameters/${parm}".
+``echo -n ${value} > /sys/module/${modulename}/parameters/${parm}``.
 
 The parameters listed below are only valid if certain kernel build options were
 enabled and if respective hardware is present. The text in square brackets at
 the beginning of each description states the restrictions within which a
-parameter is applicable:
+parameter is applicable::
 
ACPIACPI support is enabled.
AGP AGP (Accelerated Graphics Port) is enabled.
@@ -134,7 +138,7 @@ parameter is applicable:
X86_UV  SGI UV support is enabled.
XEN Xen support is enabled
 
-In addition, the following text indicates that the option:
+In addition, the following text indicates that the option::
 
BUGS=   Relates to possible processor bugs on the said processor.
KNL Is a kernel start-up parameter.
@@ -163,7 +167,7 @@ and is between 256 and 4096 characters. It is defined in 
the file
 Finally, the [KMG] suffix is commonly described after a number of kernel
 parameter values. These 'K', 'M', and 'G' letters represent the _binary_
 multipliers 'Kilo', 'Mega', and 'Giga', equalling 2^10, 2^20, and 2^30
-bytes respectively. Such letter suffixes can also be entirely omitted.
+bytes respectively. Such letter suffixes can also be entirely omitted::
 
 
acpi=   [HW,ACPI,X86,ARM64]
@@ -2479,7 +2483,7 @@ bytes respectively. Such letter suffixes can also be 
entirely omitted.
will be sent.
The default is to send the implementation identification
information.
-   
+
nfs.recover_lost_locks =
[NFSv4] Attempt to recover locks that were lost due
to a lease timeout on the server. Please note that
@@ -4124,7 +4128,7 @@ bytes respectively. Such letter suffixes can also be 
entirely omitted.
See also Documentation/input/joystick-parport.txt
 
udbg-immortal   [PPC] When debugging early kernel crashes that
-   happen after console_init() and before a proper 
+   happen after console_init() and before a proper
console driver takes over, this boot options might
help "seeing" what's going on.
 
@@ -4490,8 +4494,9 @@ bytes respectively. Such letter suffixes can also be 
entirely omitted.
Format:

,[,[,[,]]]
 
-__
+
 
-TODO:
+Todo
+
 
Add more DRM drivers.
-

[PATCH 14/17] Documentation/braille-console: convert it to ReST markup

[Mauro Carvalho Chehab]

- Fix identation for the document title;
- use monotonic fonts for paths;
- use quote blocks where needed;
- adjust spaces to properly format paragraphs;
- use :menuselection: and :kbd: for the menu item and keys;
- point too the right item at the menu;
- add it to the user book.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/braille-console.txt | 30 +-
 Documentation/serial-console.txt  |  2 ++
 Documentation/user/braile-console.rst |  1 +
 Documentation/user/index.rst  |  1 +
 4 files changed, 21 insertions(+), 13 deletions(-)
 create mode 12 Documentation/user/braile-console.rst

diff --git a/Documentation/braille-console.txt 
b/Documentation/braille-console.txt
index d0d042c2fd5e..fa3702dc04ab 100644
--- a/Documentation/braille-console.txt
+++ b/Documentation/braille-console.txt
@@ -1,33 +1,37 @@
-   Linux Braille Console
+Linux Braille Console
+=
 
 To get early boot messages on a braille device (before userspace screen
 readers can start), you first need to compile the support for the usual serial
-console (see serial-console.txt), and for braille device (in Device Drivers -
-Accessibility).
+console (see :ref:`Documentation/serial-console.txt `), and
+for braille device
+(in :menuselection:`Device Drivers --> Accessibility support --> Console on 
braille device`).
 
-Then you need to specify a console=brl, option on the kernel command line, the
-format is:
+Then you need to specify a ``console=brl``, option on the kernel command line, 
the
+format is::
 
console=brl,serial_options...
 
-where serial_options... are the same as described in serial-console.txt
+where ``serial_options...`` are the same as described in
+:ref:`Documentation/serial-console.txt `.
 
-So for instance you can use console=brl,ttyS0 if the braille device is 
connected
-to the first serial port, and console=brl,ttyS0,115200 to override the baud 
rate
-to 115200, etc.
+So for instance you can use ``console=brl,ttyS0`` if the braille device is 
connected to the first serial port, and ``console=brl,ttyS0,115200`` to
+override the baud rate to 115200, etc.
 
 By default, the braille device will just show the last kernel message (console
 mode).  To review previous messages, press the Insert key to switch to the VT
 review mode.  In review mode, the arrow keys permit to browse in the VT 
content,
-page up/down keys go at the top/bottom of the screen, and the home key goes 
back
+:kbd:`PAGE-UP`/:kbd:`PAGE-DOWN` keys go at the top/bottom of the screen, and
+the :kbd:`HOME` key goes back
 to the cursor, hence providing very basic screen reviewing facility.
 
-Sound feedback can be obtained by adding the braille_console.sound=1 kernel
+Sound feedback can be obtained by adding the ``braille_console.sound=1`` kernel
 parameter.
 
 For simplicity, only one braille console can be enabled, other uses of
-console=brl,... will be discarded.  Also note that it does not interfere with
-the console selection mechanism described in serial-console.txt
+``console=brl,...`` will be discarded.  Also note that it does not interfere 
with
+the console selection mechanism described in
+:ref:`Documentation/serial-console.txt `.
 
 For now, only the VisioBraille device is supported.
 
diff --git a/Documentation/serial-console.txt b/Documentation/serial-console.txt
index 1d9a3e48e929..a8d1e36b627a 100644
--- a/Documentation/serial-console.txt
+++ b/Documentation/serial-console.txt
@@ -1,3 +1,5 @@
+.. _serial_console:
+
 Linux Serial Console
 
 
diff --git a/Documentation/user/braile-console.rst 
b/Documentation/user/braile-console.rst
new file mode 12
index ..3a4e607a
--- /dev/null
+++ b/Documentation/user/braile-console.rst
@@ -0,0 +1 @@
+../braille-console.txt
\ No newline at end of file
diff --git a/Documentation/user/index.rst b/Documentation/user/index.rst
index 8b0afcac2a72..fe4c5b587e6f 100644
--- a/Documentation/user/index.rst
+++ b/Documentation/user/index.rst
@@ -12,6 +12,7 @@ Contents:
SecurityBugs
kernel-parameters
serial-console
+   braile-console
binfmt_misc
bad_memory
basic_profiling
-- 
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 08/17] docs-rst: create an user's manual book

[Mauro Carvalho Chehab]

Place README, REPORTING-BUGS, SecurityBugs and kernel-parameters
on an user's manual book.

As we'll be numbering the user's manual, remove the manual
numbering from SecurityBugs.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/SecurityBugs   | 12 ++--
 Documentation/index.rst  |  1 +
 Documentation/user/README.rst|  1 +
 Documentation/user/REPORTING-BUGS.rst|  1 +
 Documentation/user/SecurityBugs.rst  |  1 +
 Documentation/user/index.rst | 13 +
 Documentation/user/kernel-parameters.rst |  1 +
 7 files changed, 24 insertions(+), 6 deletions(-)
 create mode 12 Documentation/user/README.rst
 create mode 12 Documentation/user/REPORTING-BUGS.rst
 create mode 12 Documentation/user/SecurityBugs.rst
 create mode 100644 Documentation/user/index.rst
 create mode 12 Documentation/user/kernel-parameters.rst

diff --git a/Documentation/SecurityBugs b/Documentation/SecurityBugs
index 342d769834f6..df795e22d08b 100644
--- a/Documentation/SecurityBugs
+++ b/Documentation/SecurityBugs
@@ -8,8 +8,8 @@ like to know when a security bug is found so that it can be 
fixed and
 disclosed as quickly as possible.  Please report security bugs to the
 Linux kernel security team.
 
-1) Contact
---
+Contact
+---
 
 The Linux kernel security team can be contacted by email at
 .  This is a private list of security officers
@@ -23,8 +23,8 @@ REPORTING-BUGS if you are unclear about what information is 
helpful.
 Any exploit code is very helpful and will not be released without
 consent from the reporter unless it has already been made public.
 
-2) Disclosure
--
+Disclosure
+--
 
 The goal of the Linux kernel security team is to work with the
 bug submitter to bug resolution as well as disclosure.  We prefer
@@ -39,8 +39,8 @@ disclosure is from immediate (esp. if it's already publicly 
known)
 to a few weeks.  As a basic default policy, we expect report date to
 disclosure date to be on the order of 7 days.
 
-3) Non-disclosure agreements
-
+Non-disclosure agreements
+-
 
 The Linux kernel security team is not a formal body and therefore unable
 to enter any non-disclosure agreements.
diff --git a/Documentation/index.rst b/Documentation/index.rst
index d9ccb94fca95..235b6bc3a304 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -11,6 +11,7 @@ Contents:
 .. toctree::
:maxdepth: 2
 
+   user/index
kernel-documentation
development-process/index
dev-tools/tools
diff --git a/Documentation/user/README.rst b/Documentation/user/README.rst
new file mode 12
index ..3830a41184be
--- /dev/null
+++ b/Documentation/user/README.rst
@@ -0,0 +1 @@
+../../README
\ No newline at end of file
diff --git a/Documentation/user/REPORTING-BUGS.rst 
b/Documentation/user/REPORTING-BUGS.rst
new file mode 12
index ..8074a63d7596
--- /dev/null
+++ b/Documentation/user/REPORTING-BUGS.rst
@@ -0,0 +1 @@
+../../REPORTING-BUGS
\ No newline at end of file
diff --git a/Documentation/user/SecurityBugs.rst 
b/Documentation/user/SecurityBugs.rst
new file mode 12
index ..fa5504256c04
--- /dev/null
+++ b/Documentation/user/SecurityBugs.rst
@@ -0,0 +1 @@
+../SecurityBugs
\ No newline at end of file
diff --git a/Documentation/user/index.rst b/Documentation/user/index.rst
new file mode 100644
index ..280e62f21efa
--- /dev/null
+++ b/Documentation/user/index.rst
@@ -0,0 +1,13 @@
+Linux Kernel User's Documentation
+=
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+   :numbered:
+
+   README
+   REPORTING-BUGS
+   SecurityBugs
+   kernel-parameters
diff --git a/Documentation/user/kernel-parameters.rst 
b/Documentation/user/kernel-parameters.rst
new file mode 12
index ..eea97c5ac948
--- /dev/null
+++ b/Documentation/user/kernel-parameters.rst
@@ -0,0 +1 @@
+../kernel-parameters.txt
\ No newline at end of file
-- 
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 12/17] Documentation/binfmt_misc.txt: convert it to ReST markup

[Mauro Carvalho Chehab]

- Fix identation for the document title;
- use monotonic fonts for commands, paths, etc;
- use quote blocks where needed;
- adjust spaces to properly format paragraphs;
- add it to the user book.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/binfmt_misc.txt  | 134 +
 Documentation/user/binfmt_misc.rst |   1 +
 Documentation/user/index.rst   |   1 +
 3 files changed, 79 insertions(+), 57 deletions(-)
 create mode 12 Documentation/user/binfmt_misc.rst

diff --git a/Documentation/binfmt_misc.txt b/Documentation/binfmt_misc.txt
index ec83bbce547a..9c5ff8f260bf 100644
--- a/Documentation/binfmt_misc.txt
+++ b/Documentation/binfmt_misc.txt
@@ -1,5 +1,5 @@
- Kernel Support for miscellaneous (your favourite) Binary Formats v1.1
- =
+Kernel Support for miscellaneous (your favourite) Binary Formats v1.1
+=
 
 This Kernel feature allows you to invoke almost (for restrictions see below)
 every program by simply typing its name in the shell.
@@ -9,122 +9,142 @@ To achieve this you must tell binfmt_misc which interpreter 
has to be invoked
 with which binary. Binfmt_misc recognises the binary-type by matching some 
bytes
 at the beginning of the file with a magic byte sequence (masking out specified
 bits) you have supplied. Binfmt_misc can also recognise a filename extension
-aka '.com' or '.exe'.
+aka ``.com`` or ``.exe``.
 
-First you must mount binfmt_misc:
-   mount binfmt_misc -t binfmt_misc /proc/sys/fs/binfmt_misc 
+First you must mount binfmt_misc::
+
+   mount binfmt_misc -t binfmt_misc /proc/sys/fs/binfmt_misc
 
 To actually register a new binary type, you have to set up a string looking 
like
-:name:type:offset:magic:mask:interpreter:flags (where you can choose the ':'
-upon your needs) and echo it to /proc/sys/fs/binfmt_misc/register.
+``:name:type:offset:magic:mask:interpreter:flags`` (where you can choose the
+``:`` upon your needs) and echo it to ``/proc/sys/fs/binfmt_misc/register``.
 
 Here is what the fields mean:
- - 'name' is an identifier string. A new /proc file will be created with this
-   name below /proc/sys/fs/binfmt_misc; cannot contain slashes '/' for obvious
-   reasons.
- - 'type' is the type of recognition. Give 'M' for magic and 'E' for extension.
- - 'offset' is the offset of the magic/mask in the file, counted in bytes. This
-   defaults to 0 if you omit it (i.e. you write ':name:type::magic...'). 
Ignored
-   when using filename extension matching.
- - 'magic' is the byte sequence binfmt_misc is matching for. The magic string
-   may contain hex-encoded characters like \x0a or \xA4. Note that you must
-   escape any NUL bytes; parsing halts at the first one. In a shell environment
-   you might have to write \\x0a to prevent the shell from eating your \.
+
+- ``name``
+   is an identifier string. A new /proc file will be created with this
+   ``name below /proc/sys/fs/binfmt_misc``; cannot contain slashes ``/`` for
+   obvious reasons.
+- ``type``
+   is the type of recognition. Give ``M`` for magic and ``E`` for extension.
+- ``offset``
+   is the offset of the magic/mask in the file, counted in bytes. This
+   defaults to 0 if you omit it (i.e. you write ``:name:type::magic...``).
+   Ignored when using filename extension matching.
+- ``magic``
+   is the byte sequence binfmt_misc is matching for. The magic string
+   may contain hex-encoded characters like ``\x0a`` or ``\xA4``. Note that you
+   must escape any NUL bytes; parsing halts at the first one. In a shell
+   environment you might have to write ``\\x0a`` to prevent the shell from
+   eating your ``\``.
If you chose filename extension matching, this is the extension to be
-   recognised (without the '.', the \x0a specials are not allowed). Extension
-   matching is case sensitive, and slashes '/' are not allowed!
- - 'mask' is an (optional, defaults to all 0xff) mask. You can mask out some
+   recognised (without the ``.``, the ``\x0a`` specials are not allowed).
+   Extensionmatching is case sensitive, and slashes ``/`` are not allowed!
+- ``mask``
+   is an (optional, defaults to all 0xff) mask. You can mask out some
bits from matching by supplying a string like magic and as long as magic.
The mask is anded with the byte sequence of the file. Note that you must
escape any NUL bytes; parsing halts at the first one. Ignored when using
filename extension matching.
- - 'interpreter' is the program that should be invoked with the binary as first
+- ``interpreter``
+   is the program that should be invoked with the binary as first
argument (specify the full path)
- - 'flags' is an optional field that controls several aspects of the invocation
+- ``flags``
+   is an optional field that controls several aspects of the invocation
of the interpreter. It is a string of capital letters, each c

[PATCH 04/17] REPORTING-BUGS: convert to ReST markup

[Mauro Carvalho Chehab]

- add a title to the document;
- use :: before verbatim blocks;
- add blank lines where required;
- use protocol for URL references;
- use a verbatim block for the bugs template;
- add cross references to SecurityBugs.

Signed-off-by: Mauro Carvalho Chehab 
---
 REPORTING-BUGS | 66 --
 1 file changed, 37 insertions(+), 29 deletions(-)

diff --git a/REPORTING-BUGS b/REPORTING-BUGS
index 914baf9cf5fa..05c53ac7fa76 100644
--- a/REPORTING-BUGS
+++ b/REPORTING-BUGS
@@ -1,3 +1,8 @@
+.. _reportingbugs:
+
+Reporting bugs
+++
+
 Background
 ==
 
@@ -50,12 +55,13 @@ maintainer replies to you, make sure to 'Reply-all' in 
order to keep the
 public mailing list(s) in the email thread.
 
 If you know which driver is causing issues, you can pass one of the driver
-files to the get_maintainer.pl script:
+files to the get_maintainer.pl script::
+
  perl scripts/get_maintainer.pl -f 
 
 If it is a security bug, please copy the Security Contact listed in the
 MAINTAINERS file.  They can help coordinate bugfix and disclosure.  See
-Documentation/SecurityBugs for more information.
+:ref:`Documentation/SecurityBugs ` for more information.
 
 If you can't figure out which subsystem caused the issue, you should file
 a bug in kernel.org bugzilla and send email to
@@ -69,8 +75,9 @@ Tips for reporting bugs
 
 If you haven't reported a bug before, please read:
 
-http://www.chiark.greenend.org.uk/~sgtatham/bugs.html
-http://www.catb.org/esr/faqs/smart-questions.html
+   http://www.chiark.greenend.org.uk/~sgtatham/bugs.html
+
+   http://www.catb.org/esr/faqs/smart-questions.html
 
 It's REALLY important to report bugs that seem unrelated as separate email
 threads or separate bugzilla entries.  If you report several unrelated
@@ -99,34 +106,34 @@ relevant to your bug, feel free to exclude it.
 
 First run the ver_linux script included as scripts/ver_linux, which
 reports the version of some important subsystems.  Run this script with
-the command "sh scripts/ver_linux".
+the command ``sh scripts/ver_linux``.
 
 Use that information to fill in all fields of the bug report form, and
 post it to the mailing list with a subject of "PROBLEM: " for easy identification by the developers.
+summary from [1.]>" for easy identification by the developers::
 
-[1.] One line summary of the problem:
-[2.] Full description of the problem/report:
-[3.] Keywords (i.e., modules, networking, kernel):
-[4.] Kernel information
-[4.1.] Kernel version (from /proc/version):
-[4.2.] Kernel .config file:
-[5.] Most recent kernel version which did not have the bug:
-[6.] Output of Oops.. message (if applicable) with symbolic information
- resolved (see Documentation/oops-tracing.txt)
-[7.] A small shell script or example program which triggers the
- problem (if possible)
-[8.] Environment
-[8.1.] Software (add the output of the ver_linux script here)
-[8.2.] Processor information (from /proc/cpuinfo):
-[8.3.] Module information (from /proc/modules):
-[8.4.] Loaded driver and hardware information (/proc/ioports, /proc/iomem)
-[8.5.] PCI information ('lspci -vvv' as root)
-[8.6.] SCSI information (from /proc/scsi/scsi)
-[8.7.] Other information that might be relevant to the problem
-   (please look in /proc and include all information that you
-   think to be relevant):
-[X.] Other notes, patches, fixes, workarounds:
+  [1.] One line summary of the problem:
+  [2.] Full description of the problem/report:
+  [3.] Keywords (i.e., modules, networking, kernel):
+  [4.] Kernel information
+  [4.1.] Kernel version (from /proc/version):
+  [4.2.] Kernel .config file:
+  [5.] Most recent kernel version which did not have the bug:
+  [6.] Output of Oops.. message (if applicable) with symbolic information
+   resolved (see Documentation/oops-tracing.txt)
+  [7.] A small shell script or example program which triggers the
+   problem (if possible)
+  [8.] Environment
+  [8.1.] Software (add the output of the ver_linux script here)
+  [8.2.] Processor information (from /proc/cpuinfo):
+  [8.3.] Module information (from /proc/modules):
+  [8.4.] Loaded driver and hardware information (/proc/ioports, /proc/iomem)
+  [8.5.] PCI information ('lspci -vvv' as root)
+  [8.6.] SCSI information (from /proc/scsi/scsi)
+  [8.7.] Other information that might be relevant to the problem
+ (please look in /proc and include all information that you
+ think to be relevant):
+  [X.] Other notes, patches, fixes, workarounds:
 
 
 Follow up
@@ -153,7 +160,8 @@ Expectations for kernel maintainers
 Linux kernel maintainers are busy, overworked human beings.  Some times
 they may not be able to address your bug in a day, a week, or two weeks.
 If they don't answer your email, they may be on vacation, or at a Linux
-conference.  Check the conference schedule at LWN.net for more info:
+conference.  Check the conference schedule at https://LWN.net for more info:
+
ht

[PATCH 02/17] Documentation/email-clients.txt: convert it to ReST markup

[Mauro Carvalho Chehab]

As this file is mentioned at the development-process/ book,
let's convert it to ReST markup.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/email-clients.txt | 208 ++--
 1 file changed, 114 insertions(+), 94 deletions(-)

diff --git a/Documentation/email-clients.txt b/Documentation/email-clients.txt
index 2d485dea8cec..ac892b30815e 100644
--- a/Documentation/email-clients.txt
+++ b/Documentation/email-clients.txt
@@ -1,23 +1,27 @@
+.. _email_clients:
+
 Email clients info for Linux
-==
+
 
 Git
---
-These days most developers use `git send-email` instead of regular
+---
+
+These days most developers use ``git send-email`` instead of regular
 email clients.  The man page for this is quite good.  On the receiving
-end, maintainers use `git am` to apply the patches.
+end, maintainers use ``git am`` to apply the patches.
 
-If you are new to git then send your first patch to yourself.  Save it
-as raw text including all the headers.  Run `git am raw_email.txt` and
-then review the changelog with `git log`.  When that works then send
+If you are new to ``git`` then send your first patch to yourself.  Save it
+as raw text including all the headers.  Run ``git am raw_email.txt`` and
+then review the changelog with ``git log``.  When that works then send
 the patch to the appropriate mailing list(s).
 
 General Preferences
---
+---
+
 Patches for the Linux kernel are submitted via email, preferably as
 inline text in the body of the email.  Some maintainers accept
 attachments, but then the attachments should have content-type
-"text/plain".  However, attachments are generally frowned upon because
+``text/plain``.  However, attachments are generally frowned upon because
 it makes quoting portions of the patch more difficult in the patch
 review process.
 
@@ -25,7 +29,7 @@ Email clients that are used for Linux kernel patches should 
send the
 patch text untouched.  For example, they should not modify or delete tabs
 or spaces, even at the beginning or end of lines.
 
-Don't send patches with "format=flowed".  This can cause unexpected
+Don't send patches with ``format=flowed``.  This can cause unexpected
 and unwanted line breaks.
 
 Don't let your email client do automatic word wrapping for you.
@@ -54,57 +58,63 @@ mailing lists.
 
 
 Some email client (MUA) hints
---
+-
+
 Here are some specific MUA configuration hints for editing and sending
 patches for the Linux kernel.  These are not meant to be complete
 software package configuration summaries.
 
+
 Legend:
-TUI = text-based user interface
-GUI = graphical user interface
 
-~~
+- TUI = text-based user interface
+- GUI = graphical user interface
+
 Alpine (TUI)
+
 
 Config options:
-In the "Sending Preferences" section:
 
-- "Do Not Send Flowed Text" must be enabled
-- "Strip Whitespace Before Sending" must be disabled
+In the :menuselection:`Sending Preferences` section:
+
+- :menuselection:`Do Not Send Flowed Text` must be ``enabled``
+- :menuselection:`Strip Whitespace Before Sending` must be ``disabled``
 
 When composing the message, the cursor should be placed where the patch
-should appear, and then pressing CTRL-R let you specify the patch file
+should appear, and then pressing :kbd:`CTRL-R` let you specify the patch file
 to insert into the message.
 
-~~
 Claws Mail (GUI)
+
 
 Works. Some people use this successfully for patches.
 
-To insert a patch use Message->Insert File (CTRL+i) or an external editor.
+To insert a patch use :menuselection:`Message-->Insert` File (:kbd:`CTRL-I`)
+or an external editor.
 
 If the inserted patch has to be edited in the Claws composition window
-"Auto wrapping" in Configuration->Preferences->Compose->Wrapping should be
+"Auto wrapping" in
+:menuselection:`Configuration-->Preferences-->Compose-->Wrapping` should be
 disabled.
 
-~~
 Evolution (GUI)
+***
 
 Some people use this successfully for patches.
 
 When composing mail select: Preformat
-  from Format->Paragraph Style->Preformatted (Ctrl-7)
+  from :menuselection:`Format-->Paragraph Style-->Preformatted` (:kbd:`CTRL-7`)
   or the toolbar
 
 Then use:
-  Insert->Text File... (Alt-n x)
+:menuselection:`Insert-->Text File...` (:kbd:`ALT-N x`)
 to insert the patch.
 
-You can also "diff -Nru old.c new.c | xclip", select Preformat, then
-paste with the middle button.
+You can also ``diff -Nru old.c new.c | xclip``, select
+:menuselection:`Preformat`, then paste with the middle button.
 
-~~~

[PATCH 05/17] README: convert it to ReST markup

[Mauro Carvalho Chehab]

Adjust the readme file for it to use the ReST markup:

- add chapter/section markups;
- use ``foo`` for commands;
- use :: for verbatim and script blocks;
- replace unsupported markup _foo_ by **foo**;
- add cross-references to other ReST files;
- use lower case on the section titles, to match other ReST files.

Signed-off-by: Mauro Carvalho Chehab 
---
 README | 105 -
 1 file changed, 58 insertions(+), 47 deletions(-)

diff --git a/README b/README
index 09f34f78f2bb..3335b3b2973a 100644
--- a/README
+++ b/README
@@ -1,10 +1,12 @@
-Linux kernel release 4.x 
+Linux kernel release 4.x 
+=
 
 These are the release notes for Linux version 4.  Read them carefully,
 as they tell you what this is all about, explain how to install the
 kernel, and what to do if something goes wrong.
 
-WHAT IS LINUX?
+What is Linux?
+--
 
   Linux is a clone of the operating system Unix, written from scratch by
   Linus Torvalds with assistance from a loosely-knit team of hackers across
@@ -18,7 +20,8 @@ WHAT IS LINUX?
   It is distributed under the GNU General Public License - see the
   accompanying COPYING file for more details.
 
-ON WHAT HARDWARE DOES IT RUN?
+On what hardware does it run?
+-
 
   Although originally developed first for 32-bit x86-based PCs (386 or higher),
   today Linux also runs on (at least) the Compaq Alpha AXP, Sun SPARC and
@@ -34,7 +37,8 @@ ON WHAT HARDWARE DOES IT RUN?
   Linux has also been ported to itself. You can now run the kernel as a
   userspace application - this is called UserMode Linux (UML).
 
-DOCUMENTATION:
+Documentation
+-
 
  - There is a lot of documentation available both in electronic form on
the Internet and in books, both Linux-specific and pertaining to
@@ -53,14 +57,15 @@ DOCUMENTATION:
  - The Documentation/DocBook/ subdirectory contains several guides for
kernel developers and users.  These guides can be rendered in a
number of formats:  PostScript (.ps), PDF, HTML, & man-pages, among others.
-   After installation, "make psdocs", "make pdfdocs", "make htmldocs",
-   or "make mandocs" will render the documentation in the requested format.
+   After installation, ``make psdocs``, ``make pdfdocs``, ``make htmldocs``,
+   or ``make mandocs`` will render the documentation in the requested format.
 
-INSTALLING the kernel source:
+Installing the kernel source
+
 
  - If you install the full sources, put the kernel tarball in a
directory where you have permissions (e.g. your home directory) and
-   unpack it:
+   unpack it::
 
  xz -cd linux-4.X.tar.xz | tar xvf -
 
@@ -74,12 +79,12 @@ INSTALLING the kernel source:
  - You can also upgrade between 4.x releases by patching.  Patches are
distributed in the xz format.  To install by patching, get all the
newer patch files, enter the top level directory of the kernel source
-   (linux-4.X) and execute:
+   (linux-4.X) and execute::
 
  xz -cd ../patch-4.x.xz | patch -p1
 
Replace "x" for all versions bigger than the version "X" of your current
-   source tree, _in_order_, and you should be ok.  You may want to remove
+   source tree, **in_order**, and you should be ok.  You may want to remove
the backup files (some-file-name~ or some-file-name.orig), and make sure
that there are no failed patches (some-file-name# or some-file-name.rej).
If there are, either you or I have made a mistake.
@@ -90,12 +95,12 @@ INSTALLING the kernel source:
and you want to apply the 4.0.3 patch, you must not first apply the 4.0.1
and 4.0.2 patches. Similarly, if you are running kernel version 4.0.2 and
want to jump to 4.0.3, you must first reverse the 4.0.2 patch (that is,
-   patch -R) _before_ applying the 4.0.3 patch. You can read more on this in
-   Documentation/applying-patches.txt
+   patch -R) **before** applying the 4.0.3 patch. You can read more on this in
+   :ref:`Documentation/applying-patches.txt `.
 
Alternatively, the script patch-kernel can be used to automate this
process.  It determines the current kernel version and applies any
-   patches found.
+   patches found::
 
  linux/scripts/patch-kernel linux
 
@@ -103,55 +108,58 @@ INSTALLING the kernel source:
kernel source.  Patches are applied from the current directory, but
an alternative directory can be specified as the second argument.
 
- - Make sure you have no stale .o files and dependencies lying around:
+ - Make sure you have no stale .o files and dependencies lying around::
 
  cd linux
  make mrproper
 
You should now have the sources correctly installed.
 
-SOFTWARE REQUIREMENTS
+Software requirements
+-
 
Compiling and running the 4.x kernels requires up-to-date
versions of various software packages.  Consult
-   Documentation/

[PATCH 03/17] docs-rst: add inter-document cross references

[Mauro Carvalho Chehab]

Add cross references for the development process documents
that were converted to ReST:
Documentation/SubmitChecklist
Documentation/SubmittingDrivers
Documentation/SubmittingPatches
Documentation/development-process/development-process.rst
Documentation/stable_kernel_rules.txt

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/SubmitChecklist  | 10 +
 Documentation/SubmittingDrivers|  7 ---
 Documentation/SubmittingPatches| 24 ++
 .../development-process/development-process.rst|  2 ++
 Documentation/stable_kernel_rules.txt  |  7 +--
 5 files changed, 32 insertions(+), 18 deletions(-)

diff --git a/Documentation/SubmitChecklist b/Documentation/SubmitChecklist
index 22a370ff34e5..894289b22b15 100644
--- a/Documentation/SubmitChecklist
+++ b/Documentation/SubmitChecklist
@@ -1,3 +1,5 @@
+.. _submitchecklist:
+
 Linux Kernel patch submission checklist
 ~~~
 
@@ -5,7 +7,7 @@ Here are some basic things that developers should do if they 
want to see their
 kernel patch submissions accepted more quickly.
 
 These are all above and beyond the documentation that is provided in
-Documentation/SubmittingPatches
+:ref:`Documentation/SubmittingPatches `
 and elsewhere regarding submitting Linux kernel patches.
 
 
@@ -28,8 +30,8 @@ and elsewhere regarding submitting Linux kernel patches.
 4) ppc64 is a good architecture for cross-compilation checking because it
tends to use ``unsigned long`` for 64-bit quantities.
 
-5: Check your patch for general style as detailed in
-   Documentation/CodingStyle.
+5) Check your patch for general style as detailed in
+   :ref:`Documentation/CodingStyle `.
Check for trivial violations with the patch style checker prior to
submission (``scripts/checkpatch.pl``).
You should be able to justify all violations that remain in
@@ -54,7 +56,7 @@ and elsewhere regarding submitting Linux kernel patches.
but any one function that uses more than 512 bytes on the stack is a
candidate for change.
 
-11: Include :ref:`kernel-doc ` to document global  kernel APIs.
+11) Include :ref:`kernel-doc ` to document global  kernel APIs.
 (Not required for static functions, but OK there also.) Use
 ``make htmldocs`` or ``make pdfdocs`` to check the
 :ref:`kernel-doc ` and fix any issues.
diff --git a/Documentation/SubmittingDrivers b/Documentation/SubmittingDrivers
index 2ac931645e53..252b77a23fad 100644
--- a/Documentation/SubmittingDrivers
+++ b/Documentation/SubmittingDrivers
@@ -40,9 +40,9 @@ Linux 2.4:
maintainer does not respond or you cannot find the appropriate
maintainer then please contact Willy Tarreau .
 
-Linux 2.6:
+Linux 2.6 and upper:
The same rules apply as 2.4 except that you should follow linux-kernel
-   to track changes in API's. The final contact point for Linux 2.6
+   to track changes in API's. The final contact point for Linux 2.6+
submissions is Andrew Morton.
 
 What Criteria Determine Acceptance
@@ -73,7 +73,8 @@ Interfaces:
 
 Code:
Please use the Linux style of code formatting as documented
-   in Documentation/CodingStyle. If you have sections of code
+   in :ref:`Documentation/CodingStyle `.
+   If you have sections of code
that need to be in other formats, for example because they
are shared with a windows driver kit and you want to
maintain them just once separate them out nicely and note
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 9c3dfa7babf3..36f1dedc944c 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -10,10 +10,12 @@ can greatly increase the chances of your change being 
accepted.
 
 This document contains a large number of suggestions in a relatively terse
 format.  For detailed information on how the kernel development process
-works, see Documentation/development-process.  Also, read
-Documentation/SubmitChecklist for a list of items to check before
+works, see :ref:`Documentation/development-process `.
+Also, read :ref:`Documentation/SubmitChecklist `
+for a list of items to check before
 submitting code.  If you are submitting a driver, also read
-Documentation/SubmittingDrivers; for device tree binding patches, read
+:ref:`Documentation/SubmittingDrivers `;
+for device tree binding patches, read
 Documentation/devicetree/bindings/submitting-patches.txt.
 
 Many of these steps describe the default behavior of the ``git`` version
@@ -235,7 +237,9 @@ then only post say 15 or so at a time and wait for review 
and integration.
 ---
 
 Check your patch for basic style violations, details of which can be
-found in Documentation/CodingStyle.  Failure to do so simply wastes
+found in
+:ref:`Documentatio

[PATCH 13/17] Documentation/serial-console.txt: convert it to ReST markup

[Mauro Carvalho Chehab]

- Fix identation for the document title;
- use monotonic fonts for paths;
- use quote blocks where needed;
- adjust spaces to properly format paragraphs;
- use :menuselection: for the menu item;
- add it to the user book.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/serial-console.txt  | 66 +++
 Documentation/user/index.rst  |  1 +
 Documentation/user/serial-console.rst |  1 +
 3 files changed, 37 insertions(+), 31 deletions(-)
 create mode 12 Documentation/user/serial-console.rst

diff --git a/Documentation/serial-console.txt b/Documentation/serial-console.txt
index 9a7bc8b3f479..1d9a3e48e929 100644
--- a/Documentation/serial-console.txt
+++ b/Documentation/serial-console.txt
@@ -1,15 +1,19 @@
-   Linux Serial Console
+Linux Serial Console
+
 
 To use a serial port as console you need to compile the support into your
 kernel - by default it is not compiled in. For PC style serial ports
-it's the config option next to "Standard/generic (dumb) serial support".
+it's the config option next to menu option:
+
+:menuselection:`Character devices --> Serial drivers --> 8250/16550 and 
compatible serial support --> Console on 8250/16550 and compatible serial port`
+
 You must compile serial support into the kernel and not as a module.
 
 It is possible to specify multiple devices for console output. You can
 define a new kernel command line option to select which device(s) to
 use for console output.
 
-The format of this option is:
+The format of this option is::
 
console=device,options
 
@@ -28,11 +32,11 @@ The format of this option is:
 
 You can specify multiple console= options on the kernel command line.
 Output will appear on all of them. The last device will be used when
-you open /dev/console. So, for example:
+you open ``/dev/console``. So, for example::
 
console=ttyS1,9600 console=tty0
 
-defines that opening /dev/console will get you the current foreground
+defines that opening ``/dev/console`` will get you the current foreground
 virtual console, and kernel messages will appear on both the VGA
 console and the 2nd serial port (ttyS1 or COM2) at 9600 baud.
 
@@ -44,61 +48,61 @@ first looks for a VGA card and then for a serial port. So 
if you don't
 have a VGA card in your system the first serial port will automatically
 become the console.
 
-You will need to create a new device to use /dev/console. The official
-/dev/console is now character device 5,1.
+You will need to create a new device to use ``/dev/console``. The official
+``/dev/console`` is now character device 5,1.
 
 (You can also use a network device as a console.  See
-Documentation/networking/netconsole.txt for information on that.)
+``Documentation/networking/netconsole.txt`` for information on that.)
 
-Here's an example that will use /dev/ttyS1 (COM2) as the console.
+Here's an example that will use ``/dev/ttyS1`` (COM2) as the console.
 Replace the sample values as needed.
 
-1. Create /dev/console (real console) and /dev/tty0 (master virtual
-   console):
+1. Create ``/dev/console`` (real console) and ``/dev/tty0`` (master virtual
+   console)::
 
-   cd /dev
-   rm -f console tty0
-   mknod -m 622 console c 5 1
-   mknod -m 622 tty0 c 4 0
+ cd /dev
+ rm -f console tty0
+ mknod -m 622 console c 5 1
+ mknod -m 622 tty0 c 4 0
 
 2. LILO can also take input from a serial device. This is a very
useful option. To tell LILO to use the serial port:
-   In lilo.conf (global section): 
+   In lilo.conf (global section)::
 
-   serial  = 1,9600n8 (ttyS1, 9600 bd, no parity, 8 bits)
+ serial  = 1,9600n8 (ttyS1, 9600 bd, no parity, 8 bits)
 
 3. Adjust to kernel flags for the new kernel,
-   again in lilo.conf (kernel section)
+   again in lilo.conf (kernel section)::
 
-   append = "console=ttyS1,9600" 
+ append = "console=ttyS1,9600"
 
 4. Make sure a getty runs on the serial port so that you can login to
it once the system is done booting. This is done by adding a line
-   like this to /etc/inittab (exact syntax depends on your getty):
+   like this to ``/etc/inittab`` (exact syntax depends on your getty)::
 
-   S1:23:respawn:/sbin/getty -L ttyS1 9600 vt100
+ S1:23:respawn:/sbin/getty -L ttyS1 9600 vt100
 
-5. Init and /etc/ioctl.save
+5. Init and ``/etc/ioctl.save``
 
-   Sysvinit remembers its stty settings in a file in /etc, called
-   `/etc/ioctl.save'. REMOVE THIS FILE before using the serial
+   Sysvinit remembers its stty settings in a file in ``/etc``, called
+   ``/etc/ioctl.save``. REMOVE THIS FILE before using the serial
console for the first time, because otherwise init will probably
set the baudrate to 38400 (baudrate of the virtual console).
 
-6. /dev/console and X
+6. ``/dev/console`` and X
Programs that want to do something with the virtual console usually
-   open /dev/console. If you have created the new /dev/console device,
+   open ``/dev/console``. If you

Re: "CodingStyle: Clarify and complete chapter 7" in docs-next

[Jean Delvare]

On Thu, 22 Sep 2016 03:42:10 -0700, Joe Perches wrote:
> On Thu, 2016-09-22 at 11:24 +0200, Jean Delvare wrote:
> > I would rather suggest:
> > 
> > ERROR -> MUST_FIX
> > WARNING -> SHOULD_FIX
> > CHECK -> MAY_FIX
> 
> MUST is much stronger language than I would prefer.

That's what error means, really. When your compiler fails with an
error, you have no choice but to fix your code. Warnings on the other
hand may be ignored sometimes.

> There are still about a quarter million ERRORs just for
> spacing issues in the kernel tree.
> 
> Here are the top 10 ERROR checkpatch messages treewide as of
> a few days ago,
> 
> $ grep ERROR checkpatch.short_sorted_20160917
>  268308  ERROR:SPACING
>   37340  ERROR:CODE_INDENT
>   27678  ERROR:TRAILING_WHITESPACE
>   21024  ERROR:COMPLEX_MACRO
>   14048  ERROR:POINTER_LOCATION
>   12207  ERROR:TRAILING_STATEMENTS
>   11079  ERROR:OPEN_BRACE
>6802  ERROR:ASSIGN_IN_IF
>3940  ERROR:RETURN_PARENTHESES
>2322  ERROR:NON_OCTAL_PERMISSIONS
> 
> Maybe there could be some better classifications of the various
> messages.
> 
> But there are about two million checkpatch messages overall in
> the kernel tree.
> 
> That's a lot.

Sure. But I'm afraid you keep changing topics and I have no idea where
you are going. We started with "should there be a space before jump
labels", then out of nowhere we were discussing the wording of the
output of checkpatch (how is that related?) and now you pull statistics
out of your hat, like these numbers imply anything.

checkpatch was called checkPATCH for a reason. It's main intent was to
prevent NEW (coding-style mostly) errors from creeping into the kernel.
The fact that old code does now always follow these recommendations is
unfortunate but that doesn't make checkpatch wrong or bad.

ERROR means that the new code isn't allowed to do that. Period.

-- 
Jean Delvare
SUSE L3 Support
--
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-rst:c-domain: fix some issues in the c-domain

[Mauro Carvalho Chehab]

Em Tue, 20 Sep 2016 20:56:35 +0200
Markus Heiser  escreveu:

> > If I understood it right, I could do something like:
> > 
> > diff --git a/Documentation/media/conf_nitpick.py 
> > b/Documentation/media/conf_nitpick.py
> > index 480d548af670..2de603871536 100644
> > --- a/Documentation/media/conf_nitpick.py
> > +++ b/Documentation/media/conf_nitpick.py
> > @@ -107,3 +107,9 @@ nitpick_ignore = [
> > 
> > ("c:type", "v4l2_m2m_dev"),
> > ]
> > +
> > +
> > +extensions.append("linuxdoc.rstKernelDoc")
> > +extensions.append("linuxdoc.rstFlatTable")
> > +extensions.append("linuxdoc.kernel_include")
> > +extensions.append("linuxdoc.manKernelDoc")
> > 
> > Right?  
> 
> No ;)

> > It would be good to do some sort of logic on the
> > above for it to automatically include it, if linuxdoc is
> > present, otherwise print a warning and do "just" the normal
> > Sphinx tests.  
> 
> The intention is; with installing the linuxdoc project you get
> some nice command line tools, like lint for free and if you want
> to see how the linuxdoc project compiles your kernel documentation
> and how e.g. man pages are build or what warnings are spit, you
> have to **replace** the extensions from the kernel's source with
> the one from the linuxdoc project.
> 
> This is done by patching the build scripts as described in:
> 
>   https://return42.github.io/linuxdoc/linux.html
> 
> FYI: I updated the documentation of the linuxdoc project.

Hmm... It would be a way better to just do something like the
above patch, specially since a conf_lint.py could have the
modified conf_nitpick.py, and avoiding touching at the
tree. The need of making a patch to use it, touching at the
building system prevents it to be called for every applied
patch that would touch on a documented header file.

I used the above to detect some cut-and-paste issues with some
documentation.

Yet, from what I saw, the parsers of lint still need some work,
as it didn't parse some stuff at the media headers that seem ok.

> In this project I develop and maintain "future" concepts like
> man-page builder and the py-version of the kernel-doc parser. 

The new parser seems to have some bugs, like those:

$ kernel-lintdoc include/media/v4l2-ctrls.h
include/media/v4l2-ctrls.h:106 :WARN: typedef of function pointer not marked as 
typdef, use: 'typedef v4l2_ctrl_notify_fnc' in the comment.
...
include/media/v4l2-ctrls.h:605 :WARN: typedef of function pointer not marked as 
typdef, use: 'typedef v4l2_ctrl_filter' in the comment.
...
include/media/v4l2-ctrls.h:809 [kernel-doc WARN] : can't understand function 
proto: 'const char * const *v4l2_ctrl_get_menu(u32 id);'
...

in this case, both typedefs were defined. The prototype for
v4l2_ctrl_get_menu() is also valid.

Anyway, it helped to get some real troubles. Thanks!


> Vice versa, every improvement I see on kernel's source tree is
> merged into this project.
> 
> This project is also used by my POC at:
> 
> * http://return42.github.io/sphkerneldoc/
> 
> E.g. it builds the documentation of the complete kernel sources
> 
> * http://return42.github.io/sphkerneldoc/linux_src_doc/index.html
> 
> the last one is also my test-case to find regression when I change
> something / running against the whole source tree and compare the
> result to the versioned reST files at 
> 
> * https://github.com/return42/sphkerneldoc/tree/master/doc/linux_src_doc
> 
> -- Markus --
> 
> >> E.g. if you want to lint your whole include/media tree type:
> >> 
> >>  kernel-lintdoc [--sloppy] include/media  
> > 
> > Yeah, running it manually is another way, although I prefer to have
> > it done via a Makefile target, and doing only for the files that
> > are currently inside a Sphinx rst file (at least on a first moment).
> > 
> > Thanks,
> > Mauro  
> 



Thanks,
Mauro
--
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

kernel-lintdoc parser - was: Re: [PATCH v2 0/3] doc-rst:c-domain: fix some issues in the c-domain

[Mauro Carvalho Chehab]

Hi Markus,

Em Thu, 22 Sep 2016 09:08:50 -0300
Mauro Carvalho Chehab  escreveu:

> Em Tue, 20 Sep 2016 20:56:35 +0200
> Markus Heiser  escreveu:
> 

> The new parser seems to have some bugs, like those:
> 
> $ kernel-lintdoc include/media/v4l2-ctrls.h
> include/media/v4l2-ctrls.h:106 :WARN: typedef of function pointer not marked 
> as typdef, use: 'typedef v4l2_ctrl_notify_fnc' in the comment.
> ...
> include/media/v4l2-ctrls.h:605 :WARN: typedef of function pointer not marked 
> as typdef, use: 'typedef v4l2_ctrl_filter' in the comment.
> ...
> include/media/v4l2-ctrls.h:809 [kernel-doc WARN] : can't understand function 
> proto: 'const char * const *v4l2_ctrl_get_menu(u32 id);'
> ...

I ran the kernel-lintdoc with:
for i in $(git grep kernel-doc Documentation/media/kapi/|cut -d: -f4); 
do kernel-lintdoc --sloppy $i; done

and I have a few comments:

1) instead of printing the full patch, it would be good to print the
relative patch, as this makes easier to paste the errors on e-mails
and on patches.

2) Parsing of embedded structs/unions

On some headers like dvb_frontend.h, we have unamed structs and enums
inside structs:

struct dtv_frontend_properties {
...
struct {
u8  segment_count;
enum fe_code_rate   fec;
enum fe_modulation  modulation;
u8  interleaving;
} layer[3];
...
};

The fields of the embedded struct are described as:

 * @layer:  ISDB per-layer data (only ISDB standard)
 * @layer.segment_count: Segment Count;
 * @layer.fec:  per layer code rate;
 * @layer.modulation:   per layer modulation;
 * @layer.interleaving:  per layer interleaving.

kernel-lintdoc didn't like that:

drivers/media/dvb-core/dvb_frontend.h:513 :ERROR: duplicate parameter 
definition 'layer'
drivers/media/dvb-core/dvb_frontend.h:514 :ERROR: duplicate parameter 
definition 'layer'
drivers/media/dvb-core/dvb_frontend.h:515 :ERROR: duplicate parameter 
definition 'layer'
drivers/media/dvb-core/dvb_frontend.h:516 :ERROR: duplicate parameter 
definition 'layer'

2) it complains about function typedefs:

drivers/media/dvb-core/demux.h:251 :WARN: typedef of function pointer 
not marked as typdef, use: 'typedef dmx_ts_cb' in the comment.
drivers/media/dvb-core/demux.h:292 :WARN: typedef of function pointer 
not marked as typdef, use: 'typedef dmx_section_cb' in the comment.
include/media/v4l2-ioctl.h:677 :WARN: typedef of function pointer not 
marked as typdef, use: 'typedef v4l2_kioctl' in the comment.
include/media/v4l2-ctrls.h:106 :WARN: typedef of function pointer not 
marked as typdef, use: 'typedef v4l2_ctrl_notify_fnc' in the comment.
include/media/v4l2-ctrls.h:606 :WARN: typedef of function pointer not 
marked as typdef, use: 'typedef v4l2_ctrl_filter' in the comment.
include/media/v4l2-dv-timings.h:39 :WARN: typedef of function pointer 
not marked as typdef, use: 'typedef v4l2_check_dv_timings_fnc' in the comment.
include/media/v4l2-dv-timings.h:39 :WARN: typedef of function pointer 
used uncommon code style: 'typedef bool v4l2_check_dv_timings_fnc(const struct 
v4l2_dv_timings *t, void *handle);'
include/media/videobuf2-core.h:877 :WARN: typedef of function pointer 
not marked as typdef, use: 'typedef vb2_thread_fnc' in the comment.

3) this is actually a more complex problem: how to represent returned values
from the function callbacks. Maybe we'll need to patch kernel-doc. Right now,
it complains with:

drivers/media/dvb-core/demux.h:397 :WARN: duplicate section name 'It 
returns'
drivers/media/dvb-core/demux.h:415 :WARN: duplicate section name 'It 
returns'
drivers/media/dvb-core/demux.h:431 :WARN: duplicate section name 'It 
returns'
drivers/media/dvb-core/demux.h:444 :WARN: duplicate section name 'It 
returns'
drivers/media/dvb-core/demux.h:462 :WARN: duplicate section name 'It 
returns'
drivers/media/dvb-core/demux.h:475 :WARN: duplicate section name 'It 
returns'
drivers/media/dvb-core/demux.h:491 :WARN: duplicate section name 'It 
returns'
drivers/media/dvb-core/demux.h:507 :WARN: duplicate section name 'It 
returns'
drivers/media/dvb-core/demux.h:534 :WARN: duplicate section name 'It 
returns'
drivers/media/dvb-core/demux.h:542 :WARN: duplicate section name 'It 
returns'
drivers/media/dvb-core/demux.h:552 :WARN: duplicate section name 'It 
returns'

4) Parse errors.

Those seem to be caused by some errors at the parser:

include/media/v4l2-ctrls.h:809 :WARN: can't understand function proto: 
'const char * const *v4l2_ctrl_get_menu(u32 id);'
include/media/v4l2-dev.h:173 :WARN: no description found for parameter 
'valid_ioctls\[BITS_TO_LONGS(BASE_VIDIOC_PRIVATE)\]'
include/media/v4l2-dev.h:173 :WARN: no description found for parameter 
'disable_locking\[BITS_TO_LONGS(BASE_VIDIOC_PRIVAT

Re: "CodingStyle: Clarify and complete chapter 7" in docs-next

[Jean Delvare]

Hi Jani,

On Thu, 22 Sep 2016 13:43:42 +0300, Jani Nikula wrote:
> On Thu, 22 Sep 2016, Jean Delvare  wrote:
> > You need to think in terms of actual use cases. Who uses checkpatch and
> > why? I think there are 3 groups of users:
> > * Beginners. They won't run the script by themselves, instead they will
> >   submit a patch which infringes a lot of coding style rules, and the
> >   maintainer will point them to checkpatch and ask for a resubmission
> >   which makes checkpatch happy. Being beginners, they can only rely on
> >   the script itself to only report things which need to be fixed, by
> >   default.
> > * Experienced developers. Who simply want to make sure they did not
> >   overlook anything before they post their work for review. They have
> >   the knowledge to decide if they want to ignore some of the warnings.
> > * People with too much spare time, looking for anything they could
> >   "contribute" to the kernel. They will use --subjective and piss off
> >   every maintainer they can find.
> >
> > Sadly there's not much we can do about the third category, short of
> > killing option --subjective altogether.
> 
> You could make checkpatch have different defaults for patches and files,
> to encourage better style in new code, but to discourage finding
> problems in existing code.

Fixing old code isn't wrong per se. It's good actually. But only if
done the right way by the right person. I don't think it makes any
sense to use this task as an introduction to kernel development for
newcomers. It doesn't teach them anything about the kernel, really.

-- 
Jean Delvare
SUSE L3 Support
--
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: "CodingStyle: Clarify and complete chapter 7" in docs-next

[Jani Nikula]

On Thu, 22 Sep 2016, Jean Delvare  wrote:
> Hi Jani,
>
> On Thu, 22 Sep 2016 13:43:42 +0300, Jani Nikula wrote:
>> 
>> You could make checkpatch have different defaults for patches and files,
>> to encourage better style in new code, but to discourage finding
>> problems in existing code.
>
> Fixing old code isn't wrong per se. It's good actually. But only if
> done the right way by the right person. I don't think it makes any
> sense to use this task as an introduction to kernel development for
> newcomers. It doesn't teach them anything about the kernel, really.

Mostly agreed, though I'd go as far as saying certain classes of
(checkpatch) issues aren't worth fixing, at all, by anyone, except
perhaps while changing the code anyway for some other purpose.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
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: "CodingStyle: Clarify and complete chapter 7" in docs-next

[Al Viro]

On Thu, Sep 22, 2016 at 01:57:58PM +0200, Jean Delvare wrote:
> > 
> > MUST is much stronger language than I would prefer.
> 
> That's what error means, really. When your compiler fails with an
> error, you have no choice but to fix your code. Warnings on the other
> hand may be ignored sometimes.

And they are errors, because of...?

> Sure. But I'm afraid you keep changing topics and I have no idea where
> you are going. We started with "should there be a space before jump
> labels", then out of nowhere we were discussing the wording of the
> output of checkpatch (how is that related?) and now you pull statistics
> out of your hat, like these numbers imply anything.
> 
> checkpatch was called checkPATCH for a reason. It's main intent was to
> prevent NEW (coding-style mostly) errors from creeping into the kernel.
> The fact that old code does now always follow these recommendations is
> unfortunate but that doesn't make checkpatch wrong or bad.
> 
> ERROR means that the new code isn't allowed to do that. Period.

The main intent of checkpatch these days appears to be providing an easy
way of thoughtless inflation of commit counts, everything else be damned.
Make-work, in other words.

The _only_ criterion for adding new checks should be a strong consensus in
the core kernel.  IOW, it should be descriptive, not prescriptive.  "Some
people do it this way, some - that" is not a valid reason for "let's make it
uniform; that way is just better, so from now on it's a new requirement".
Especially when the rationale behind the choice has all the intellectual
rigour of feng shui.  Some of these checks are common-sense, some are
absolutely arbitrary, there are far too many of them and elevating them
to the level of compiler errors like you seem to do is rather dishonest.
--
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 PATCH v2 3/5] futex: Throughput-optimized (TO) futexes

[Waiman Long]

On 09/22/2016 03:49 AM, Peter Zijlstra wrote:

On Wed, Sep 21, 2016 at 07:37:34PM -0400, Waiman Long wrote:

On 09/21/2016 02:59 AM, Mike Galbraith wrote:

On Tue, 2016-09-20 at 09:42 -0400, Waiman Long wrote:

This patch introduces a new futex implementation called
throughput-optimized (TO) futexes.

nit: 'TO' sounds way too much like timeout... TP?  You even use 'to' as
shorthand for timeout in the next patch.

I agree. I am not that satisfied with the TO name. So I will change it to TP
in my next revision of the patch. Thanks for the suggestion.

I'd leave out the TO part entirely (or only mention it in changelogs).

That is, I'd call the futex ops: FUTEX_LOCK and FUTEX_UNLOCK.


I was following the convention for the PI futexes where we have 
FUTEX_LOCK_PI and FUTEX_UNLOCK_PI. If you think it is OK to promote this 
new futex as default for mutex type locks and use the PI futexes only 
when needed, I am certainly OK to drop the suffix.


Cheers,
Longman
--
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 PATCH 4/4] futex, doc: TO futexes document

[Waiman Long]

On 09/22/2016 06:40 AM, Thomas Gleixner wrote:

On Tue, 6 Sep 2016, Waiman Long wrote:

This patch adds a new document file on how to use the TO futexes.

Documentation is nice, but the proper place for documenting this is the
futex(2) man page.

Thanks,

tglx


Yes, I will certainly send patch to update the manpages after the new 
futex gets merged into the upstream kernel. Or should I do that in parallel?


Cheers,
Longman
--
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 PATCH 3/4] futex: Throughput-optimized (TO) futexes

[Thomas Gleixner]

On Tue, 6 Sep 2016, Waiman Long wrote:
> +enum futex_type {
> + TYPE_PI = 0,
> + TYPE_TO,
> +};

Please introduce the futex_type magic and the related changes to the pi
code in a seperate patch so it can be verified independently.

It's sad that one has to explain that to you over and over 

> @@ -836,10 +859,10 @@ static void put_futex_state(struct futex_state *state)
>   return;
>  
>   /*
> -  * If state->owner is NULL, the owner is most probably dying
> -  * and has cleaned up the futex state already
> +  * If state->owner is NULL and the type is TYPE_PI, the owner
> +  * is most probably dying and has cleaned up the state already
>*/
> - if (state->owner) {
> + if (state->owner && (state->type == TYPE_PI)) {
>   raw_spin_lock_irq(&state->owner->pi_lock);
>   list_del_init(&state->list);
>   raw_spin_unlock_irq(&state->owner->pi_lock);
> @@ -847,6 +870,11 @@ static void put_futex_state(struct futex_state *state)
>   rt_mutex_proxy_unlock(&state->pi_mutex, state->owner);
>   }
>  
> + /*
> +  * Dequeue it from the HB futex state list.
> +  */
> + list_del_init(&state->hb_list);

The comment above this list_del() is really pointless. I can see that from
the code itself.

Aside of that: Why do you need seperate list heads? You explain the
seperate list somewhere in that big comment below, but it should be
explained at the point where you add it to the state and the hash bucket.

>   if (current->pi_state_cache)
>   kfree(state);
>   else {
> @@ -919,13 +947,24 @@ void exit_pi_state_list(struct task_struct *curr)
>   continue;
>   }
>  
> - WARN_ON(pi_state->owner != curr);
>   WARN_ON(list_empty(&pi_state->list));
> + if (pi_state->type == TYPE_PI) {
> + WARN_ON(pi_state->owner != curr);
> + pi_state->owner = NULL;
> + }
>   list_del_init(&pi_state->list);
> - pi_state->owner = NULL;
>   raw_spin_unlock_irq(&curr->pi_lock);
>  
> - rt_mutex_unlock(&pi_state->pi_mutex);
> + if (pi_state->type == TYPE_PI)

lacks curly braces

> + rt_mutex_unlock(&pi_state->pi_mutex);
> + else if (pi_state->type == TYPE_TO) {
> + /*
> +  * Need to wakeup the mutex owner.
> +  */

Another completely useless comment. Because you tell what you do, but not
WHY.

> + WARN_ON(!pi_state->owner);
> + if (pi_state->owner)
> + wake_up_process(pi_state->owner);

And what handles or sanity checks the state->hb_list ???

> +/*
> + * Try to lock the userspace futex word (0 => vpid).
> + *
> + * Return: 1 if lock acquired or an error happens, 0 if not.
> + *  The status code will be 0 if no error, or < 0 if an error happens.
> + *  *puval will contain the latest futex value when trylock fails.
> + *
> + * The waiter flag, if set, will make it ignore the FUTEX_WAITERS bit.
> + * The HB spinlock should NOT be held while calling this function. A
> + * successful lock acquisition will clear the waiter and died bits.
> + */
> +static inline int futex_trylock_to(u32 __user *uaddr, u32 vpid, u32 *puval,
> +const bool waiter, int *status)
> +{
> + u32 uval;
> +
> + *status = 0;
> +
> + if (unlikely(get_user(uval, uaddr)))
> + goto efault;
> +
> + *puval = uval;
> +
> + if (waiter ? (uval & FUTEX_TID_MASK) : uval)
> + return 0;   /* Trylock fails */

Please do not use tail comments. They are hard to parse. 

> +
> + if (unlikely(futex_atomic_cmpxchg_inatomic(puval, uaddr, uval, vpid)))
> + goto efault;
> +
> + return *puval == uval;
> +
> +efault:
> + *status = -EFAULT;
> + return 1;
> +}

Do we really need another variant of cmpxchg and why do you need that extra
status? What's wrong in doing the magic in the return value?

This is utter crap, really.

> +
> +/*
> + * Spinning threshold for futex word without setting FUTEX_WAITERS.
> + */
> +#define FUTEX_SPIN_THRESHOLD (1 << 10)

That number is pulled out of thin air or what is the rationale for chosing
1024?

> +/*
> + * Spin on the futex word while the futex owner is active. Otherwise, set
> + * the FUTEX_WAITERS bit and go to sleep. As we take a reference to the futex
> + * owner's task structure, we don't need to use RCU to ensure that the task
> + * structure is valid. The function will directly grab the lock if the
> + * owner is dying or the pid is invalid. That should take care of the problem
> + * of dead lock owners unless the pid wraps around and the preceived owner is
> + * not the real owner.
> + *
> + * Return: 0 if futex acquired, < 0 if an error happens.

If you document functions then pl

Re: [RFC PATCH v2 3/5] futex: Throughput-optimized (TO) futexes

[Thomas Gleixner]

On Thu, 22 Sep 2016, Peter Zijlstra wrote:
> On Wed, Sep 21, 2016 at 07:37:34PM -0400, Waiman Long wrote:
> > On 09/21/2016 02:59 AM, Mike Galbraith wrote:
> > >On Tue, 2016-09-20 at 09:42 -0400, Waiman Long wrote:
> > >>This patch introduces a new futex implementation called
> > >>throughput-optimized (TO) futexes.
> > >nit: 'TO' sounds way too much like timeout... TP?  You even use 'to' as
> > >shorthand for timeout in the next patch.
> > 
> > I agree. I am not that satisfied with the TO name. So I will change it to TP
> > in my next revision of the patch. Thanks for the suggestion.
> 
> I'd leave out the TO part entirely (or only mention it in changelogs).
> 
> That is, I'd call the futex ops: FUTEX_LOCK and FUTEX_UNLOCK.

That brings me to a different question:

How is user space going to support this, i.e. is this some extra magic for
code which implements its own locking primitives or is there going to be a
wide use via e.g. glibc.

Also what's the reason that we can't do probabilistic spinning for
FUTEX_WAIT and have to add yet another specialized variant of futexes?

Thanks,

tglx

--
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 PATCH 00/11] pci: support for configurable PCI endpoint

[Arnd Bergmann]

On Thursday, September 15, 2016 2:03:05 PM CEST Kishon Vijay Abraham I wrote:
> On Wednesday 14 September 2016 06:55 PM, Arnd Bergmann wrote:
> > On Wednesday, September 14, 2016 10:41:56 AM CEST Kishon Vijay Abraham I 
> > wrote:
> > I've added the drivers/ntb maintainers to Cc, given that there is
> > a certain degree of overlap between your work and the existing
> > code, I think they should be part of the discussion.
> >  
> >> Known Limitation:
> >>*) Does not support multi-function devices
> > 
> > If I understand it right, this was a problem for USB and adding
> > it later made it somewhat inconsistent. Maybe we can at least
> > try to come up with an idea of how multi-function devices
> > could be handled even if we don't implement it until someone
> > actually needs it.
> 
> Actually IMO multi-function device in PCI should be much simpler than it is 
> for
> USB. In the case of USB, all the functions in a multi-function device will
> share the same *usb configuration* . (USB device can have multiple
> configuration but only one can be enabled at a time). A multi-function USB
> device will still have a single vendor-id/product-id/class... So I think a
> separate library (composite.c) in USB makes sense.

Ok, makes sense.

> But in the case of PCI, every function can be treated independently since all
> the functions have it's own 4KB configuration space. Each function can be
> configured independently. Each can have it's own vendor-id/product-id/class..
> I'm not sure if we'll need a separate library for PCI like we have for USB.

I think it depends on whether we want to add the software multi-function
support you mention.

> Now the restriction for not allowing multi-function device is because of the
> following structure definition.
> 
> struct pci_epc {
>   ..
> struct pci_epf *epf;
>   ..
> };
> 
> EPC has a single reference to EPF and it is used *only* to notify the function
> driver when the link is up. (If this can be changed to use notification
> mechanism, multi-function devices can be supported here)
> 
> One more place where this restriction arises is in designware driver
> 
> struct dw_pcie_ep {
>   ..
> u8 bar_to_atu[6];
>   ..
> };
> 
> We use single ATU window to configure a BAR (in BAR). If there are multiple
> functions, then this should also be modified since each function has 6 BARs.
> 
> This can be fixed without much effort unless some other issue props up.

Ok.

> > 
> > Is your hardware able to make the PCIe endpoint look like
> > a device with multiple PCI functions, or would one have to
> > do this in software inside of a single PCI function if we
> > ever need it?
> 
> The hardware I have doesn't support multiple PCI functions (like having a
> separate configuration space for each function). It has a dedicated space for
> configuration space supporting only one function. [Section 24.9.7.3.2
> PCIe_SS_EP_CFG_DBICS Register Description in  [1]].
> 
> yeah, it has to be done in software (but that won't be multi-function device 
> in
> PCI terms).
> 
> [1] -> http://www.ti.com/lit/ug/spruhz6g/spruhz6g.pdf

Ok, so in theory there can be other hardware (and quite likely is)
that supports multiple functions, and we can extend the framework
to support them without major obstacles, but your hardware doesn't,
so you kept it simple with one hardcoded function, right?

Seems completely reasonable to me.

> >> TODO:
> >>*) access buffers in RC
> >>*) raise MSI interrupts
> >>*) Enable user space control for the RC side PCI driver
> > 
> > The user space control would end up just being one of several
> > gadget drivers, right? E.g. gadget drivers for standard hardware
> > (8250 uart, ATA, NVMe, some ethernet) could be done as kernel
> > drivers while a user space driver can be used for things that
> > are more unusual and that don't need to interface to another
> > part of the kernel?
> 
> Actually I didn't mean that. It was more with respect to the host side PCI 
> test
> driver (drivers/misc/pci_endpoint_test.c). Right now it validates BAR, irq
> itself. I wanted to change this so that the user controls which tests to run.
> (Like for USB gadget zero tests, testusb.c invokes ioctls to perform various
> tests). Similarly I want to have a userspace program invoke pci_endpoint_test
> to perform various PCI tests.

Ok, I see. So what I described above would be yet another function
driver that can be implemented, but so far, you have not planned
to do that because there was not need, right?

> > 
> >>*) Adapt all other users of designware to use the new design (only
> >>   dra7xx has been adapted)
> > 
> > I don't fully understand this part. Does every designware based
> > driver need modifications, or are the changes to the
> > generic parts of the designware driver enough to make it
> > work for the simpler platforms?
> 
> I have changed the core designware driver structures (like previously the
> platform drivers will only use pcie

Re: [RFC PATCH v2 3/5] futex: Throughput-optimized (TO) futexes

[Peter Zijlstra]

On Tue, Sep 20, 2016 at 09:42:41AM -0400, Waiman Long wrote:
> +/*
> + * Spinning threshold before enabling lock handoff.
> + * Each sleep will decrement the threshold by 1/32 of the start value.
> + */
> +#define TO_SPIN_THRESHOLD(1 << 13)
> +#define TO_SLEEP_DECREMENT   (TO_SPIN_THRESHOLD/32)

Argh, we should really get rid of those stupid numbers. Wasn't there a
patch set working on implementing paravirt functions that would make all
this fixable in a sane way?
--
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 PATCH 4/4] futex, doc: TO futexes document

[Thomas Gleixner]

On Thu, 22 Sep 2016, Waiman Long wrote:
> On 09/22/2016 06:40 AM, Thomas Gleixner wrote:
> > On Tue, 6 Sep 2016, Waiman Long wrote:
> > > This patch adds a new document file on how to use the TO futexes.
> > Documentation is nice, but the proper place for documenting this is the
> > futex(2) man page.
> > 
> > Thanks,
> > 
> > tglx
> 
> Yes, I will certainly send patch to update the manpages after the new futex
> gets merged into the upstream kernel. Or should I do that in parallel?

It won't get merged w/o a patch to the manpage which is accepted by the man
page maintainer.

Thanks,

tglx


--
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 PATCH v2 3/5] futex: Throughput-optimized (TO) futexes

[Davidlohr Bueso]

On Thu, 22 Sep 2016, Thomas Gleixner wrote:


On Thu, 22 Sep 2016, Peter Zijlstra wrote:

On Wed, Sep 21, 2016 at 07:37:34PM -0400, Waiman Long wrote:
> On 09/21/2016 02:59 AM, Mike Galbraith wrote:
> >On Tue, 2016-09-20 at 09:42 -0400, Waiman Long wrote:
> >>This patch introduces a new futex implementation called
> >>throughput-optimized (TO) futexes.
> >nit: 'TO' sounds way too much like timeout... TP?  You even use 'to' as
> >shorthand for timeout in the next patch.
>
> I agree. I am not that satisfied with the TO name. So I will change it to TP
> in my next revision of the patch. Thanks for the suggestion.

I'd leave out the TO part entirely (or only mention it in changelogs).

That is, I'd call the futex ops: FUTEX_LOCK and FUTEX_UNLOCK.


That brings me to a different question:

How is user space going to support this, i.e. is this some extra magic for
code which implements its own locking primitives or is there going to be a
wide use via e.g. glibc.

Also what's the reason that we can't do probabilistic spinning for
FUTEX_WAIT and have to add yet another specialized variant of futexes?


Where would this leave the respective FUTEX_WAKE? A nop? Probably have to
differentiate the fact that the queue was empty, but there was a spinning,
instead of straightforward returning 0.

Thanks,
Davidlohr
--
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 PATCH v2 3/5] futex: Throughput-optimized (TO) futexes

[Thomas Gleixner]

On Thu, 22 Sep 2016, Davidlohr Bueso wrote:
> On Thu, 22 Sep 2016, Thomas Gleixner wrote:
> > Also what's the reason that we can't do probabilistic spinning for
> > FUTEX_WAIT and have to add yet another specialized variant of futexes?
> 
> Where would this leave the respective FUTEX_WAKE? A nop? Probably have to
> differentiate the fact that the queue was empty, but there was a spinning,
> instead of straightforward returning 0.

Sorry, but I really can't parse this answer.

Can you folks please communicate with proper and coherent explanations
instead of throwing a few gnawed off bones in my direction?

Thanks,

tglx
--
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] Move runnable tools from Documentation to tools

[Jonathan Corbet]

On Wed, 21 Sep 2016 18:51:10 -0600
Shuah Khan  wrote:

> Move runnable tools from Documentation to tools. I moved just the
> tools code, and left documentation files as is.
> 
> Based on the v1 series feedback, This v2 series moves accounting,
> laptops/dslm, and pcmcia to tools.
> 
> If v2 patches look good, and if I get an okay, I will try to get
> these into 4.9-rc1

Acked-by: Jonathan Corbet 

Though I still wonder if we really need to keep some of those tools...

jon
--
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: "CodingStyle: Clarify and complete chapter 7" in docs-next

[Jean Delvare]

On Thu, 22 Sep 2016 14:11:03 +0100, Al Viro wrote:
> On Thu, Sep 22, 2016 at 01:57:58PM +0200, Jean Delvare wrote:
> > > 
> > > MUST is much stronger language than I would prefer.
> > 
> > That's what error means, really. When your compiler fails with an
> > error, you have no choice but to fix your code. Warnings on the other
> > hand may be ignored sometimes.
> 
> And they are errors, because of...?

Because we decided they were important. Of course there is some
subjectivity to this decision, much like all gcc warnings could be
errors and some errors could be warnings. Which is why gcc allows
enabling/disabling individually.

I assume the current set of errors vs. warnings is the result of some
consensus amongst kernel developers. It can certainly be adjusted if
the consensus changes for whatever reason.

> > Sure. But I'm afraid you keep changing topics and I have no idea where
> > you are going. We started with "should there be a space before jump
> > labels", then out of nowhere we were discussing the wording of the
> > output of checkpatch (how is that related?) and now you pull statistics
> > out of your hat, like these numbers imply anything.
> > 
> > checkpatch was called checkPATCH for a reason. It's main intent was to
> > prevent NEW (coding-style mostly) errors from creeping into the kernel.
> > The fact that old code does now always follow these recommendations is
> > unfortunate but that doesn't make checkpatch wrong or bad.
> > 
> > ERROR means that the new code isn't allowed to do that. Period.
> 
> The main intent of checkpatch these days appears to be providing an easy
> way of thoughtless inflation of commit counts, everything else be damned.
> Make-work, in other words.

Yes, I've noticed the trend too :-( But that's a problem with the
people using the tool, mostly, not with the tool itself.

> The _only_ criterion for adding new checks should be a strong consensus in
> the core kernel.  IOW, it should be descriptive, not prescriptive.  "Some
> people do it this way, some - that" is not a valid reason for "let's make it
> uniform; that way is just better, so from now on it's a new requirement".
> Especially when the rationale behind the choice has all the intellectual
> rigour of feng shui.  Some of these checks are common-sense, some are
> absolutely arbitrary, there are far too many of them (...)

That I agree with, I've complained about the same before. But that
doesn't mean checkpatch is not a wonderfully useful tool. It really is,
if used properly.

> and elevating them
> to the level of compiler errors like you seem to do is rather dishonest.

I see. Well clearly this discussion isn't going anywhere so I'll go
back working on things that really matter. See you.

-- 
Jean Delvare
SUSE L3 Support
--
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 PATCH v2 3/5] futex: Throughput-optimized (TO) futexes

[Davidlohr Bueso]

On Thu, 22 Sep 2016, Thomas Gleixner wrote:


On Thu, 22 Sep 2016, Davidlohr Bueso wrote:

On Thu, 22 Sep 2016, Thomas Gleixner wrote:
> Also what's the reason that we can't do probabilistic spinning for
> FUTEX_WAIT and have to add yet another specialized variant of futexes?

Where would this leave the respective FUTEX_WAKE? A nop? Probably have to
differentiate the fact that the queue was empty, but there was a spinning,
instead of straightforward returning 0.


Sorry, but I really can't parse this answer.

Can you folks please communicate with proper and coherent explanations
instead of throwing a few gnawed off bones in my direction?


I actually think that FUTEX_WAIT is the better/nicer approach. But my immediate
question above was how to handle the FUTEX_WAKE counter-part. If we want to
maintain current FIFO ordering for wakeups, now with WAIT spinners this will
create lock stealing scenarios (including if we even guard against starvation).
Or we could reduce the scope of spinners, due to the restrictions, similar to
the top-waiter only being able to spin for rtmutexes. This of course will hurt
the effectiveness of spinning in FUTEX_WAIT in the first place.

Another immediate thought was situations where we spinner(s) and the wait queue 
is
empty, the WAKE should also have to acknowledge that situation, as just 
returning 0
would indicate that there are actually no waiters on the futex.

Thanks,
Davidlohr
--
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: "CodingStyle: Clarify and complete chapter 7" in docs-next

[Julia Lawall]

> > The main intent of checkpatch these days appears to be providing an easy
> > way of thoughtless inflation of commit counts, everything else be damned.
> > Make-work, in other words.
>
> Yes, I've noticed the trend too :-( But that's a problem with the
> people using the tool, mostly, not with the tool itself.

With respect to at least one person in this category, I don't think that
their main original inspiration was checkpatch in the first place.  More
random information collected from developer comments, that person's own
notion of what good code is, etc.  So there may be limits to what one can
do to checkpatch that will have an impact on this issue.

Furthermore, probably people who use checkpatch in the right way, ie to
check their patches, don't actually mention their use of checkpatch.  They
just fix up their commits and move on.

julia
--
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: "CodingStyle: Clarify and complete chapter 7" in docs-next

[Joe Perches]

On Thu, 2016-09-22 at 14:11 +0100, Al Viro wrote:
> The main intent of checkpatch these days appears to be providing an easy
> way of thoughtless inflation of commit counts, everything else be damned.

You've made this statement several times over many years.
I don't believe it's true.
I doubt anyone is getting paid per commit.
Who really cares enough to game some stupid little metric?

If it's really a big deal, name some names.  Otherwise please
stop with this dubious argument/point.

> Some of these checks are common-sense, some are
> absolutely arbitrary,

Essentially all of the checkpatch rules are arbitrary.
The compiler doesn't care one way or another.

All the checks exist just to make code appear more consistent.

The conceit being that more consistent code is easier for humans
to read and spot potential defects and possible reuse patterns.
--
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: "CodingStyle: Clarify and complete chapter 7" in docs-next

[Joe Perches]

On Thu, 2016-09-22 at 13:57 +0200, Jean Delvare wrote:
> Sure. But I'm afraid you keep changing topics and I have no idea where
> you are going. We started with "should there be a space before jump
> labels", then out of nowhere we were discussing the wording of the
> output of checkpatch (how is that related?) and now you pull statistics
> out of your hat, like these numbers imply anything.

No, not out of a hat.  Those are the results of a silly script that
runs checkpatch on every .[ch] kernel file (but not tools/) with:

--show-types --terse --emacs --strict --no-summary --quiet -f

The magnitude of "ERRORS" is high and it's not necessary or useful
to modify old or obsolete code just to reduce that magnitude.

> checkpatch was called checkPATCH for a reason.

That's why I promote the --force option to limit using checkpatch on
files outside of staging.

https://patchwork.kernel.org/patch/9332205/

Andrew?  Are you going to apply that one day?

> ERROR means that the new code isn't allowed to do that. Period.

Disagree.  The compiler doesn't care.  The value of consistency in
reducing defects is very hard to quantify.

--
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 PATCH v2 3/5] futex: Throughput-optimized (TO) futexes

[Waiman Long]

On 09/22/2016 09:23 AM, Peter Zijlstra wrote:

On Tue, Sep 20, 2016 at 09:42:41AM -0400, Waiman Long wrote:

+/*
+ * Spinning threshold before enabling lock handoff.
+ * Each sleep will decrement the threshold by 1/32 of the start value.
+ */
+#define TO_SPIN_THRESHOLD  (1<<  13)
+#define TO_SLEEP_DECREMENT (TO_SPIN_THRESHOLD/32)

Argh, we should really get rid of those stupid numbers. Wasn't there a
patch set working on implementing paravirt functions that would make all
this fixable in a sane way?


These thresholds are not paravirt related. They are there to determine 
when we should activate explicit lock handoff when the waiter is waiting 
for too long. Yes, it is arbitrary. The numbers are on the high side as 
setting them too low will limit lock stealing and hence overall 
performance. The FUTEX_WAITERS bit is only turned on when either the top 
waiter is sleeping or a lock handoff is needed. Otherwise, it is off to 
encourage lock stealing in the userspace as well as in the kernel.


Cheers,
Longman


--
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: XDP (eXpress Data Path) documentation

[Jesper Dangaard Brouer]

On Tue, 20 Sep 2016 11:08:44 +0200 Jesper Dangaard Brouer  
wrote:

> As promised, I've started documenting the XDP eXpress Data Path):
> 
>  [1] 
> https://prototype-kernel.readthedocs.io/en/latest/networking/XDP/index.html
> 
> IMHO the documentation have reached a stage where it is useful for the
> XDP project, BUT I request collaboration on improving the documentation
> from all. (Native English speakers are encouraged to send grammar fixes ;-))

I want to publicly thanks Edward Cree for being the first contributor
to the XDP documentation with formulation and grammar fixes.

Pulled and pushed:
 https://github.com/netoptimizer/prototype-kernel/commit/fb6a3de95

Thanks!
-- 
Best regards,
  Jesper Dangaard Brouer
  MSc.CS, Principal Kernel Engineer at Red Hat
  Author of http://www.iptv-analyzer.org
  LinkedIn: http://www.linkedin.com/in/brouer
--
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 PATCH 4/4] futex, doc: TO futexes document

[Waiman Long]

On 09/22/2016 09:51 AM, Thomas Gleixner wrote:

On Thu, 22 Sep 2016, Waiman Long wrote:

Yes, I will certainly send patch to update the manpages after the new futex
gets merged into the upstream kernel. Or should I do that in parallel?

It won't get merged w/o a patch to the manpage which is accepted by the man
page maintainer.


Sure. I will send out a manpage patch when I send out the next revision 
of this patch.


Thanks,
Longman
--
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: "CodingStyle: Clarify and complete chapter 7" in docs-next

[Jean Delvare]

On Thu, 22 Sep 2016 10:49:47 -0700, Joe Perches wrote:
> On Thu, 2016-09-22 at 13:57 +0200, Jean Delvare wrote:
> > Sure. But I'm afraid you keep changing topics and I have no idea where
> > you are going. We started with "should there be a space before jump
> > labels", then out of nowhere we were discussing the wording of the
> > output of checkpatch (how is that related?) and now you pull statistics
> > out of your hat, like these numbers imply anything.
> 
> No, not out of a hat.  Those are the results of a silly script that
> runs checkpatch on every .[ch] kernel file (but not tools/) with:
> 
>   --show-types --terse --emacs --strict --no-summary --quiet -f

Silly is the key word here. Just don't do it.

> The magnitude of "ERRORS" is high and it's not necessary or useful
> to modify old or obsolete code just to reduce that magnitude.

I agree. Just don't do it.

> > checkpatch was called checkPATCH for a reason.
> 
> That's why I promote the --force option to limit using checkpatch on
> files outside of staging.
> 
> https://patchwork.kernel.org/patch/9332205/
> 
> Andrew?  Are you going to apply that one day?

I hope not. Looks plain wrong to me. This wont prevents idiots from
being idiots. All it does is make things more difficult for the rest of
us.

> > ERROR means that the new code isn't allowed to do that. Period.
> 
> Disagree.  The compiler doesn't care.

Which is good, because this has nothing to do with the compiler.

> The value of consistency in reducing defects is very hard to quantify.

That's not the only purpose of consistency.

-- 
Jean Delvare
SUSE L3 Support
--
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 PATCH v2 3/5] futex: Throughput-optimized (TO) futexes

[Waiman Long]

On 09/22/2016 09:34 AM, Thomas Gleixner wrote:

On Thu, 22 Sep 2016, Peter Zijlstra wrote:


I'd leave out the TO part entirely (or only mention it in changelogs).

That is, I'd call the futex ops: FUTEX_LOCK and FUTEX_UNLOCK.

That brings me to a different question:

How is user space going to support this, i.e. is this some extra magic for
code which implements its own locking primitives or is there going to be a
wide use via e.g. glibc.


There are some applications that use futex(2) directly to implement 
their synchronization primitives. For those applications, they will need 
to modify their code to detect the presence of the new futexes. They can 
then use the new futexes if available and use wait-wake futexes if not.


I am also planning to take a look at the pthread_mutex* APIs to see if 
they can be modified to use the new futexes later on when the patch 
becomes more mature.



Also what's the reason that we can't do probabilistic spinning for
FUTEX_WAIT and have to add yet another specialized variant of futexes?



The main reason is that a FUTEX_WAIT waiter has no idea who the owner of 
the futex is. We usually do spinning when the lock owner is running and 
abort when it goes to sleep. We can't do that for FUTEX_WAIT.


Cheers,
Longman
--
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 PATCH v2 3/5] futex: Throughput-optimized (TO) futexes

[Waiman Long]

On 09/22/2016 11:11 AM, Davidlohr Bueso wrote:

On Thu, 22 Sep 2016, Thomas Gleixner wrote:


On Thu, 22 Sep 2016, Davidlohr Bueso wrote:

On Thu, 22 Sep 2016, Thomas Gleixner wrote:
> Also what's the reason that we can't do probabilistic spinning for
> FUTEX_WAIT and have to add yet another specialized variant of 
futexes?


Where would this leave the respective FUTEX_WAKE? A nop? Probably 
have to
differentiate the fact that the queue was empty, but there was a 
spinning,

instead of straightforward returning 0.


Sorry, but I really can't parse this answer.

Can you folks please communicate with proper and coherent explanations
instead of throwing a few gnawed off bones in my direction?


I actually think that FUTEX_WAIT is the better/nicer approach. But my 
immediate
question above was how to handle the FUTEX_WAKE counter-part. If we 
want to
maintain current FIFO ordering for wakeups, now with WAIT spinners 
this will
create lock stealing scenarios (including if we even guard against 
starvation).
Or we could reduce the scope of spinners, due to the restrictions, 
similar to
the top-waiter only being able to spin for rtmutexes. This of course 
will hurt

the effectiveness of spinning in FUTEX_WAIT in the first place.


Actually, there can be a lot of lock stealing going on with the 
wait-wake futexes. If the critical section is short enough, many of the 
lock waiters can be waiting in the hash bucket spinlock queue and not 
sleeping yet while the futex value changes. As a result, they will exit 
the futex syscall and back to user space with EAGAIN where one of them 
may get the lock. So we can't assume that they will get the lock in the 
FIFO order anyway.


Another immediate thought was situations where we spinner(s) and the 
wait queue is
empty, the WAKE should also have to acknowledge that situation, as 
just returning 0

would indicate that there are actually no waiters on the futex.


I would say that adding optimistic spinning to FUTEX_WAIT will be a 
major change and I don't think it will be less complex than adding a new 
futex type like the TO futexes while introducing a fair amount of risk 
of breaking existing applications.


Cheers,
Longman

--
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 PATCH v2 3/5] futex: Throughput-optimized (TO) futexes

[Thomas Gleixner]

On Thu, 22 Sep 2016, Waiman Long wrote:
> On 09/22/2016 09:34 AM, Thomas Gleixner wrote:
> > On Thu, 22 Sep 2016, Peter Zijlstra wrote:
> > > 
> > > I'd leave out the TO part entirely (or only mention it in changelogs).
> > > 
> > > That is, I'd call the futex ops: FUTEX_LOCK and FUTEX_UNLOCK.
> > That brings me to a different question:
> > 
> > How is user space going to support this, i.e. is this some extra magic for
> > code which implements its own locking primitives or is there going to be a
> > wide use via e.g. glibc.
> 
> There are some applications that use futex(2) directly to implement their
> synchronization primitives. For those applications, they will need to modify
> their code to detect the presence of the new futexes. They can then use the
> new futexes if available and use wait-wake futexes if not.

That's what I suspected. Did you talk to the other folks who complain about
futex performance (database, JVM, etc.) and play their own games with user
space spinlocks and whatever?
 
> I am also planning to take a look at the pthread_mutex* APIs to see if they
> can be modified to use the new futexes later on when the patch becomes more
> mature.

Please involve glibc people who are interested in the futex stuff early and
discuss the concept before it's set in stone for your particular usecase.
 
> > Also what's the reason that we can't do probabilistic spinning for
> > FUTEX_WAIT and have to add yet another specialized variant of futexes?
> > 
> 
> The main reason is that a FUTEX_WAIT waiter has no idea who the owner of the
> futex is. We usually do spinning when the lock owner is running and abort when
> it goes to sleep. We can't do that for FUTEX_WAIT.

Fair enough. This wants to be spelled out in the changelog and explained a
bit more detailed.

Thanks,

tglx
--
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 PATCH v2 3/5] futex: Throughput-optimized (TO) futexes

[Thomas Gleixner]

On Thu, 22 Sep 2016, Waiman Long wrote:
> BTW, my initial attempt for the new futex was to use the same workflow as the
> PI futexes, but use mutex which has optimistic spinning instead of rt_mutex.
> That version can double the throughput compared with PI futexes but still far
> short of what can be achieved with wait-wake futex. Looking at the performance
> figures from the patch:
> 
> wait-wake futex PI futexTO futex
> --- 
> max time3.49s50.91s  2.65s
> min time3.24s50.84s  0.07s
> average time3.41s50.90s  1.84s
> sys time  7m22.4s55.73s2m32.9s

That's really interesting. Do you have any explanation for this massive
system time differences?

> lock count   3,090,294  9,999,813   698,318
> unlock count 3,268,896  9,999,814   134
> 
> The problem with a PI futexes like version is that almost all the lock/unlock
> operations were done in the kernel which added overhead and latency. Now
> looking at the numbers for the TO futexes, less than 1/10 of the lock
> operations were done in the kernel, the number of unlock was insignificant.
> Locking was done mostly by lock stealing. This is where most of the
> performance benefit comes from, not optimistic spinning.

How does the lock latency distribution of all this look like and how fair
is the whole thing?

> This is also the reason that a lock handoff mechanism is implemented to
> prevent lock starvation which is likely to happen without one.

Where is that lock handoff mechanism?

Thanks,

tglx
--
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 PATCH v2 3/5] futex: Throughput-optimized (TO) futexes

[Waiman Long]

On 09/22/2016 04:08 PM, Waiman Long wrote:

On 09/22/2016 11:11 AM, Davidlohr Bueso wrote:

On Thu, 22 Sep 2016, Thomas Gleixner wrote:


On Thu, 22 Sep 2016, Davidlohr Bueso wrote:

On Thu, 22 Sep 2016, Thomas Gleixner wrote:
> Also what's the reason that we can't do probabilistic spinning for
> FUTEX_WAIT and have to add yet another specialized variant of 
futexes?


Where would this leave the respective FUTEX_WAKE? A nop? Probably 
have to
differentiate the fact that the queue was empty, but there was a 
spinning,

instead of straightforward returning 0.


Sorry, but I really can't parse this answer.

Can you folks please communicate with proper and coherent explanations
instead of throwing a few gnawed off bones in my direction?


I actually think that FUTEX_WAIT is the better/nicer approach. But my 
immediate
question above was how to handle the FUTEX_WAKE counter-part. If we 
want to
maintain current FIFO ordering for wakeups, now with WAIT spinners 
this will
create lock stealing scenarios (including if we even guard against 
starvation).
Or we could reduce the scope of spinners, due to the restrictions, 
similar to
the top-waiter only being able to spin for rtmutexes. This of course 
will hurt

the effectiveness of spinning in FUTEX_WAIT in the first place.


Actually, there can be a lot of lock stealing going on with the 
wait-wake futexes. If the critical section is short enough, many of 
the lock waiters can be waiting in the hash bucket spinlock queue and 
not sleeping yet while the futex value changes. As a result, they will 
exit the futex syscall and back to user space with EAGAIN where one of 
them may get the lock. So we can't assume that they will get the lock 
in the FIFO order anyway.


BTW, my initial attempt for the new futex was to use the same workflow 
as the PI futexes, but use mutex which has optimistic spinning instead 
of rt_mutex. That version can double the throughput compared with PI 
futexes but still far short of what can be achieved with wait-wake 
futex. Looking at the performance figures from the patch:


wait-wake futex PI futexTO futex
--- 
max time3.49s50.91s  2.65s
min time3.24s50.84s  0.07s
average time3.41s50.90s  1.84s
sys time  7m22.4s55.73s2m32.9s
lock count   3,090,294  9,999,813   698,318
unlock count 3,268,896  9,999,814   134

The problem with a PI futexes like version is that almost all the 
lock/unlock operations were done in the kernel which added overhead and 
latency. Now looking at the numbers for the TO futexes, less than 1/10 
of the lock operations were done in the kernel, the number of unlock was 
insignificant. Locking was done mostly by lock stealing. This is where 
most of the performance benefit comes from, not optimistic spinning.


This is also the reason that a lock handoff mechanism is implemented to 
prevent lock starvation which is likely to happen without one.


Cheers,
Longman


--
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 PATCH v2 3/5] futex: Throughput-optimized (TO) futexes

[Waiman Long]

On 09/22/2016 04:26 PM, Thomas Gleixner wrote:

On Thu, 22 Sep 2016, Waiman Long wrote:

On 09/22/2016 09:34 AM, Thomas Gleixner wrote:

On Thu, 22 Sep 2016, Peter Zijlstra wrote:

I'd leave out the TO part entirely (or only mention it in changelogs).

That is, I'd call the futex ops: FUTEX_LOCK and FUTEX_UNLOCK.

That brings me to a different question:

How is user space going to support this, i.e. is this some extra magic for
code which implements its own locking primitives or is there going to be a
wide use via e.g. glibc.

There are some applications that use futex(2) directly to implement their
synchronization primitives. For those applications, they will need to modify
their code to detect the presence of the new futexes. They can then use the
new futexes if available and use wait-wake futexes if not.

That's what I suspected. Did you talk to the other folks who complain about
futex performance (database, JVM, etc.) and play their own games with user
space spinlocks and whatever?


I am also part of the team that help large application vendors to tune 
their application performance on our large SMP systems. Those 
application vendors tend to use futex directly instead of relying on 
glibc. We had seen spinlock contention in the futex could sometimes be a 
significant portion of the CPU cycles consumed depending on the 
workloads that were being run. We had been providing suggestions on the 
best practice of how to use futexes. But there is only so much you can 
do with tuning their locking code implementation. That is why I am also 
looking for way to improve the performance of the futex code in the kernel.





I am also planning to take a look at the pthread_mutex* APIs to see if they
can be modified to use the new futexes later on when the patch becomes more
mature.

Please involve glibc people who are interested in the futex stuff early and
discuss the concept before it's set in stone for your particular usecase.
  


Sure, I will start to do some prototyping and performance testing with 
glibc and then engage those folks about that.



Also what's the reason that we can't do probabilistic spinning for
FUTEX_WAIT and have to add yet another specialized variant of futexes?


The main reason is that a FUTEX_WAIT waiter has no idea who the owner of the
futex is. We usually do spinning when the lock owner is running and abort when
it goes to sleep. We can't do that for FUTEX_WAIT.

Fair enough. This wants to be spelled out in the changelog and explained a
bit more detailed.


I will.

Cheers,
Longman
--
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 PATCH v2 1/5] futex: Add futex_set_timer() helper function

[Thomas Gleixner]

On Tue, 20 Sep 2016, Waiman Long wrote:

Please be more careful of your subject lines. First thing I thought was
that you add a helper which is used in later patches to find out that you
actualy consolidate duplicated code. Something like:

  futex: Consolidate duplicated timer setup code

would have told me right away what this is about.

> This patch adds a new futex_set_timer() function to consolidate all

Please do not use: "This patch ...". We already know that this is a patch,
otherwise it would not be tagged [PATCH n/m] in the subject line.

See Documentation/SubmittingPatches 

> the sleeping hrtime setup code.

Let me give you a hint:

1:  The code has three identical code copies to set up the futex timeout.

2:  Add a helper function and consolidate the call sites.

#1 tells precisely what the problem is
#2 tells precisely how it is solved

Can you see the difference?

> +/*
> + * Helper function to set the sleeping hrtimer.
> + */
> +static inline void futex_set_timer(ktime_t *time, struct hrtimer_sleeper 
> **pto,
> + struct hrtimer_sleeper *timeout, int flags, u64 range_ns)

Please use futex_setup_timer() as the function name. I was confused when I
read the other patch that you wanted to "set" the timer before entering
into the place which would actually need it.

> +{
> + if (!time)
> + return;
> + *pto = timeout;

Please don't do that. That's a horrible coding style.

What's wrong with returning NULL or the timeout pointer and assign it to
"to" at the call site?

Thanks,

tglx

--
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 PATCH v2 3/5] futex: Throughput-optimized (TO) futexes

[Davidlohr Bueso]

On Thu, 22 Sep 2016, Waiman Long wrote:

BTW, my initial attempt for the new futex was to use the same workflow 
as the PI futexes, but use mutex which has optimistic spinning instead 
of rt_mutex.


Btw, Thomas, do you still have any interest pursuing this for rtmutexes from
-rt into mainline? If so I can resend the patches from a while ago.

Thanks,
Davidlohr
--
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 PATCH v2 3/5] futex: Throughput-optimized (TO) futexes

[Thomas Gleixner]

On Thu, 22 Sep 2016, Davidlohr Bueso wrote:
> On Thu, 22 Sep 2016, Waiman Long wrote:
> 
> > BTW, my initial attempt for the new futex was to use the same workflow as
> > the PI futexes, but use mutex which has optimistic spinning instead of
> > rt_mutex.
> 
> Btw, Thomas, do you still have any interest pursuing this for rtmutexes from
> -rt into mainline? If so I can resend the patches from a while ago.

Certainly yes. My faint memory tells me that there was some potential issue
due to boosting the owner only if it gets scheduled out, but I might be
wrong.

Thanks,

tglx
--
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 PATCH v2 3/5] futex: Throughput-optimized (TO) futexes

[Waiman Long]

On 09/22/2016 04:38 PM, Thomas Gleixner wrote:

On Thu, 22 Sep 2016, Waiman Long wrote:

BTW, my initial attempt for the new futex was to use the same workflow as the
PI futexes, but use mutex which has optimistic spinning instead of rt_mutex.
That version can double the throughput compared with PI futexes but still far
short of what can be achieved with wait-wake futex. Looking at the performance
figures from the patch:

 wait-wake futex PI futexTO futex
 --- 
max time3.49s50.91s  2.65s
min time3.24s50.84s  0.07s
average time3.41s50.90s  1.84s
sys time  7m22.4s55.73s2m32.9s

That's really interesting. Do you have any explanation for this massive
system time differences?


For the wait-wake futexes, the waiters will be kicked out with EAGAIN 
without sleeping as long as the futex value changes before they acquire 
the hash bucket spinlock. These waiters will attempt to acquire the lock 
again in the user space. If that fails, they will call FUTEX_WAIT again.


In the above test case, the critical section is pretty short and about 
4/5 of the FUTEX_WAIT calls resulted in an EAGAIN error. So there are a 
lot more user-space/kernel transitions than the TO futexes. I think the 
difference in the number of FUTEX_WAIT calls vs. the FUTEX_LOCK_TO calls 
causes the difference between their sys times. As for the PI futex, it 
is a strictly sleeping lock and so won't use that much sys time.



lock count   3,090,294  9,999,813   698,318
unlock count 3,268,896  9,999,814   134

The problem with a PI futexes like version is that almost all the lock/unlock
operations were done in the kernel which added overhead and latency. Now
looking at the numbers for the TO futexes, less than 1/10 of the lock
operations were done in the kernel, the number of unlock was insignificant.
Locking was done mostly by lock stealing. This is where most of the
performance benefit comes from, not optimistic spinning.

How does the lock latency distribution of all this look like and how fair
is the whole thing?


The TO futexes are unfair as can be seen from the min/max thread times 
listed above. It took the fastest thread 0.07s to complete all the 
locking operations, whereas the slowest one needed 2.65s. However, the 
situation reverses when I changed the critical section to a 1us sleep. 
In this case, there will be no optimistic spinning. The performance 
results for 100k locking operations were listed below.


wait-wake futex PI futexTO futex
--- 
max time0.06s 9.32s  4.76s
min time5.59s 9.36s  5.62s
average time3.25s 9.35s  5.41s

In this case, the TO futexes are fairer but perform worse than the 
wait-wake futexes. That is because the lock handoff mechanism limit the 
amount of lock stealing in the TO futexes while the wait-wake futexes 
have no such restriction. When I disabled  lock handoff, the TO futexes 
would then perform similar to the wait-wake futexes.





This is also the reason that a lock handoff mechanism is implemented to
prevent lock starvation which is likely to happen without one.

Where is that lock handoff mechanism?




In the futex_state object, there is a new field handoff_pid. It is set 
when the threshold count in futex_spin_on_owner() becomes negative When 
this field is set, the unlocker will change the futex word to that value 
instead of clearing it to 0 and others can steal it. I will separate out 
the lock handoff in a separate patch in the next revision to highlight it.


Cheers,
Longman
--
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 PATCH v2 3/5] futex: Throughput-optimized (TO) futexes

[Waiman Long]

On 09/22/2016 05:41 PM, Thomas Gleixner wrote:

On Thu, 22 Sep 2016, Davidlohr Bueso wrote:

On Thu, 22 Sep 2016, Waiman Long wrote:


BTW, my initial attempt for the new futex was to use the same workflow as
the PI futexes, but use mutex which has optimistic spinning instead of
rt_mutex.

Btw, Thomas, do you still have any interest pursuing this for rtmutexes from
-rt into mainline? If so I can resend the patches from a while ago.

Certainly yes. My faint memory tells me that there was some potential issue
due to boosting the owner only if it gets scheduled out, but I might be
wrong.


It is tricky to add optimistic spinning to rtmutexes because of the need 
to observe process priorities. It is certainly possible to make the top 
waiter spin, but then I am not sure how much performance gain with just 
that.


Cheers,
Longman
--
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: kernel-lintdoc parser - was: Re: [PATCH v2 0/3] doc-rst:c-domain: fix some issues in the c-domain

[Markus Heiser]

Hi Mauro,

thanks a lot for your tests and inspirations ...

Am 22.09.2016 um 14:35 schrieb Mauro Carvalho Chehab :

> Hi Markus,
> 
> Em Thu, 22 Sep 2016 09:08:50 -0300
> Mauro Carvalho Chehab  escreveu:
> 
>> Em Tue, 20 Sep 2016 20:56:35 +0200
>> Markus Heiser  escreveu:
>> 
> 
>> The new parser seems to have some bugs, like those:
>> 
>> $ kernel-lintdoc include/media/v4l2-ctrls.h
>> include/media/v4l2-ctrls.h:106 :WARN: typedef of function pointer not marked 
>> as typdef, use: 'typedef v4l2_ctrl_notify_fnc' in the comment.
>> ...
>> include/media/v4l2-ctrls.h:605 :WARN: typedef of function pointer not marked 
>> as typdef, use: 'typedef v4l2_ctrl_filter' in the comment.
>> ...
>> include/media/v4l2-ctrls.h:809 [kernel-doc WARN] : can't understand function 
>> proto: 'const char * const *v4l2_ctrl_get_menu(u32 id);'
>> ...
> 
> I ran the kernel-lintdoc with:
>   for i in $(git grep kernel-doc Documentation/media/kapi/|cut -d: -f4); 
> do kernel-lintdoc --sloppy $i; done
> 
> and I have a few comments:
> 
> 1) instead of printing the full patch, it would be good to print the
> relative patch, as this makes easier to paste the errors on e-mails
> and on patches.

relative patch? ... I think you mean relative path, if so: 

I can add an option like "--abspath", not a big deal
but whats about calling the lint with $(pwd)/$i ::

 for i in $(git grep kernel-doc Documentation/media/kapi/|cut -d: -f4); do 
kernel-lintdoc --sloppy $(pwd)/$i; done

.. fits this solution to your use-case?


> 2) Parsing of embedded structs/unions
> 
> On some headers like dvb_frontend.h, we have unamed structs and enums
> inside structs:
> 
> struct dtv_frontend_properties {
> ...
>   struct {
>   u8  segment_count;
>   enum fe_code_rate   fec;
>   enum fe_modulation  modulation;
>   u8  interleaving;
>   } layer[3];
> ...
> };
> 
> The fields of the embedded struct are described as:
> 
> * @layer: ISDB per-layer data (only ISDB standard)
> * @layer.segment_count: Segment Count;
> * @layer.fec: per layer code rate;
> * @layer.modulation:  per layer modulation;
> * @layer.interleaving: per layer interleaving.
> 
> kernel-lintdoc didn't like that:
> 
>   drivers/media/dvb-core/dvb_frontend.h:513 :ERROR: duplicate parameter 
> definition 'layer'
>   drivers/media/dvb-core/dvb_frontend.h:514 :ERROR: duplicate parameter 
> definition 'layer'
>   drivers/media/dvb-core/dvb_frontend.h:515 :ERROR: duplicate parameter 
> definition 'layer'
>   drivers/media/dvb-core/dvb_frontend.h:516 :ERROR: duplicate parameter 
> definition 'layer'

Hah .. fixed this yesterday ;-)

  
https://github.com/return42/linuxdoc/commit/531df6dd7728393f447b1a4b3215b96687d02ba2

I analyzed this yesterday and haven't had time to report it,
so I will do it now:

   This is also broken in the kernel-doc (perl) parser
   .. are you able to fix it? 

I can give it I try, but I have no extensive test case for the
perl version and perl is a bid harder for me. So sometimes I'am
a bit scary about patching the kernel-doc perl script.
(as I said before, for the py version I test against the
whole source and compare/versionize the resulted reST)

What I tested:

  ./scripts/kernel-doc -rst -function dtv_frontend_properties 
drivers/media/dvb-core/dvb_frontend.h

for "layer" it outputs:

``layer[3]``
  per layer interleaving.

Read my commit message above .. the description block is taken
from " @layer.interleaving:" instead from "@layer:".


> 2) it complains about function typedefs:
> 
>   drivers/media/dvb-core/demux.h:251 :WARN: typedef of function pointer 
> not marked as typdef, use: 'typedef dmx_ts_cb' in the comment.
>   drivers/media/dvb-core/demux.h:292 :WARN: typedef of function pointer 
> not marked as typdef, use: 'typedef dmx_section_cb' in the comment.
>   include/media/v4l2-ioctl.h:677 :WARN: typedef of function pointer not 
> marked as typdef, use: 'typedef v4l2_kioctl' in the comment.
>   include/media/v4l2-ctrls.h:106 :WARN: typedef of function pointer not 
> marked as typdef, use: 'typedef v4l2_ctrl_notify_fnc' in the comment.
>   include/media/v4l2-ctrls.h:606 :WARN: typedef of function pointer not 
> marked as typdef, use: 'typedef v4l2_ctrl_filter' in the comment.
>   include/media/v4l2-dv-timings.h:39 :WARN: typedef of function pointer 
> not marked as typdef, use: 'typedef v4l2_check_dv_timings_fnc' in the comment.
>   include/media/v4l2-dv-timings.h:39 :WARN: typedef of function pointer 
> used uncommon code style: 'typedef bool v4l2_check_dv_timings_fnc(const 
> struct v4l2_dv_timings *t, void *handle);'
>   include/media/videobuf2-core.h:877 :WARN: typedef of function pointer 
> not marked as typdef, use: 'typedef vb2_thread_fnc' in the comment.

Thanks for reporting this ... fixed it:

https://github.com/return42/linuxdoc/commit/9228f2128dba967519fd8f2cdeb2c2202caad84d

> 3) this is actuall

Re: kernel-lintdoc parser - was: Re: [PATCH v2 0/3] doc-rst:c-domain: fix some issues in the c-domain

[Markus Heiser]

Am 22.09.2016 um 14:35 schrieb Mauro Carvalho Chehab :

> Hi Markus,
> 3) this is actually a more complex problem: how to represent returned values
> from the function callbacks. Maybe we'll need to patch kernel-doc.

This might be a solution for dense kernel-doc comments where you
want to have paragraph and lists in parameter descriptions:

https://github.com/return42/linuxdoc/commit/9bfb8a59326677a819f62cb16f3ffacc8b244af1

--M--


--
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 PATCH v2 1/5] futex: Add futex_set_timer() helper function

[Waiman Long]

On 09/22/2016 05:31 PM, Thomas Gleixner wrote:

On Tue, 20 Sep 2016, Waiman Long wrote:

Please be more careful of your subject lines. First thing I thought was
that you add a helper which is used in later patches to find out that you
actualy consolidate duplicated code. Something like:

   futex: Consolidate duplicated timer setup code

would have told me right away what this is about.


This patch adds a new futex_set_timer() function to consolidate all

Please do not use: "This patch ...". We already know that this is a patch,
otherwise it would not be tagged [PATCH n/m] in the subject line.

See Documentation/SubmittingPatches 


the sleeping hrtime setup code.

Let me give you a hint:

1:  The code has three identical code copies to set up the futex timeout.

2:  Add a helper function and consolidate the call sites.

#1 tells precisely what the problem is
#2 tells precisely how it is solved

Can you see the difference?


+/*
+ * Helper function to set the sleeping hrtimer.
+ */
+static inline void futex_set_timer(ktime_t *time, struct hrtimer_sleeper **pto,
+   struct hrtimer_sleeper *timeout, int flags, u64 range_ns)

Please use futex_setup_timer() as the function name. I was confused when I
read the other patch that you wanted to "set" the timer before entering
into the place which would actually need it.


+{
+   if (!time)
+   return;
+   *pto = timeout;

Please don't do that. That's a horrible coding style.

What's wrong with returning NULL or the timeout pointer and assign it to
"to" at the call site?

Thanks,

tglx



Thanks for the suggestions. I will fix this patch in the next revision.

Cheers,
Longman
--
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 PATCH 3/4] futex: Throughput-optimized (TO) futexes

[Waiman Long]

On 09/22/2016 09:32 AM, Thomas Gleixner wrote:

On Tue, 6 Sep 2016, Waiman Long wrote:

+enum futex_type {
+   TYPE_PI = 0,
+   TYPE_TO,
+};

Please introduce the futex_type magic and the related changes to the pi
code in a seperate patch so it can be verified independently.

It's sad that one has to explain that to you over and over 


I didn't break it out because the changes to the PI code was pretty 
small. I will break it out in the next version.



@@ -836,10 +859,10 @@ static void put_futex_state(struct futex_state *state)
return;

/*
-* If state->owner is NULL, the owner is most probably dying
-* and has cleaned up the futex state already
+* If state->owner is NULL and the type is TYPE_PI, the owner
+* is most probably dying and has cleaned up the state already
 */
-   if (state->owner) {
+   if (state->owner&&  (state->type == TYPE_PI)) {
raw_spin_lock_irq(&state->owner->pi_lock);
list_del_init(&state->list);
raw_spin_unlock_irq(&state->owner->pi_lock);
@@ -847,6 +870,11 @@ static void put_futex_state(struct futex_state *state)
rt_mutex_proxy_unlock(&state->pi_mutex, state->owner);
}

+   /*
+* Dequeue it from the HB futex state list.
+*/
+   list_del_init(&state->hb_list);

The comment above this list_del() is really pointless. I can see that from
the code itself.

Aside of that: Why do you need seperate list heads? You explain the
seperate list somewhere in that big comment below, but it should be
explained at the point where you add it to the state and the hash bucket.


Sure. Will fix the comment.


if (current->pi_state_cache)
kfree(state);
else {
@@ -919,13 +947,24 @@ void exit_pi_state_list(struct task_struct *curr)
continue;
}

-   WARN_ON(pi_state->owner != curr);
WARN_ON(list_empty(&pi_state->list));
+   if (pi_state->type == TYPE_PI) {
+   WARN_ON(pi_state->owner != curr);
+   pi_state->owner = NULL;
+   }
list_del_init(&pi_state->list);
-   pi_state->owner = NULL;
raw_spin_unlock_irq(&curr->pi_lock);

-   rt_mutex_unlock(&pi_state->pi_mutex);
+   if (pi_state->type == TYPE_PI)

lacks curly braces


Yes, you are right.


+   rt_mutex_unlock(&pi_state->pi_mutex);
+   else if (pi_state->type == TYPE_TO) {
+   /*
+* Need to wakeup the mutex owner.
+*/

Another completely useless comment. Because you tell what you do, but not
WHY.


Will elaborate on why the wakeup here.


+   WARN_ON(!pi_state->owner);
+   if (pi_state->owner)
+   wake_up_process(pi_state->owner);

And what handles or sanity checks the state->hb_list ???



The exit_pi_state_list() function doesn't need to deal with 
state->hb_list. The hb_list is used to locate the futex state, but the 
futex owner doesn't have a reference to the futex state. So it won't 
need to decrement it and potentially free it.



+/*
+ * Try to lock the userspace futex word (0 =>  vpid).
+ *
+ * Return: 1 if lock acquired or an error happens, 0 if not.
+ *The status code will be 0 if no error, or<  0 if an error happens.
+ **puval will contain the latest futex value when trylock fails.
+ *
+ * The waiter flag, if set, will make it ignore the FUTEX_WAITERS bit.
+ * The HB spinlock should NOT be held while calling this function. A
+ * successful lock acquisition will clear the waiter and died bits.
+ */
+static inline int futex_trylock_to(u32 __user *uaddr, u32 vpid, u32 *puval,
+  const bool waiter, int *status)
+{
+   u32 uval;
+
+   *status = 0;
+
+   if (unlikely(get_user(uval, uaddr)))
+   goto efault;
+
+   *puval = uval;
+
+   if (waiter ? (uval&  FUTEX_TID_MASK) : uval)
+   return 0;   /* Trylock fails */

Please do not use tail comments. They are hard to parse.



OK, will move the comment up.


+
+   if (unlikely(futex_atomic_cmpxchg_inatomic(puval, uaddr, uval, vpid)))
+   goto efault;
+
+   return *puval == uval;
+
+efault:
+   *status = -EFAULT;
+   return 1;
+}

Do we really need another variant of cmpxchg and why do you need that extra
status? What's wrong in doing the magic in the return value?


This is not another variant of cmpxchg. It is the cmpxchg used by 
cmpxchg_futex_value_locked().  The only difference is that page fault 
was disabled with the locked version. I call 
futex_atomic_cmpxchg_inatomic() directly because it is called without 
the HB spinlock. So I don't need to disable page fault. I will add a 
separate patch to introduce