Re: [PATCH v2 3/3] mm: enable CONFIG_MOVABLE_NODE on powerpc

[Reza Arbab]

On Mon, Sep 19, 2016 at 11:59:35AM +0530, Aneesh Kumar K.V wrote:

Movable node also does.
memblock_set_bottom_up(true);
What is the impact of that. Do we need changes equivalent to that ? Also
where are we marking the nodes which can be hotplugged, ie where do we
do memblock_mark_hotplug() ?


These are related to the mechanism x86 uses to create movable nodes at 
boot. The SRAT is parsed to mark any hotplug memory. That marking is 
used later when initializing ZONE_MOVABLE for each node. [1]


The bottom-up allocation is due to a timing issue [2]. There is a window 
where kernel memory may be allocated before the SRAT is parsed. Any 
bottom-up allocations done during that time will likely be in the same 
(nonmovable) node as the kernel image.


On power, I don't think we have a heuristic equivalent to that SRAT 
memory hotplug info. So, we'll be limited to dynamically adding movable 
nodes after boot.


1. http://events.linuxfoundation.org/sites/events/files/lcjp13_chen.pdf
2. commit 79442ed189ac ("mm/memblock.c: introduce bottom-up allocation 
mode")


--
Reza Arbab

--
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: [PATCHv12 1/3] rdmacg: Added rdma cgroup controller

[Parav Pandit]

Hi Leon,

On Fri, Sep 16, 2016 at 12:26 AM, Leon Romanovsky  wrote:
> On Wed, Sep 14, 2016 at 12:36:19PM +0530, Parav Pandit wrote:
>> Hi Dennis,
>>
>> Do you know how would HFI1 driver would work along with rdma cgroup?
>>
>> Hi Matan, Leon, Jason,
>> Apart from HFI1, is there any other concern?
>> Or Patch is good to go?
>
> I didn't review it yet :(.
> Sorry
>

We have completed review from Tejun, Christoph.
HFI driver folks also provided feedback for Intel drivers.
Matan's also doesn't have any more comments.

If possible, if you can also review, it will be helpful.

I have some more changes unrelated to cgroup in same files in both the git tree.
Pushing them now either results into merge conflict later on for
Doug/Tejun, or requires rebase and resending patch.
If you can review, we can avoid such rework.

>>
>> 4.8 dates are close by (2 weeks) and there are two git trees involved
>> (that might cause merge error to Linus) so if there are no issues, I
>> would like to make request to Doug to consider it for 4.8 early on.
>>
>> Parav
>>
>> On Mon, Sep 12, 2016 at 10:37 AM, Leon Romanovsky  wrote:
>> > On Sun, Sep 11, 2016 at 11:52:35AM -0600, Jason Gunthorpe wrote:
>> >> On Sun, Sep 11, 2016 at 07:24:45PM +0200, Christoph Hellwig wrote:
>> >> > > > > I've posted some initial work toward a) a while ago, and once we
>> >> > >
>> >> > > Did it get merged? Do you have a pointer?
>> >> >
>> >> > http://www.spinics.net/lists/linux-rdma/msg31958.html
>> >>
>> >> Right, I remember that. Certainly the right direction
>> >>
>> >> > > However, everything under verbs is not straightforward. The files in
>> >> > > userspace are not copies...
>> >> > >
>> >> > > user:
>> >> > >
>> >> > > struct ibv_query_device {
>> >> > >__u32 command;
>> >> > >__u16 in_words;
>> >> > >__u16 out_words;
>> >> > >__u64 response;
>> >> > >__u64 driver_data[0];
>> >> > > };
>> >> > >
>> >> > > kernel:
>> >> > >
>> >> > > struct ib_uverbs_query_device {
>> >> > > __u64 response;
>> >> > > __u64 driver_data[0];
>> >> > > };
>> >> >
>> >> > We'll obviously need different strutures for the libibvers API
>> >> > and the kernel interface in this case, and we'll need to figure out
>> >> > how to properly translate them.  I think a cast, plus compile time
>> >> > type checking ala BUILD_BUG_ON is the way to go.
>> >>
>> >> I'm not sure I follow, which would I cast?
>> >>
>> >> BUILD_BUG_ON(sizeof(ibv_query_device) == sizeof(ib_uverbs_cmd_hdr) +
>> >>  sizeof(ib_uverbs_query_device))
>> >>
>> >> ?
>> >>
>> >> > > I'm thinking the best way forward might be to use a script and
>> >> > > transform userspace into:
>> >> > >
>> >> > > struct ibv_query_device {
>> >> > >   struct ib_uverbs_cmd_hdr hdr;
>> >> > >   struct ib_uverbs_query_device cmd;
>> >> > > };
>> >> >
>> >> > That would break the users of the interface.
>> >>
>> >> Sorry, I mean doing this inside rdma-plumbing. Since the change is ABI
>> >> identical the modified libibverbs would still be binary compatible
>> >> with all providers but not source compatible. Since all kernel
>> >> supported providers are in rdma-plumbing we can add the '.cmd.' at the
>> >> same time.
>> >>
>> >> The kernel uapi header would stay the same.
>> >>
>> >> > However automatically generating the user ABI from the kernel one
>> >> > might still be a good idea in the long run.
>> >>
>> >> My preference would be to try and use the kernel headers directly.
>> >
>> > I thought the same, especially after realizing that they are almost
>> > copy/paste from the vendor *-abi.h files.
>> >
>> >>
>> >> Jason
--
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: [iovisor-dev] XDP (eXpress Data Path) documentation

[Alexei Starovoitov]

On Tue, Sep 20, 2016 at 11:08:44AM +0200, Jesper Dangaard Brouer via 
iovisor-dev 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 ;-))
> 
> 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

Thanks so much for doing it. This is great start!
Some minor editing is needed here and there.
To make it into official doc do you mind preparing a patch for Jon's doc tree ?
If you think the doc is too volatile and not suitable for kernel.org,
another alternative is to host it on https://github.com/iovisor
since it's LF collaborative project it won't disappear suddenly.
You can be a maintainer of that repo if you like.

--
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 v10 RESEND 0/3] Documentation: Add description of enable multi-cpus support for kdump

[Baoquan He]

On 09/20/16 at 06:03pm, Jonathan Corbet wrote:
> On Mon, 19 Sep 2016 13:59:46 +0800
> Baoquan He  wrote:
> 
> > This is v10 post. In this patchset patch 1/3 is added to give more details
> > about nr_cpus and maxcpus in kernel-parameters.txt. This is suggested by
> > Jonathan since the description of them is unclear so that people can't see
> > what's the exact difference between them. Otherwise no big further change
> > for 2/3 and 3/3 which comprise the old post.
> 
> So somehow I'd applied 1/3 a while back, but not the other two.  All three
> are in the docs tree now, thanks.

Thanks!

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

Re: [PATCH v4 00/29] Create a book for Kernel development

[Jonathan Corbet]

On Mon, 19 Sep 2016 08:07:34 -0300
Mauro Carvalho Chehab  wrote:

> That's the 4th version of this series. It also contains a second patch series
> with more ReST conversions and documentation improvements.
> This patchset merges the content of a second patch series:
> 
>   [PATCH 00/17] Improve documentation for the development-process
> 

OK, I'm applying these through 28; I'm going to hold off on #29.  Thanks
for separating that part out so nicely.

> I opted to keep the patch changing the  kernel-docs.txt changes
> (patch 21/29). The patch is already written and another patch
> (patch 22/29)  depends on it, because there are references to
> this file at Documentation/HOWTO.
>
> It shouldn't be hard  to get rid of it, but I'm not sure if worths
> the effort. As I commented, people might find useful to update
> it to point to more modern documents. If people won't do it,
> it can still be removed from the Kernel a the next Kernel version.

I'll take them for now, since there seems to be interest in doing something
with this document.  I kept the applying-patches one as well.  But I do
think that we need to start being a bit more willing to get rid of musty
old docs.  We don't carry unused code because "it might be useful to
somebody"; I think we should take the same approach to docs.  Out-of-date
or irrelevant docs are a maintenance burden, and they impose a heavy burden
on the people the docs are most meant to help...

A few notes:

#1 didn't apply, I had to do it by hand.  I suspect my late application of
Marcus's work got in the way there.

#2 had this:

> Content-Type: text/plain; charset=true

...which threw git am for a loop; I had to fix it manually.  What gives
there?

#4 didn't apply and had to be done by hand.

#10 (CodingStyle) has a lot of ".. code-block:: c" constructs.  Why are
those needed?  We're still using C by default for literal blocks, right?

#15 (SecurityBugs) leaves the section numbers in place; did you intend
that?

#21 (kernel-docs.txt) had the charset=true weirdness

#28 actually, I balked at applying this one, since it assumes that
the great renaming is taking place, and that hasn't happened yet.

So actually I only went through #27, but that took a long time - seemingly
longer than it takes you to create them! :)

A few of the patches still have the bare "::" lines in them; I think I'll
just add a patch to fix those up real quick.

Thanks,

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: [PATCH] [linux-next] Fix double word "the the" in Doc/filesystems

[Jonathan Corbet]

On Tue, 20 Sep 2016 12:49:59 +0900
Masanari Iida  wrote:

> This patch fix typos "the the" found in Documentation/filesystems.

So this patch doesn't apply.

> Signed-off-by: Masanari Iida 
> ---
>  Documentation/filesystems/autofs4-mount-control.txt | 10 +-

In particular, this one fails.  Which is weird, since that file hasn't
been modified since 2014...which kernel version was this done against?
Can you please retry with a current kernel?

>  Documentation/filesystems/directory-locking |  2 +-
>  Documentation/filesystems/overlayfs.txt |  2 +-
>  3 files changed, 7 insertions(+), 7 deletions(-)

Thanks,

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: [PATCH v10 RESEND 0/3] Documentation: Add description of enable multi-cpus support for kdump

[Jonathan Corbet]

On Mon, 19 Sep 2016 13:59:46 +0800
Baoquan He  wrote:

> This is v10 post. In this patchset patch 1/3 is added to give more details
> about nr_cpus and maxcpus in kernel-parameters.txt. This is suggested by
> Jonathan since the description of them is unclear so that people can't see
> what's the exact difference between them. Otherwise no big further change
> for 2/3 and 3/3 which comprise the old post.

So somehow I'd applied 1/3 a while back, but not the other two.  All three
are in the docs tree now, thanks.

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: [PATCH] Documentation: DMA-API-HOWTO: Fix a typo

[Jonathan Corbet]

On Tue, 20 Sep 2016 09:04:20 -0700
Andrey Smirnov  wrote:

> - if (dma_mapping_error(cp->dev, dma_handle)) {
> + if (dma_mapping_error(cp->dev, mapping)) {

Interesting, that has been wrong for the entire git era; another patch
fixed that line a few years ago, but left the wrong name in place...
Applied to the docs tree, thanks.

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: [PATCH v2 0/3] doc-rst:c-domain: fix some issues in the c-domain

[Mauro Carvalho Chehab]

Em Tue, 20 Sep 2016 13:00:33 -0600
Jonathan Corbet  escreveu:

> On Tue, 20 Sep 2016 20:56:35 +0200
> Markus Heiser  wrote:
> 
> > > I submitted one patch fixing it. Not sure if it got merged by Jon
> > > or not.  
> > 
> > Ups, I might have overseen this patch .. as Jon said, its hard to
> > follow you ;)
> > 
> > I tested the above with Jon's docs-next, so it seems your patch is
> > not yet applied. Could you send me a link for this patch? (sorry,
> > I can't find it).
> 
> Send again, please?  I'll add it to the pile of other stuff, and try not
> to lose it again...:)

Gah, there are so many patches that I'm also confused whether I sent something
or just dreamed about sending it :)

I actually sent a patch doing this on a /47 patch series, but only
for macros:

Subject: [PATCH 01/47] kernel-doc: ignore arguments on macro definitions

I was thinking on doing the same for functions, but didn't actually
submitted such patch.

Yet, it seems more coherent, IMHO, to use use same approach for both C
functions and macros: presenting just the name instead of printing the
arguments.

I'll work on it and submit, likely tomorrow.

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

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

[Jonathan Corbet]

On Tue, 20 Sep 2016 20:56:35 +0200
Markus Heiser  wrote:

> > I submitted one patch fixing it. Not sure if it got merged by Jon
> > or not.  
> 
> Ups, I might have overseen this patch .. as Jon said, its hard to
> follow you ;)
> 
> I tested the above with Jon's docs-next, so it seems your patch is
> not yet applied. Could you send me a link for this patch? (sorry,
> I can't find it).

Send again, please?  I'll add it to the pile of other stuff, and try not
to lose it again...:)

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: [PATCH v2 0/3] doc-rst:c-domain: fix some issues in the c-domain

[Markus Heiser]

Am 19.09.2016 um 17:00 schrieb Mauro Carvalho Chehab :

>> Hmm, as far as I see, the output is not correct ... The output of
>> functions with a function pointer argument are missing the 
>> leading parenthesis in the function definition:
>> 
>>  .. c:function:: struct v4l2_m2m_ctx * v4l2_m2m_ctx_init (struct 
>> v4l2_m2m_dev * m2m_dev, void * drv_priv, int (*queue_init) (void *priv, 
>> struct vb2_queue *src_vq, struct vb2_queue *dst_vq)
>> 
>> The missing parenthesis cause the error message. 
> 
> 
> Ah, OK! I'll kernel-doc and see what's happening here.
> 
>> 
>> The output of the parameter description is:
>> 
>>  ``int (*)(void *priv, struct vb2_queue *src_vq, struct vb2_queue *dst_vq) 
>> queue_init``
>>a callback for queue type-specific initialization function
>>to be used for initializing videobuf_queues
>> 
>> Correct (and IMO better to read) is:
>> 
>>  .. c:function:: struct v4l2_m2m_ctx *v4l2_m2m_ctx_init(struct v4l2_m2m_dev 
>> *m2m_dev, void *drv_priv, int (*queue_init)(void *priv, struct vb2_queue 
>> *src_vq, struct vb2_queue *dst_vq))
>> 
>> and the parameter description should be something like ...
>> 
>>   :param int (\*queue_init)(void \*priv, struct vb2_queue \*src_vq, struct 
>> vb2_queue \*dst_vq):
>>a callback for queue type-specific initialization function
>>to be used for initializing videobuf_queues
> 
> I guess the better would be to strip the parameter type and output
> it as:
>   queue_init
>   a callback for queue type-specific initialization function
>   to be used for initializing videobuf_queues

Good point!

> As I pointed before, the point is that such argument can easily have
> more than 80 columns, with would cause troubles with LaTeX output,
> as LaTeX doesn't break long verbatim text on multiple lines.
> 
> I submitted one patch fixing it. Not sure if it got merged by Jon
> or not.

Ups, I might have overseen this patch .. as Jon said, its hard to
follow you ;)

I tested the above with Jon's docs-next, so it seems your patch is
not yet applied. Could you send me a link for this patch? (sorry,
I can't find it).


>> I tested this with my linuxdoc tools (parser) with I get no
>> error messages from the sphinx c-domain.
>> 
>> BTW: 
>> 
>> The parser of my linuxdoc project is more strict and spit out some 
>> warnings, which are not detected by the kernel-doc parser from the
>> kernel source tree.
>> 
>> For your rework on kernel-doc comments, it might be helpful to see
>> those messages, so I recommend to install the linuxdoc package and
>> do some lint.
>> 
>> install: https://return42.github.io/linuxdoc/install.html
>> lint:https://return42.github.io/linuxdoc/cmd-line.html#kernel-lintdoc
> 
> Interesting! Yeah, it caught a lot more errors ;)
> 
> 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.

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

Re: [PATCH 1/8] samples: move accounting example code from Documentation

[Shuah Khan]

On 09/19/2016 10:02 AM, Jonathan Corbet wrote:
> On Mon, 19 Sep 2016 08:47:32 -0600
> Shuah Khan  wrote:
> 
>> Move accounting examples to samples and remove it from Documentation
>> Makefile. Create a new Makefile to build accounting. It can be built
>> from top level directory or from accounting directory:
> 
> So I like the basic idea of these patches; it's the direction we've been
> trying to push things for a little bit.  I have a couple of specific
> comments for this one that may well apply to the others as well.
> 
> 1) Is samples the right destination for these utilities?  Some of them
>might well be better placed under tools/ instead.  I'm not sure we've
>ever formally stated the purpose of those two subtrees; I see samples/
>as demonstrations of how to use something, while tools/ are utilities
>you might actually want to use for some purpose.  Something like
>getdelays might well fall into the latter group.  But maybe others
>disagree?

getdelays stumped me a bit. My first choice was tools and then I noticed
that the documentation says it is a tool and an example usage of taskstruct.
I am not set on tools or samples as location for this. I can move it to
tools instead.

> 
> 2) Tools like getdelays are referenced in the documents that have been
>left behind; see accounting/delay-accounting.txt, for example.  Those
>documents should be updated so that readers know where to find the
>referenced programs, wherever they end up.  Converting them to Sphinx
>while you're at it is an extra-credit exercise :)

Right. Documents need updates and also the 00-Index files. I agree with
you that converting to Sphinx makes sense. There will be some learning
curve on my part. I can take this one once the move happens and do the
Documentation and 00-Index file updates.

thanks,
-- Shuah
--
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] Documentation: DMA-API-HOWTO: Fix a typo

[Andrey Smirnov]

Fix a type in example variable name.

Signed-off-by: Andrey Smirnov 
---
 Documentation/DMA-API-HOWTO.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.txt
index 781024e..d08a56a 100644
--- a/Documentation/DMA-API-HOWTO.txt
+++ b/Documentation/DMA-API-HOWTO.txt
@@ -699,7 +699,7 @@ to use the dma_sync_*() interfaces.
dma_addr_t mapping;
 
mapping = dma_map_single(cp->dev, buffer, len, DMA_FROM_DEVICE);
-   if (dma_mapping_error(cp->dev, dma_handle)) {
+   if (dma_mapping_error(cp->dev, mapping)) {
/*
 * reduce current DMA mapping usage,
 * delay and try again later or
-- 
2.5.5

--
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

[RFC PATCH v2 2/5] futex: Rename futex_pi_state to futex_state

[Waiman Long]

The futex_pi_state structure will be overloaded in later patches to
store state information about non-PI futexes. So the structure name
itself is no longer a good description of its purpose. This patch
renames it to futex_state, a more generic name.

Some of the functions that process the futex states are also renamed.

Signed-off-by: Waiman Long 
---
 include/linux/sched.h |4 +-
 kernel/futex.c|  107 +
 2 files changed, 56 insertions(+), 55 deletions(-)

diff --git a/include/linux/sched.h b/include/linux/sched.h
index 62c68e5..fefd7f7 100644
--- a/include/linux/sched.h
+++ b/include/linux/sched.h
@@ -126,7 +126,7 @@ struct sched_attr {
u64 sched_period;
 };
 
-struct futex_pi_state;
+struct futex_state;
 struct robust_list_head;
 struct bio_list;
 struct fs_struct;
@@ -1772,7 +1772,7 @@ struct task_struct {
struct compat_robust_list_head __user *compat_robust_list;
 #endif
struct list_head pi_state_list;
-   struct futex_pi_state *pi_state_cache;
+   struct futex_state *pi_state_cache;
 #endif
 #ifdef CONFIG_PERF_EVENTS
struct perf_event_context *perf_event_ctxp[perf_nr_task_contexts];
diff --git a/kernel/futex.c b/kernel/futex.c
index 37e61ef..f8bb93f 100644
--- a/kernel/futex.c
+++ b/kernel/futex.c
@@ -192,11 +192,12 @@ int __read_mostly futex_cmpxchg_enabled;
 #define FLAGS_HAS_TIMEOUT  0x04
 
 /*
- * Priority Inheritance state:
+ * Futex state object:
+ *  - Priority Inheritance state
  */
-struct futex_pi_state {
+struct futex_state {
/*
-* list of 'owned' pi_state instances - these have to be
+* list of 'owned' state instances - these have to be
 * cleaned up in do_exit() if the task exits prematurely:
 */
struct list_head list;
@@ -240,7 +241,7 @@ struct futex_q {
struct task_struct *task;
spinlock_t *lock_ptr;
union futex_key key;
-   struct futex_pi_state *pi_state;
+   struct futex_state *pi_state;
struct rt_mutex_waiter *rt_waiter;
union futex_key *requeue_pi_key;
u32 bitset;
@@ -787,76 +788,76 @@ static int get_futex_value_locked(u32 *dest, u32 __user 
*from)
 /*
  * PI code:
  */
-static int refill_pi_state_cache(void)
+static int refill_futex_state_cache(void)
 {
-   struct futex_pi_state *pi_state;
+   struct futex_state *state;
 
if (likely(current->pi_state_cache))
return 0;
 
-   pi_state = kzalloc(sizeof(*pi_state), GFP_KERNEL);
+   state = kzalloc(sizeof(*state), GFP_KERNEL);
 
-   if (!pi_state)
+   if (!state)
return -ENOMEM;
 
-   INIT_LIST_HEAD(_state->list);
+   INIT_LIST_HEAD(>list);
/* pi_mutex gets initialized later */
-   pi_state->owner = NULL;
-   atomic_set(_state->refcount, 1);
-   pi_state->key = FUTEX_KEY_INIT;
+   state->owner = NULL;
+   atomic_set(>refcount, 1);
+   state->key = FUTEX_KEY_INIT;
 
-   current->pi_state_cache = pi_state;
+   current->pi_state_cache = state;
 
return 0;
 }
 
-static struct futex_pi_state * alloc_pi_state(void)
+static struct futex_state *alloc_futex_state(void)
 {
-   struct futex_pi_state *pi_state = current->pi_state_cache;
+   struct futex_state *state = current->pi_state_cache;
 
-   WARN_ON(!pi_state);
+   WARN_ON(!state);
current->pi_state_cache = NULL;
 
-   return pi_state;
+   return state;
 }
 
 /*
- * Drops a reference to the pi_state object and frees or caches it
+ * Drops a reference to the futex state object and frees or caches it
  * when the last reference is gone.
  *
  * Must be called with the hb lock held.
  */
-static void put_pi_state(struct futex_pi_state *pi_state)
+static void put_futex_state(struct futex_state *state)
 {
-   if (!pi_state)
+   if (!state)
return;
 
-   if (!atomic_dec_and_test(_state->refcount))
+   if (!atomic_dec_and_test(>refcount))
return;
 
/*
-* If pi_state->owner is NULL, the owner is most probably dying
-* and has cleaned up the pi_state already
+* If state->owner is NULL, the owner is most probably dying
+* and has cleaned up the futex state already
 */
-   if (pi_state->owner) {
-   raw_spin_lock_irq(_state->owner->pi_lock);
-   list_del_init(_state->list);
-   raw_spin_unlock_irq(_state->owner->pi_lock);
+   if (state->owner) {
+   raw_spin_lock_irq(>owner->pi_lock);
+   list_del_init(>list);
+   raw_spin_unlock_irq(>owner->pi_lock);
 
-   rt_mutex_proxy_unlock(_state->pi_mutex, pi_state->owner);
+   rt_mutex_proxy_unlock(>pi_mutex, state->owner);
}
 
if (current->pi_state_cache)
-   kfree(pi_state);
+   kfree(state);
else {
/*
-* 

[RFC PATCH v2 0/5] futex: Introducing throughput-optimized futexes

[Waiman Long]

 v1->v2:
  - Adds an explicit lock hand-off mechanism.
  - Adds timeout support.
  - Simplifies the required userspace code.
  - Fixes a number of problems in the v1 code.

This patchset introduces a new futex implementation called
throughput-optimized (TO) futexes. It is similar to PI futexes in its
calling convention, but provides better throughput than the wait-wake
futexes by encouraging lock stealing and optimistic spinning.

Waiman Long (5):
  futex: Add futex_set_timer() helper function
  futex: Rename futex_pi_state to futex_state
  futex: Throughput-optimized (TO) futexes
  futex: Add timeout support to TO futexes
  futex, doc: TO futexes document

 Documentation/00-INDEX |2 +
 Documentation/to-futex.txt |  140 
 include/linux/sched.h  |4 +-
 include/uapi/linux/futex.h |4 +
 kernel/futex.c |  810 +++-
 5 files changed, 869 insertions(+), 91 deletions(-)
 create mode 100644 Documentation/to-futex.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

[RFC PATCH v2 4/5] futex: Add timeout support to TO futexes

[Waiman Long]

This patch adds the timeout support in other futex types to TO
futexes. However, the timeout isn't as precise as the other futex
types due to the fact timer expiration can't currently be detected
when the thread is waiting in the serialization mutex.

Signed-off-by: Waiman Long 
---
 kernel/futex.c |   40 +++-
 1 files changed, 31 insertions(+), 9 deletions(-)

diff --git a/kernel/futex.c b/kernel/futex.c
index 7daba56..c73be79 100644
--- a/kernel/futex.c
+++ b/kernel/futex.c
@@ -3423,7 +3423,8 @@ static inline int futex_set_waiters_unlocked(u32 __user 
*uaddr, u32 *puval)
  * Return: 0 if futex acquired, < 0 if an error happens.
  */
 static int futex_spin_on_owner(u32 __user *uaddr, u32 vpid,
-  struct futex_state *state)
+  struct futex_state *state,
+  struct hrtimer_sleeper *timeout)
 {
int ret, loop = TO_SPIN_THRESHOLD;
u32 uval, curval;
@@ -3483,8 +3484,11 @@ static int futex_spin_on_owner(u32 __user *uaddr, u32 
vpid,
continue;
}
 
-   /* Check for signal */
-   if (signal_pending(current)) {
+   /* Check for timeout & signal */
+   if (timeout && !timeout->task) {
+   ret = -ETIMEDOUT;
+   break;
+   } else if (signal_pending(current)) {
ret = -EINTR;
break;
}
@@ -3594,6 +3598,12 @@ efault:
  * This function is not inlined so that it can show up in stack trace for
  * analysis purpose.
  *
+ * The timeout functionality isn't as precise as other other futex types
+ * as timer expiration will not be detected while waiting in the
+ * serialization mutex. One possible solution is to modify the expiration
+ * function to send out a signal as well so as to break the thread out of
+ * the mutex code if we really want more precise timeout.
+ *
  * Return:
  *  < 0 - an error happens
  *  0   - acquires the lock via futex_spin_on_owner()
@@ -3601,8 +3611,9 @@ efault:
  *  2   - lock handed off from unlocker
  */
 static noinline int
-futex_lock_to(u32 __user *uaddr, unsigned int flags)
+futex_lock_to(u32 __user *uaddr, unsigned int flags, ktime_t *time)
 {
+   struct hrtimer_sleeper timeout, *to = NULL;
struct futex_hash_bucket *hb;
union futex_key key = FUTEX_KEY_INIT;
struct futex_state *state;
@@ -3627,6 +3638,8 @@ futex_lock_to(u32 __user *uaddr, unsigned int flags)
if (refill_futex_state_cache())
return -ENOMEM;
 
+   futex_set_timer(time, , , flags, current->timer_slack_ns);
+
ret = get_futex_key(uaddr, flags & FLAGS_SHARED, , VERIFY_WRITE);
if (unlikely(ret))
goto out;
@@ -3651,10 +3664,15 @@ futex_lock_to(u32 __user *uaddr, unsigned int flags)
/*
 * Acquiring the serialization mutex.
 */
-   if (state->type != TYPE_TO)
+   if (state->type != TYPE_TO) {
ret = -EINVAL;
-   else
+   } else {
+   if (to)
+   hrtimer_start_expires(>timer, HRTIMER_MODE_ABS);
ret = mutex_lock_interruptible(>mutex);
+   if (ret && to && !timeout.task)
+   ret = -ETIMEDOUT;
+   }
 
if (unlikely(ret))
/*
@@ -3667,7 +3685,7 @@ futex_lock_to(u32 __user *uaddr, unsigned int flags)
 * As the mutex owner, we can now spin on the futex word as well as
 * the active-ness of the futex owner.
 */
-   ret = futex_spin_on_owner(uaddr, vpid, state);
+   ret = futex_spin_on_owner(uaddr, vpid, state, to ?  : NULL);
 
mutex_unlock(>mutex);
 
@@ -3684,6 +3702,10 @@ out_put_state_key:
put_futex_key();
 
 out:
+   if (to) {
+   hrtimer_cancel(>timer);
+   destroy_hrtimer_on_stack(>timer);
+   }
return ret;
 }
 
@@ -3831,7 +3853,7 @@ long do_futex(u32 __user *uaddr, int op, u32 val, ktime_t 
*timeout,
return futex_requeue(uaddr, flags, uaddr2, val, val2, , 1);
 #ifdef CONFIG_SMP
case FUTEX_LOCK_TO:
-   return futex_lock_to(uaddr, flags);
+   return futex_lock_to(uaddr, flags, timeout);
case FUTEX_UNLOCK_TO:
return futex_unlock_to(uaddr, flags);
 #endif
@@ -3850,7 +3872,7 @@ SYSCALL_DEFINE6(futex, u32 __user *, uaddr, int, op, u32, 
val,
int cmd = op & FUTEX_CMD_MASK;
 
if (utime && (cmd == FUTEX_WAIT || cmd == FUTEX_LOCK_PI ||
- cmd == FUTEX_WAIT_BITSET ||
+ cmd == FUTEX_WAIT_BITSET || cmd == FUTEX_LOCK_TO ||
  cmd == FUTEX_WAIT_REQUEUE_PI)) {
if (unlikely(should_fail_futex(!(op & FUTEX_PRIVATE_FLAG
return -EFAULT;
-- 
1.7.1

--
To unsubscribe from this list: send the 

[RFC PATCH v2 5/5] futex, doc: TO futexes document

[Waiman Long]

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

Signed-off-by: Waiman Long 
---
 Documentation/00-INDEX |2 +
 Documentation/to-futex.txt |  140 
 2 files changed, 142 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/to-futex.txt

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index cb9a6c6..a39f020 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -439,6 +439,8 @@ this_cpu_ops.txt
- List rationale behind and the way to use this_cpu operations.
 thermal/
- directory with information on managing thermal issues (CPU/temp)
+to-futex.txt
+   - Documentation on lightweight throughput-optimized futexes.
 trace/
- directory with info on tracing technologies within linux
 unaligned-memory-access.txt
diff --git a/Documentation/to-futex.txt b/Documentation/to-futex.txt
new file mode 100644
index 000..bcd29d1
--- /dev/null
+++ b/Documentation/to-futex.txt
@@ -0,0 +1,140 @@
+Started by: Waiman Long 
+
+Throughput-Optimized Futexes
+
+
+There are two main problems for a wait-wake futex (FUTEX_WAIT and
+FUTEX_WAKE) when used for creating user-space locking primitives:
+
+ 1) With a wait-wake futex, tasks waiting for a lock are put to sleep
+in the futex queue to be woken up by the lock owner when it is done
+with the lock. Waking up a sleeping task, however, introduces some
+additional latency which can be large especially if the critical
+section protected by the lock is relatively short. This may cause
+a performance bottleneck on large systems with many CPUs running
+applications that need a lot of inter-thread synchronization.
+
+ 2) The performance of the wait-wake futex is currently
+spinlock-constrained.  When many threads are contending for a
+futex in a large system with many CPUs, it is not unusual to have
+spinlock contention accounting for more than 90% of the total
+CPU cycles consumed at various points in time.
+
+This two problems can create performance bottlenecks with a
+futex-constrained workload especially on systems with large number
+of CPUs.
+
+The goal of the throughput-optimized (TO) futexes is maximize the
+locking throughput at the expense of fairness and deterministic
+latency. This is done by encouraging lock stealing and optimistic
+spinning on a locked futex when the lock owner is running within the
+kernel until the lock is free. This is the same optimistic spinning
+mechanism used by the kernel mutex and rw semaphore implementations
+to improve performance. Optimistic spinning was done without taking
+any lock.
+
+The downside of this improved throughput is the increased variance
+of the actual response times of the locking operations. Some locking
+operations will be very fast, while others may be considerably slower.
+The average response time should be better than the wait-wake futexes.
+
+The TO futexes has a built-in lock hand-off mechanism to prevent lock
+starvation from happening. When the top lock waiter has too many failed
+attempts to acquire the lock, it will initiate the hand-off mechanism
+by forcing the unlocker to transfer the lock to itself instead of
+freeing it. This limit the maximum latency a waiter has to wait.
+
+Performance-wise, TO futexes should be faster than wait-wake futexes
+especially if the futex locker holders do not sleep. For workload
+that does a lot of sleeping within the critical sections, the TO
+futexes may not be faster than the wait-wake futexes.
+
+Implementation
+--
+
+Like the PI and robust futexes, a lock acquirer has to atomically
+put its thread ID (TID) into the lower 30 bits of the 32-bit futex
+which should has an original value of 0. If it succeeds, it will be
+the owner of the futex. Otherwise, it has to call into the kernel
+using the new FUTEX_LOCK_TO futex(2) syscall.
+
+  futex(uaddr, FUTEX_LOCK_TO, 0, timeout, NULL, 0);
+
+Only the optional timeout parameter is being used by the new futex
+call.
+
+A kernel mutex is used for serialization. The top lock waiter that is
+the owner of the serialization mutex will try to acquire the lock when
+it is available.
+
+When the futex lock owner is no longer running, the top waiter will
+set the FUTEX_WAITERS bit before going to sleep. This is to make sure
+the futex owner will go into the kernel at unlock time to wake the
+waiter up.
+
+The expected return values of the above futex call are:
+ a) 0   - lock acquired as the top waiter
+ b) 1   - lock stolen as non-top waiter
+ c) 2   - lock explicitly handed off by the unlocker
+ d) < 0 - an error happens
+
+When it is time to unlock, the lock owner has to atomically change
+the futex value from its TID to 0. If that fails, it has to issue a
+FUTEX_UNLOCK_TO futex system call to wake up the top waiter.
+
+  futex(uaddr, FUTEX_UNLOCK_TO, 0, NULL, NULL, 0);
+
+A return value of 

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

[Waiman Long]

This patch introduces a new futex implementation called
throughput-optimized (TO) futexes. The goal of this new futex
type is to maximize locking throughput at the expense of fairness
and deterministic latency. Its throughput is higher than that of
the wait-wake futexes especially on systems with a large number of
CPUs and the lock owners are unlikely to sleep. The downside is the
increase in the response time variance. It also implements a lock
hand-off mechanism to make sure that lock starvation won't happen.

Using a futex locking microbenchmark to do 10 millions locking
operations with 5 pause instructions as the critical section by 256
threads (10M/256 locking ops each) on a 4-socket 72-core 144-thread
Haswell-EX system, the results of the benchmark runs were as follows:

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 lock and unlock counts above show the actual numbers of futex(2)
lock and unlock syscalls that were being issued.

Signed-off-by: Waiman Long 
---
 include/uapi/linux/futex.h |4 +
 kernel/futex.c |  634 +++-
 2 files changed, 627 insertions(+), 11 deletions(-)

diff --git a/include/uapi/linux/futex.h b/include/uapi/linux/futex.h
index 0b1f716..e7deaf3 100644
--- a/include/uapi/linux/futex.h
+++ b/include/uapi/linux/futex.h
@@ -20,6 +20,8 @@
 #define FUTEX_WAKE_BITSET  10
 #define FUTEX_WAIT_REQUEUE_PI  11
 #define FUTEX_CMP_REQUEUE_PI   12
+#define FUTEX_LOCK_TO  13
+#define FUTEX_UNLOCK_TO14
 
 #define FUTEX_PRIVATE_FLAG 128
 #define FUTEX_CLOCK_REALTIME   256
@@ -39,6 +41,8 @@
 FUTEX_PRIVATE_FLAG)
 #define FUTEX_CMP_REQUEUE_PI_PRIVATE   (FUTEX_CMP_REQUEUE_PI | \
 FUTEX_PRIVATE_FLAG)
+#define FUTEX_LOCK_TO_PRIVATE  (FUTEX_LOCK_TO | FUTEX_PRIVATE_FLAG)
+#define FUTEX_UNLOCK_TO_PRIVATE(FUTEX_UNLOCK_TO | FUTEX_PRIVATE_FLAG)
 
 /*
  * Support for robust futexes: the kernel cleans up held futexes at
diff --git a/kernel/futex.c b/kernel/futex.c
index f8bb93f..7daba56 100644
--- a/kernel/futex.c
+++ b/kernel/futex.c
@@ -191,6 +191,11 @@ int __read_mostly futex_cmpxchg_enabled;
 #define FLAGS_CLOCKRT  0x02
 #define FLAGS_HAS_TIMEOUT  0x04
 
+enum futex_type {
+   TYPE_PI = 0,
+   TYPE_TO,
+};
+
 /*
  * Futex state object:
  *  - Priority Inheritance state
@@ -203,13 +208,30 @@ struct futex_state {
struct list_head list;
 
/*
-* The PI object:
+* Linking into the owning hashed bucket (TO futexes only)
+*/
+   struct list_head hb_list;
+
+   /*
+* The PI or mutex object:
 */
-   struct rt_mutex pi_mutex;
+   union {
+   struct rt_mutex pi_mutex;
+   struct mutex mutex;
+   };
 
+   /*
+* For PI futex, owner is the task that owns the futex.
+* For TO futex, owner is the mutex lock holder that is either
+* spinning on the futex owner or sleeping.
+*/
struct task_struct *owner;
atomic_t refcount;
 
+   enum futex_type type;
+
+   u32 handoff_pid;/* TO only, PID for lock hand-off */
+
union futex_key key;
 };
 
@@ -262,6 +284,7 @@ struct futex_hash_bucket {
atomic_t waiters;
spinlock_t lock;
struct plist_head chain;
+   struct list_head fs_list;   /* List of futex state objects */
 } cacheline_aligned_in_smp;
 
 /*
@@ -801,8 +824,11 @@ static int refill_futex_state_cache(void)
return -ENOMEM;
 
INIT_LIST_HEAD(>list);
+   INIT_LIST_HEAD(>hb_list);
+
/* pi_mutex gets initialized later */
state->owner = NULL;
+   state->handoff_pid = 0;
atomic_set(>refcount, 1);
state->key = FUTEX_KEY_INIT;
 
@@ -836,10 +862,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(>owner->pi_lock);
list_del_init(>list);
raw_spin_unlock_irq(>owner->pi_lock);
@@ -847,6 +873,10 @@ static void put_futex_state(struct futex_state *state)

[PATCH 06/14] Documentation/kernel-docs.txt: some improvements on the ReST output

[Mauro Carvalho Chehab]

- Use lower case for sections, as this is the standard used on
  the other ReST files;
- The latest version of this document is at the Kernel source, and
  not at the listed URL. So, move it to the end of the doc.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/kernel-docs.txt | 15 +++
 1 file changed, 7 insertions(+), 8 deletions(-)

diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt
index fc1474419c81..5493f8bbe45a 100644
--- a/Documentation/kernel-docs.txt
+++ b/Documentation/kernel-docs.txt
@@ -3,10 +3,6 @@ Index of Documentation for People Interested in Writing and/or 
Understanding the
 
   Juan-Mariano de Goyeneche 
 
-.. note::
- The latest version of this document may be found at:
- :http://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html
-
 The need for a document like this one became apparent in the
 linux-kernel mailing list as the same questions, asking for pointers
 to information, appeared again and again.
@@ -34,7 +30,7 @@ Document.
 
 Enjoy!
 
-ON-LINE DOCS
+On-line docs
 
 
 * Title: **Linux Device Drivers, Third Edition**
@@ -466,8 +462,8 @@ ON-LINE DOCS
   :Notes: For 2.0.x kernels. Gives guidances to port it to 2.2.x
 kernels.
 
-BOOKS: (Not on-line)
-
+Published books
+---
 
 * Title: **Linux Device Drivers**
 
@@ -590,7 +586,7 @@ BOOKS: (Not on-line)
   :Note: German. The third edition from 2011 is
  much cheaper and still quite up-to-date.
 
-MISCELLANEOUS
+Miscellaneous
 -
 
 * Name: **linux/Documentation**
@@ -675,3 +671,6 @@ MISCELLANEOUS
 ---
 
 Document last updated on Mon 2016-Sep-19
+
+This document is based on:
+ http://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html
-- 
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/14] Update kernel-docs.txt

[Mauro Carvalho Chehab]

This patch series update the kernel-docs.txt file, removing broken links, adding
newer ones and ordering documents in published date.

IMHO, after this patch series, kernel-docs.txt will be in a better shape and
could be useful to help new Kernel developers by providing them some extra
references.

I'm adding the Richard's patch series here, I rebased them to be applied
before the renaming patch.

PS.: This series should be applied after:
[PATCH v4 00/29] Create a book for Kernel development

(and before patch 29/29), because it depends on this patch:

https://git.linuxtv.org/mchehab/experimental.git/commit/?h=docs-next=5df1a04603dc0ac4e3c964094005c56a1bf2d704

The entire series of patches can be found at:

https://git.linuxtv.org//mchehab/experimental.git/log/?h=docs-next

And the generated documents at:

HTML:   https://mchehab.fedorapeople.org/development-process/
LaTex:  
https://mchehab.fedorapeople.org/development-process/latex/development-process.tex
PDF:
https://mchehab.fedorapeople.org/development-process/latex/development-process.pdf
  
ePub:   
https://mchehab.fedorapeople.org/development-process/epub/LinuxKernelDevelopmentDocumentation.epub

Mauro Carvalho Chehab (10):
  Documentation/kernel-docs.txt: convert it to ReST markup
  Documentation/kernel-docs.txt: some improvements on the ReST output
  Documentation/kernel-docs.txt: adjust LDD references
  Documentation/kernel-docs.txt: sort books per publication date
  Documentation/kernel-docs.txt: add two published books
  Documentation/kernel-docs.txt: remove more legacy references
  Documentation/kernel-docs.txt: move in-kernel docs
  Documentation/kernel-docs.txt: get rid of broken docs
  Documentation/kernel-docs.txt: Add dates for online docs
  Documentation/kernel-docs.txt: reorder based on timestamp

Richard Sailer (4):
  Documentation/kernel-docs.txt: Remove offline or outdated entries
  Documentation/kernel-docs.txt: Improve layouting of book list
  Documentation/kernel-docs.txt: Add 4 paper/book references
  Documentation/kernel-docs.txt: Consistent indenting: 4 spaces

 Documentation/kernel-docs.txt | 1375 +++--
 1 file changed, 647 insertions(+), 728 deletions(-)

-- 
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 04/14] Documentation/kernel-docs.txt: Add 4 paper/book references

[Mauro Carvalho Chehab]

From: Richard Sailer 

Background/Reasoning:

Books:
--
 * Linux Kernel Networking by Rami Rosen
   While some parts are quite short and could be
   more carefully explained it's still a good recomendation
   for understanding linux kernel networking, (IMHO)

* Linux Treiber entwickeln:
  It sure is a drawback that this is a german book.
  But it's quite recent, well structured and there are also
  other non-english (spanish) books/papers in this list.

Papers:
---

  * On Submitting kernel Patches
Contains 2 case studies of bigger patch sets and how (or how not)
they were merged. I found it helpful

  * Tracing the Way of Data in a TCP Connection through the Linux Kernel
Since this was written by me this inclusion may be a bit biased :p
Neitherless I think this gives a good introduction on
understanding/exploring linux internals using ftrace and an overview
of Linux TCP internals.

[mche...@s-opensource.com: rebased to apply before rename]

Signed-off-by: Richard Sailer 
Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/kernel-docs.txt | 45 +++
 1 file changed, 45 insertions(+)

diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt
index 1fe1046fe6bf..c3a8462a4012 100644
--- a/Documentation/kernel-docs.txt
+++ b/Documentation/kernel-docs.txt
@@ -154,6 +154,33 @@ ON-LINE DOCS
  device driver. It describes the code for module initialization and
  cleanup, as well as the open() and close() system calls*.
 
+ * Title: **On submitting kernel Patches**
+
+   :Author: Andi Kleen
+   :URL: http://halobates.de/on-submitting-kernel-patches.pdf
+   :Keywords: patches, review process, types of submissions, basic rules, 
case studies
+   :Description: This paper gives several experience values on what types 
of patches
+ there are and how likley they get merged.
+   :Abstract:
+ [...]. This paper examines some common problems for
+  submitting larger changes and some strategies to avoid problems.
+
+ * Title: **Tracing the Way of Data in a TCP Connection through the Linux 
Kernel**
+   :Author: Richard Sailer
+   :URL: https://archive.org/details/linux_kernel_data_flow_short_paper
+   :Keywords: Linux Kernel Networking, TCP, tracing, ftrace
+   :Description: A seminar paper explaining ftrace and how to use it for
+ understanding linux kernel internals,
+ illustrated at tracing the way of a TCP packet through the kernel.
+   :Abstract: *This short paper outlines the usage of ftrace a tracing 
framework
+ as a tool to understand a running Linux system.
+ Having obtained a trace-log a kernel hacker can read and understand
+ source code more determined and with context.
+ In a detailed example this approach is demonstrated in tracing
+ and the way of data in a TCP Connection through the kernel.
+ Finally this trace-log is used as base for more a exact conceptual
+ exploration and description of the Linux TCP/IP implementation.*
+
  * Title: **The Devil's in the Details**
 
:Author: Georg v. Zezschwitz and Alessandro Rubini.
@@ -545,6 +572,24 @@ BOOKS: (Not on-line)
:Pages: 440
:ISBN: 978-0672329463
 
+ * Title: **Linux Kernel Networking: Implementation and Theory**
+
+   :Author: Rami Rosen
+   :Publisher: Apress
+   :Date: December 22, 2013
+   :Pages: 648
+   :ISBN: 978-1430261964
+
+ * Title: **Linux Treiber entwickeln**
+
+   :Author: J??rgen Quade, Eva-Katharina Kunst
+   :Publisher: dpunkt.verlag
+   :Date: Oct 2015 (4th edition)
+   :Pages: 688
+   :ISBN: 978-3-86490-288-8
+   :Note: German. The third edition from 2011 is
+  much cheaper and still quite up-to-date.
+
 MISCELLANEOUS
 -
 
-- 
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 09/14] Documentation/kernel-docs.txt: add two published books

[Mauro Carvalho Chehab]

Add two books from my own bookshelf. I found them useful by
the time I bought; so it could be useful to others ;)

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/kernel-docs.txt | 16 
 1 file changed, 16 insertions(+)

diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt
index 0f4fa8b69769..3c335bd58934 100644
--- a/Documentation/kernel-docs.txt
+++ b/Documentation/kernel-docs.txt
@@ -474,6 +474,14 @@ Published books
   :Pages: 648
   :ISBN: 978-1430261964
 
+* Title: **Embedded Linux Primer: A practical Real-World Approach, 2nd 
Edition**
+
+  :Author: Christopher Hallinan
+  :Publisher: Pearson
+  :Date: November, 2010
+  :Pages: 656
+  :ISBN: 978-0137017836
+
 * Title: **Linux Kernel Development, 3rd Edition**
 
   :Author: Robert Love
@@ -482,6 +490,14 @@ Published books
   :Pages: 440
   :ISBN: 978-0672329463
 
+* Title: **Essential Linux Device Drivers**
+
+  :Author: Sreekrishnan Venkateswaran
+  :Published: Prentice Hall
+  :Date: April, 2008
+  :Pages: 744
+  :ISBN: 978-0132396554
+
 .. _ldd3_published:
 
 * Title: **Linux Device Drivers, 3rd Edition**
-- 
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 03/14] Documentation/kernel-docs.txt: Improve layouting of book list

[Mauro Carvalho Chehab]

From: Richard Sailer 

The dots at the ends of the list elements introduced
unnecesarry newlines in the "compiled" document.

While this was not "mission critical" it's not nice to look at
either.

[mche...@s-opensource.com: rebased to apply before rename]

Signed-off-by: Richard Sailer 
Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/kernel-docs.txt | 86 +--
 1 file changed, 43 insertions(+), 43 deletions(-)

diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt
index 2771c5ca177c..1fe1046fe6bf 100644
--- a/Documentation/kernel-docs.txt
+++ b/Documentation/kernel-docs.txt
@@ -444,18 +444,18 @@ BOOKS: (Not on-line)
 
  * Title: **Linux Device Drivers**
 
-   :Author: Alessandro Rubini.
-   :Publisher: O'Reilly & Associates.
-   :Date: 1998.
-   :Pages: 439.
+   :Author: Alessandro Rubini
+   :Publisher: O'Reilly & Associates
+   :Date: 1998
+   :Pages: 439
:ISBN: 1-56592-292-1
 
  * Title: **Linux Device Drivers, 2nd Edition**
 
-   :Author: Alessandro Rubini and Jonathan Corbet.
-   :Publisher: O'Reilly & Associates.
-   :Date: 2001.
-   :Pages: 586.
+   :Author: Alessandro Rubini and Jonathan Corbet
+   :Publisher: O'Reilly & Associates
+   :Date: 2001
+   :Pages: 586
:ISBN: 0-59600-008-1
:Notes: Further information in
  http://www.oreilly.com/catalog/linuxdrive2/
@@ -463,9 +463,9 @@ BOOKS: (Not on-line)
  * Title: **Linux Device Drivers, 3rd Edition**
 
:Authors: Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman
-   :Publisher: O'Reilly & Associates.
-   :Date: 2005.
-   :Pages: 636.
+   :Publisher: O'Reilly & Associates
+   :Date: 2005
+   :Pages: 636
:ISBN: 0-596-00590-3
:Notes: Further information in
  http://www.oreilly.com/catalog/linuxdrive3/
@@ -473,74 +473,74 @@ BOOKS: (Not on-line)
 
  * Title: **Linux Kernel Internals**
 
-   :Author: Michael Beck.
-   :Publisher: Addison-Wesley.
-   :Date: 1997.
+   :Author: Michael Beck
+   :Publisher: Addison-Wesley
+   :Date: 1997
:ISBN: 0-201-33143-8 (second edition)
 
  * Title: **The Design of the UNIX Operating System**
 
-   :Author: Maurice J. Bach.
-   :Publisher: Prentice Hall.
-   :Date: 1986.
-   :Pages: 471.
+   :Author: Maurice J. Bach
+   :Publisher: Prentice Hall
+   :Date: 1986
+   :Pages: 471
:ISBN: 0-13-201757-1
 
  * Title: **The Design and Implementation of the 4.3 BSD UNIX Operating 
System**
 
-   :Author: Samuel J. Leffler, Marshall Kirk McKusick, Michael J.
- Karels, John S. Quarterman.
-   :Publisher: Addison-Wesley.
-   :Date: 1989 (reprinted with corrections on October, 1990).
+   :Author: Samuel J. Leffler, Marshall Kirk McKusick, Michael J
+ Karels, John S. Quarterman
+   :Publisher: Addison-Wesley
+   :Date: 1989 (reprinted with corrections on October, 1990)
:ISBN: 0-201-06196-1
 
  * Title: **The Design and Implementation of the 4.4 BSD UNIX Operating 
System**
 
:Author: Marshall Kirk McKusick, Keith Bostic, Michael J. Karels,
- John S. Quarterman.
-   :Publisher: Addison-Wesley.
-   :Date: 1996.
+ John S. Quarterman
+   :Publisher: Addison-Wesley
+   :Date: 1996
:ISBN: 0-201-54979-4
 
  * Title: **Programmation Linux 2.0 API systeme et fonctionnement du 
noyau**
 
-   :Author: Remy Card, Eric Dumas, Franck Mevel.
-   :Publisher: Eyrolles.
-   :Date: 1997.
-   :Pages: 520.
+   :Author: Remy Card, Eric Dumas, Franck Mevel
+   :Publisher: Eyrolles
+   :Date: 1997
+   :Pages: 520
:ISBN: 2-212-08932-5
-   :Notes: French.
+   :Notes: French
 
  * Title: **Unix internals -- the new frontiers**
 
-   :Author: Uresh Vahalia.
-   :Publisher: Prentice Hall.
-   :Date: 1996.
-   :Pages: 600.
+   :Author: Uresh Vahalia
+   :Publisher: Prentice Hall
+   :Date: 1996
+   :Pages: 600
:ISBN: 0-13-101908-2
 
  * Title: **Programming for the real world - POSIX.4**
 
-   :Author: Bill O. Gallmeister.
-   :Publisher: O'Reilly & Associates, Inc..
-   :Date: 1995.
-   :Pages: ???.
+   :Author: Bill O. Gallmeister
+   :Publisher: O'Reilly & Associates, Inc
+   :Date: 1995
+   :Pages: ???
:ISBN: I-56592-074-0
:Notes: Though not being directly about Linux, Linux aims to be
  POSIX. Good reference.
 
  * Title:  **UNIX  Systems  for  Modern Architectures: Symmetric 
Multiprocessing and Caching for Kernel Programmers**
 
-   :Author: Curt Schimmel.
-   :Publisher: Addison Wesley.
-   :Date: June, 1994.
-   :Pages: 432.
+   :Author: Curt Schimmel
+   :Publisher: Addison 

[PATCH 08/14] Documentation/kernel-docs.txt: sort books per publication date

[Mauro Carvalho Chehab]

Instead of using a random order, place the books on publication
date, from the newest to the oldest.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/kernel-docs.txt | 92 ++-
 1 file changed, 47 insertions(+), 45 deletions(-)

diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt
index 709644bc3bc7..0f4fa8b69769 100644
--- a/Documentation/kernel-docs.txt
+++ b/Documentation/kernel-docs.txt
@@ -451,9 +451,37 @@ On-line docs
   :Notes: For 2.0.x kernels. Gives guidances to port it to 2.2.x
 kernels.
 
+.. Please keep the published books in reverse publication date
+
 Published books
 ---
 
+* Title: **Linux Treiber entwickeln**
+
+  :Author: J??rgen Quade, Eva-Katharina Kunst
+  :Publisher: dpunkt.verlag
+  :Date: Oct 2015 (4th edition)
+  :Pages: 688
+  :ISBN: 978-3-86490-288-8
+  :Note: German. The third edition from 2011 is
+ much cheaper and still quite up-to-date.
+
+* Title: **Linux Kernel Networking: Implementation and Theory**
+
+  :Author: Rami Rosen
+  :Publisher: Apress
+  :Date: December 22, 2013
+  :Pages: 648
+  :ISBN: 978-1430261964
+
+* Title: **Linux Kernel Development, 3rd Edition**
+
+  :Author: Robert Love
+  :Publisher: Addison-Wesley
+  :Date: July, 2010
+  :Pages: 440
+  :ISBN: 978-0672329463
+
 .. _ldd3_published:
 
 * Title: **Linux Device Drivers, 3rd Edition**
@@ -474,30 +502,6 @@ Published books
   :Date: 1997
   :ISBN: 0-201-33143-8 (second edition)
 
-* Title: **The Design of the UNIX Operating System**
-
-  :Author: Maurice J. Bach
-  :Publisher: Prentice Hall
-  :Date: 1986
-  :Pages: 471
-  :ISBN: 0-13-201757-1
-
-* Title: **The Design and Implementation of the 4.3 BSD UNIX Operating 
System**
-
-  :Author: Samuel J. Leffler, Marshall Kirk McKusick, Michael J
-Karels, John S. Quarterman
-  :Publisher: Addison-Wesley
-  :Date: 1989 (reprinted with corrections on October, 1990)
-  :ISBN: 0-201-06196-1
-
-* Title: **The Design and Implementation of the 4.4 BSD UNIX Operating 
System**
-
-  :Author: Marshall Kirk McKusick, Keith Bostic, Michael J. Karels,
-John S. Quarterman
-  :Publisher: Addison-Wesley
-  :Date: 1996
-  :ISBN: 0-201-54979-4
-
 * Title: **Programmation Linux 2.0 API systeme et fonctionnement du noyau**
 
   :Author: Remy Card, Eric Dumas, Franck Mevel
@@ -507,6 +511,14 @@ Published books
   :ISBN: 2-212-08932-5
   :Notes: French
 
+* Title: **The Design and Implementation of the 4.4 BSD UNIX Operating 
System**
+
+  :Author: Marshall Kirk McKusick, Keith Bostic, Michael J. Karels,
+John S. Quarterman
+  :Publisher: Addison-Wesley
+  :Date: 1996
+  :ISBN: 0-201-54979-4
+
 * Title: **Unix internals -- the new frontiers**
 
   :Author: Uresh Vahalia
@@ -533,31 +545,21 @@ Published books
   :Pages: 432
   :ISBN: 0-201-63338-8
 
-* Title: **Linux Kernel Development, 3rd Edition**
+* Title: **The Design and Implementation of the 4.3 BSD UNIX Operating 
System**
 
-  :Author: Robert Love
+  :Author: Samuel J. Leffler, Marshall Kirk McKusick, Michael J
+Karels, John S. Quarterman
   :Publisher: Addison-Wesley
-  :Date: July, 2010
-  :Pages: 440
-  :ISBN: 978-0672329463
+  :Date: 1989 (reprinted with corrections on October, 1990)
+  :ISBN: 0-201-06196-1
 
-* Title: **Linux Kernel Networking: Implementation and Theory**
+* Title: **The Design of the UNIX Operating System**
 
-  :Author: Rami Rosen
-  :Publisher: Apress
-  :Date: December 22, 2013
-  :Pages: 648
-  :ISBN: 978-1430261964
-
-* Title: **Linux Treiber entwickeln**
-
-  :Author: J??rgen Quade, Eva-Katharina Kunst
-  :Publisher: dpunkt.verlag
-  :Date: Oct 2015 (4th edition)
-  :Pages: 688
-  :ISBN: 978-3-86490-288-8
-  :Note: German. The third edition from 2011 is
- much cheaper and still quite up-to-date.
+  :Author: Maurice J. Bach
+  :Publisher: Prentice Hall
+  :Date: 1986
+  :Pages: 471
+  :ISBN: 0-13-201757-1
 
 Miscellaneous
 -
-- 
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/14] Documentation/kernel-docs.txt: move in-kernel docs

[Mauro Carvalho Chehab]

There are three places where it mentions in-kernel docs.

Move them to a separate topic.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/kernel-docs.txt | 91 ++-
 1 file changed, 47 insertions(+), 44 deletions(-)

diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt
index 3b48deddd977..0bef9cfefd87 100644
--- a/Documentation/kernel-docs.txt
+++ b/Documentation/kernel-docs.txt
@@ -30,6 +30,53 @@ Document.
 
 Enjoy!
 
+Docs at the Linux Kernel tree
+-
+
+The DocBook books should be built with ``make {htmldocs | psdocs | pdfdocs}``.
+The Sphinx books should be built with ``make {htmldocs | pdfdocs | epubdocs}``.
+
+* Name: **linux/Documentation**
+
+  :Author: Many.
+  :Location: Documentation/
+  :Keywords: text files, Sphinx, DocBook.
+  :Description: Documentation that comes with the kernel sources,
+inside the Documentation directory. Some pages from this document
+(including this document itself) have been moved there, and might
+be more up to date than the web version.
+
+* Title: **The Kernel Hacking HOWTO**
+
+  :Author: Various Talented People, and Rusty.
+  :Location: Documentation/DocBook/kernel-hacking.tmpl
+  :Keywords: HOWTO, kernel contexts, deadlock, locking, modules,
+symbols, return conventions.
+  :Description: From the Introduction: "Please understand that I
+never wanted to write this document, being grossly underqualified,
+but I always wanted to read it, and this was the only way. I
+simply explain some best practices, and give reading entry-points
+into the kernel sources. I avoid implementation details: that's
+what the code is for, and I ignore whole tracts of useful
+routines. This document assumes familiarity with C, and an
+understanding of what the kernel is, and how it is used. It was
+originally written for the 2.3 kernels, but nearly all of it
+applies to 2.2 too; 2.0 is slightly different".
+
+* Title: **Linux Kernel Locking HOWTO**
+
+  :Author: Various Talented People, and Rusty.
+  :Location: Documentation/DocBook/kernel-locking.tmpl
+  :Keywords: locks, locking, spinlock, semaphore, atomic, race
+condition, bottom halves, tasklets, softirqs.
+  :Description: The title says it all: document describing the
+locking system in the Linux Kernel either in uniprocessor or SMP
+systems.
+  :Notes: "It was originally written for the later (>2.3.47) 2.3
+kernels, but most of it applies to 2.2 too; 2.0 is slightly
+different". Freely redistributable under the conditions of the GNU
+General Public License.
+
 On-line docs
 
 
@@ -266,24 +313,6 @@ On-line docs
 want a mechanism that is scalable. This means a large number of
 inactive FDs cost very little in memory and CPU time to manage".
 
-* Title: **The Kernel Hacking HOWTO**
-
-  :Author: Various Talented People, and Rusty.
-  :Location: in kernel tree, Documentation/DocBook/kernel-hacking.tmpl
-(must be built as "make {htmldocs | psdocs | pdfdocs})
-  :Keywords: HOWTO, kernel contexts, deadlock, locking, modules,
-symbols, return conventions.
-  :Description: From the Introduction: "Please understand that I
-never wanted to write this document, being grossly underqualified,
-but I always wanted to read it, and this was the only way. I
-simply explain some best practices, and give reading entry-points
-into the kernel sources. I avoid implementation details: that's
-what the code is for, and I ignore whole tracts of useful
-routines. This document assumes familiarity with C, and an
-understanding of what the kernel is, and how it is used. It was
-originally written for the 2.3 kernels, but nearly all of it
-applies to 2.2 too; 2.0 is slightly different".
-
 * Title: **Writing an ALSA Driver**
 
   :Author: Takashi Iwai 
@@ -302,21 +331,6 @@ On-line docs
 a brief description of some of the acronyms and terms you may hear
 during discussion of the Linux kernel".
 
-* Title: **Linux Kernel Locking HOWTO**
-
-  :Author: Various Talented People, and Rusty.
-  :Location: in kernel tree, Documentation/DocBook/kernel-locking.tmpl
-(must be built as "make {htmldocs | psdocs | pdfdocs})
-  :Keywords: locks, locking, spinlock, semaphore, atomic, race
-condition, bottom halves, tasklets, softirqs.
-  :Description: The title says it all: document describing the
-locking system in the Linux Kernel either in uniprocessor or SMP
-systems.
-  :Notes: "It was originally written for the later (>2.3.47) 2.3
-kernels, but most of it applies to 2.2 too; 2.0 is slightly
-

[PATCH 13/14] Documentation/kernel-docs.txt: Add dates for online docs

[Mauro Carvalho Chehab]

It is a way better to have a timestamp to help identifying
when something is too old.

So, retrieve the dates marked on the existing documents.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/kernel-docs.txt | 52 +++
 1 file changed, 43 insertions(+), 9 deletions(-)

diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt
index 65ecee92db88..5f65f412e7f7 100644
--- a/Documentation/kernel-docs.txt
+++ b/Documentation/kernel-docs.txt
@@ -84,6 +84,7 @@ On-line docs
 
   :Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman
   :URL: http://lwn.net/Kernel/LDD3/
+  :Date: 2005
   :Description: A 600-page book covering the (2.6.10) driver
 programming API and kernel hacking in general.  Available under the
 Creative Commons Attribution-ShareAlike 2.0 license.
@@ -93,6 +94,7 @@ On-line docs
 
   :Author: Richard Gooch.
   :URL: http://www.mjmwired.net/kernel/Documentation/filesystems/vfs.txt
+  :Date: 2007
   :Keywords: VFS, File System, mounting filesystems, opening files,
 dentries, dcache.
   :Description: Brief introduction to the Linux Virtual File System.
@@ -104,6 +106,7 @@ On-line docs
 
   :Author: Ingo Molnar, Gadi Oxman and Miguel de Icaza.
   :URL: http://www.linuxjournal.com/article.php?sid=2391
+  :Date: 1997
   :Keywords: RAID, MD driver.
   :Description: Linux Journal Kernel Korner article. Here is its
   :Abstract: *A description of the implementation of the RAID-1,
@@ -115,6 +118,7 @@ On-line docs
 
   :Author: Alessandro Rubini.
   :URL: http://www.linuxjournal.com/article.php?sid=1219
+  :Date: 1996
   :Keywords: device driver, module, loading/unloading modules,
 allocating resources.
   :Description: Linux Journal Kernel Korner article. Here is its
@@ -129,6 +133,7 @@ On-line docs
 
   :Author: Alessandro Rubini.
   :URL: http://www.linuxjournal.com/article.php?sid=1220
+  :Date: 1996
   :Keywords: character driver, init_module, clean_up module,
 autodetection, mayor number, minor number, file operations,
 open(), close().
@@ -142,6 +147,7 @@ On-line docs
 
   :Author: Andi Kleen
   :URL: http://halobates.de/on-submitting-kernel-patches.pdf
+  :Date: 2008
   :Keywords: patches, review process, types of submissions, basic rules, 
case studies
   :Description: This paper gives several experience values on what types 
of patches
 there are and how likley they get merged.
@@ -152,6 +158,7 @@ On-line docs
 * Title: **Tracing the Way of Data in a TCP Connection through the Linux 
Kernel**
   :Author: Richard Sailer
   :URL: https://archive.org/details/linux_kernel_data_flow_short_paper
+  :Date: 2016
   :Keywords: Linux Kernel Networking, TCP, tracing, ftrace
   :Description: A seminar paper explaining ftrace and how to use it for
 understanding linux kernel internals,
@@ -169,6 +176,7 @@ On-line docs
 
   :Author: Georg v. Zezschwitz and Alessandro Rubini.
   :URL: http://www.linuxjournal.com/article.php?sid=1221
+  :Date: 1996
   :Keywords: read(), write(), select(), ioctl(), blocking/non
 blocking mode, interrupt handler.
   :Description: Linux Journal Kernel Korner article. Here is its
@@ -180,6 +188,7 @@ On-line docs
 
   :Author: Alessandro Rubini and Georg v. Zezschwitz.
   :URL: http://www.linuxjournal.com/article.php?sid=1222
+  :Date: 1996
   :Keywords: interrupts, irqs, DMA, bottom halves, task queues.
   :Description: Linux Journal Kernel Korner article. Here is its
   :Abstract: *This is the fourth in a series of articles about
@@ -195,6 +204,7 @@ On-line docs
 
   :Author: Georg v. Zezschwitz.
   :URL: http://www.linuxjournal.com/article.php?sid=1287
+  :Date: 1996
   :Keywords: address spaces, pages, pagination, page management,
 demand loading, swapping, memory protection, memory mapping, mmap,
 virtual memory areas (VMAs), vremap, PCI.
@@ -208,6 +218,7 @@ On-line docs
 
   :Author: Alan Cox.
   :URL: http://www.linuxjournal.com/article.php?sid=1312
+  :Date: 1996
   :Keywords: sk_buffs, network devices, protocol/link layer
 variables, network devices flags, transmit, receive,
 configuration, multicast.
@@ -220,6 +231,7 @@ On-line docs
 
   :Author: Michael K. Johnson.
   :URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html
+  :Date: 1997
   :Keywords: device drivers, files, VFS, kernel interface, character vs
 block devices, hardware interrupts, scsi, DMA, access to user memory,
 memory allocation, timers.
@@ -231,6 +243,7 @@ On-line docs
 
   :Author: Peter J. Braam.
   :URL: http://www.coda.cs.cmu.edu/doc/html/kernel-venus-protocol.html
+  :Date: 1998
   :Keywords: coda, filesystem, venus, cache manager.
   

[PATCH 10/14] Documentation/kernel-docs.txt: remove more legacy references

[Mauro Carvalho Chehab]

The Linux Kernel - This book is for Kernel 2.0.33

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/kernel-docs.txt | 17 -
 1 file changed, 17 deletions(-)

diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt
index 3c335bd58934..3b48deddd977 100644
--- a/Documentation/kernel-docs.txt
+++ b/Documentation/kernel-docs.txt
@@ -42,23 +42,6 @@ On-line docs
 Creative Commons Attribution-ShareAlike 2.0 license.
   :note: You can also :ref:`purchase a copy from O'Reilly or elsewhere  
`.
 
-* Title: **The Linux Kernel**
-
-  :Author: David A. Rusling.
-  :URL: http://www.tldp.org/LDP/tlk/tlk.html
-  :Keywords: everything!, book.
-  :Description: On line, 200 pages book describing most aspects of
-the Linux Kernel. Probably, the first reference for beginners.
-Lots of illustrations explaining data structures use and
-relationships in the purest Richard W. Stevens' style. Contents:
-"1.-Hardware Basics, 2.-Software Basics, 3.-Memory Management,
-4.-Processes, 5.-Interprocess Communication Mechanisms, 6.-PCI,
-7.-Interrupts and Interrupt Handling, 8.-Device Drivers, 9.-The
-File system, 10.-Networks, 11.-Kernel Mechanisms, 12.-Modules,
-13.-The Linux Kernel Sources, A.-Linux Data Structures, B.-The
-Alpha AXP Processor, C.-Useful Web and FTP Sites, D.-The GNU
-General Public License, Glossary". In short: a must have.
-
 * Title: **Conceptual Architecture of the Linux Kernel**
 
   :Author: Ivan T. Bowman.
-- 
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 14/14] Documentation/kernel-docs.txt: reorder based on timestamp

[Mauro Carvalho Chehab]

Reorder the on-line documents based on their timestamp or
copyright notes. More updated documents come first.

While here, add the number of pages for POSIX4 document.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/kernel-docs.txt | 536 +-
 1 file changed, 270 insertions(+), 266 deletions(-)

diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt
index 5f65f412e7f7..4a82edbd8df2 100644
--- a/Documentation/kernel-docs.txt
+++ b/Documentation/kernel-docs.txt
@@ -30,6 +30,11 @@ Document.
 
 Enjoy!
 
+.. note::
+
+   The documents on each section of this document are ordered by its
+   published date, from the newest to the oldest.
+
 Docs at the Linux Kernel tree
 -
 
@@ -80,15 +85,45 @@ The Sphinx books should be built with ``make {htmldocs | 
pdfdocs | epubdocs}``.
 On-line docs
 
 
-* Title: **Linux Device Drivers, Third Edition**
-
-  :Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman
-  :URL: http://lwn.net/Kernel/LDD3/
-  :Date: 2005
-  :Description: A 600-page book covering the (2.6.10) driver
-programming API and kernel hacking in general.  Available under the
-Creative Commons Attribution-ShareAlike 2.0 license.
-  :note: You can also :ref:`purchase a copy from O'Reilly or elsewhere  
`.
+* Title: **Linux Kernel Mailing List Glossary**
+
+  :Author: various
+  :URL: http://kernelnewbies.org/glossary/
+  :Date: rolling version
+  :Keywords: glossary, terms, linux-kernel.
+  :Description: From the introduction: "This glossary is intended as
+a brief description of some of the acronyms and terms you may hear
+during discussion of the Linux kernel".
+
+* Title: **Tracing the Way of Data in a TCP Connection through the Linux 
Kernel**
+
+  :Author: Richard Sailer
+  :URL: https://archive.org/details/linux_kernel_data_flow_short_paper
+  :Date: 2016
+  :Keywords: Linux Kernel Networking, TCP, tracing, ftrace
+  :Description: A seminar paper explaining ftrace and how to use it for
+understanding linux kernel internals,
+illustrated at tracing the way of a TCP packet through the kernel.
+  :Abstract: *This short paper outlines the usage of ftrace a tracing 
framework
+as a tool to understand a running Linux system.
+Having obtained a trace-log a kernel hacker can read and understand
+source code more determined and with context.
+In a detailed example this approach is demonstrated in tracing
+and the way of data in a TCP Connection through the kernel.
+Finally this trace-log is used as base for more a exact conceptual
+exploration and description of the Linux TCP/IP implementation.*
+
+* Title: **On submitting kernel Patches**
+
+  :Author: Andi Kleen
+  :URL: http://halobates.de/on-submitting-kernel-patches.pdf
+  :Date: 2008
+  :Keywords: patches, review process, types of submissions, basic rules, 
case studies
+  :Description: This paper gives several experience values on what types 
of patches
+there are and how likley they get merged.
+  :Abstract:
+[...]. This paper examines some common problems for
+submitting larger changes and some strategies to avoid problems.
 
 * Title: **Overview of the Virtual File System**
 
@@ -102,6 +137,218 @@ On-line docs
 mounting a file system and description of important data
 structures explaining the purpose of each of their entries.
 
+* Title: **Linux Device Drivers, Third Edition**
+
+  :Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman
+  :URL: http://lwn.net/Kernel/LDD3/
+  :Date: 2005
+  :Description: A 600-page book covering the (2.6.10) driver
+programming API and kernel hacking in general.  Available under the
+Creative Commons Attribution-ShareAlike 2.0 license.
+  :note: You can also :ref:`purchase a copy from O'Reilly or elsewhere  
`.
+
+* Title: **Writing an ALSA Driver**
+
+  :Author: Takashi Iwai 
+  :URL: http://www.alsa-project.org/~iwai/writing-an-alsa-driver/index.html
+  :Date: 2005
+  :Keywords: ALSA, sound, soundcard, driver, lowlevel, hardware.
+  :Description: Advanced Linux Sound Architecture for developers,
+both at kernel and user-level sides. ALSA is the Linux kernel
+sound architecture in the 2.6 kernel version.
+
+* Title: **Linux PCMCIA Programmer's Guide**
+
+  :Author: David Hinds.
+  :URL: http://pcmcia-cs.sourceforge.net/ftp/doc/PCMCIA-PROG.html
+  :Date: 2003
+  :Keywords: PCMCIA.
+  :Description: "This document describes how to write kernel device
+drivers for the Linux PCMCIA Card Services interface. It also
+describes how to write user-mode utilities for communicating with
+Card 

[PATCH 05/14] Documentation/kernel-docs.txt: Consistent indenting: 4 spaces

[Mauro Carvalho Chehab]

From: Richard Sailer 

This introduces a consistent indenting of 4 spaces for all
lists.

[mche...@s-opensource.com: rebased to apply before rename]

Signed-off-by: Richard Sailer 
Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/kernel-docs.txt | 1222 -
 1 file changed, 611 insertions(+), 611 deletions(-)

diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt
index c3a8462a4012..fc1474419c81 100644
--- a/Documentation/kernel-docs.txt
+++ b/Documentation/kernel-docs.txt
@@ -37,640 +37,640 @@ Enjoy!
 ON-LINE DOCS
 
 
- * Title: **Linux Device Drivers, Third Edition**
-
-   :Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman
-   :URL: http://lwn.net/Kernel/LDD3/
-   :Description: A 600-page book covering the (2.6.10) driver
- programming API and kernel hacking in general.  Available under the
- Creative Commons Attribution-ShareAlike 2.0 license.
-
- * Title: **The Linux Kernel**
-
-   :Author: David A. Rusling.
-   :URL: http://www.tldp.org/LDP/tlk/tlk.html
-   :Keywords: everything!, book.
-   :Description: On line, 200 pages book describing most aspects of
- the Linux Kernel. Probably, the first reference for beginners.
- Lots of illustrations explaining data structures use and
- relationships in the purest Richard W. Stevens' style. Contents:
- "1.-Hardware Basics, 2.-Software Basics, 3.-Memory Management,
- 4.-Processes, 5.-Interprocess Communication Mechanisms, 6.-PCI,
- 7.-Interrupts and Interrupt Handling, 8.-Device Drivers, 9.-The
- File system, 10.-Networks, 11.-Kernel Mechanisms, 12.-Modules,
- 13.-The Linux Kernel Sources, A.-Linux Data Structures, B.-The
- Alpha AXP Processor, C.-Useful Web and FTP Sites, D.-The GNU
- General Public License, Glossary". In short: a must have.
-
- * Title: **Linux Device Drivers, 2nd Edition**
-
-   :Author: Alessandro Rubini and Jonathan Corbet.
-   :URL: http://www.xml.com/ldd/chapter/book/index.html
-   :Keywords: device drivers, modules, debugging, memory, hardware,
- interrupt handling, char drivers, block drivers, kmod, mmap, DMA,
- buses.
-   :Description: O'Reilly's popular book, now also on-line under the
- GNU Free Documentation License.
-   :Notes: You can also buy it in paper-form from O'Reilly. See below
- under BOOKS (Not on-line).
-
- * Title: **Conceptual Architecture of the Linux Kernel**
-
-   :Author: Ivan T. Bowman.
-   :URL: http://plg.uwaterloo.ca/
-   :Keywords: conceptual software architecture, extracted design,
- reverse engineering, system structure.
-   :Description: Conceptual software architecture of the Linux kernel,
- automatically extracted from the source code. Very detailed. Good
- figures. Gives good overall kernel understanding.
-
- * Title: **Concrete Architecture of the Linux Kernel**
-
-   :Author: Ivan T. Bowman, Saheem Siddiqi, and Meyer C. Tanuan.
-   :URL: http://plg.uwaterloo.ca/
-   :Keywords: concrete architecture, extracted design, reverse
- engineering, system structure, dependencies.
-   :Description: Concrete architecture of the Linux kernel,
- automatically extracted from the source code. Very detailed. Good
- figures. Gives good overall kernel understanding. This papers
- focus on lower details than its predecessor (files, variables...).
-
- * Title: **Linux as a Case Study: Its Extracted Software Architecture**
-
-   :Author: Ivan T. Bowman, Richard C. Holt and Neil V. Brewster.
-   :URL: http://plg.uwaterloo.ca/
-   :Keywords: software architecture, architecture recovery,
- redocumentation.
-   :Description: Paper appeared at ICSE'99, Los Angeles, May 16-22,
- 1999. A mixture of the previous two documents from the same
- author.
-
- * Title: **Overview of the Virtual File System**
-
-   :Author: Richard Gooch.
-   :URL: http://www.mjmwired.net/kernel/Documentation/filesystems/vfs.txt
-   :Keywords: VFS, File System, mounting filesystems, opening files,
- dentries, dcache.
-   :Description: Brief introduction to the Linux Virtual File System.
- What is it, how it works, operations taken when opening a file or
- mounting a file system and description of important data
- structures explaining the purpose of each of their entries.
-
- * Title: **The Linux RAID-1, 4, 5 Code**
-
-   :Author: Ingo Molnar, Gadi Oxman and Miguel de Icaza.
-   :URL: http://www.linuxjournal.com/article.php?sid=2391
-   :Keywords: RAID, MD driver.
-   :Description: Linux Journal Kernel Korner article. Here is its
-   :Abstract: *A description of the implementation of the 

[PATCH 12/14] Documentation/kernel-docs.txt: get rid of broken docs

[Mauro Carvalho Chehab]

There are still some broken docs: the URLs point to somewhere,
however, the texts are not there anymore. I was able to
find the texts on other URLs for some of those, but they're all
too old. So, just get rid of them.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/kernel-docs.txt | 41 -
 1 file changed, 41 deletions(-)

diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt
index 0bef9cfefd87..65ecee92db88 100644
--- a/Documentation/kernel-docs.txt
+++ b/Documentation/kernel-docs.txt
@@ -89,37 +89,6 @@ On-line docs
 Creative Commons Attribution-ShareAlike 2.0 license.
   :note: You can also :ref:`purchase a copy from O'Reilly or elsewhere  
`.
 
-* Title: **Conceptual Architecture of the Linux Kernel**
-
-  :Author: Ivan T. Bowman.
-  :URL: http://plg.uwaterloo.ca/
-  :Keywords: conceptual software architecture, extracted design,
-reverse engineering, system structure.
-  :Description: Conceptual software architecture of the Linux kernel,
-automatically extracted from the source code. Very detailed. Good
-figures. Gives good overall kernel understanding.
-
-* Title: **Concrete Architecture of the Linux Kernel**
-
-  :Author: Ivan T. Bowman, Saheem Siddiqi, and Meyer C. Tanuan.
-  :URL: http://plg.uwaterloo.ca/
-  :Keywords: concrete architecture, extracted design, reverse
-engineering, system structure, dependencies.
-  :Description: Concrete architecture of the Linux kernel,
-automatically extracted from the source code. Very detailed. Good
-figures. Gives good overall kernel understanding. This papers
-focus on lower details than its predecessor (files, variables...).
-
-* Title: **Linux as a Case Study: Its Extracted Software Architecture**
-
-  :Author: Ivan T. Bowman, Richard C. Holt and Neil V. Brewster.
-  :URL: http://plg.uwaterloo.ca/
-  :Keywords: software architecture, architecture recovery,
-redocumentation.
-  :Description: Paper appeared at ICSE'99, Los Angeles, May 16-22,
-1999. A mixture of the previous two documents from the same
-author.
-
 * Title: **Overview of the Virtual File System**
 
   :Author: Richard Gooch.
@@ -577,16 +546,6 @@ Published books
 Miscellaneous
 -
 
-
-  :Author: Thomas Graichen.
-  :URL: http://marc.info/?l=linux-kernel=96446640102205=4
-  :Keywords: CVS, web, cvsweb, browsing source code.
-  :Description: Web interface to a CVS server with the kernel
-sources. "Here you can have a look at any file of the Linux kernel
-sources of any version starting from 1.0 up to the (daily updated)
-current version available. Also you can check the differences
-between two versions of a file".
-
 * Name: **Cross-Referencing Linux**
 
   :URL: http://lxr.free-electrons.com/
-- 
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 07/14] Documentation/kernel-docs.txt: adjust LDD references

[Mauro Carvalho Chehab]

- remove LDD versions 1 and 2, as there's already an entry for
  LDD3;
- add a link between LDD online and published entries.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/kernel-docs.txt | 31 ++-
 1 file changed, 2 insertions(+), 29 deletions(-)

diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt
index 5493f8bbe45a..709644bc3bc7 100644
--- a/Documentation/kernel-docs.txt
+++ b/Documentation/kernel-docs.txt
@@ -40,6 +40,7 @@ On-line docs
   :Description: A 600-page book covering the (2.6.10) driver
 programming API and kernel hacking in general.  Available under the
 Creative Commons Attribution-ShareAlike 2.0 license.
+  :note: You can also :ref:`purchase a copy from O'Reilly or elsewhere  
`.
 
 * Title: **The Linux Kernel**
 
@@ -58,18 +59,6 @@ On-line docs
 Alpha AXP Processor, C.-Useful Web and FTP Sites, D.-The GNU
 General Public License, Glossary". In short: a must have.
 
-* Title: **Linux Device Drivers, 2nd Edition**
-
-  :Author: Alessandro Rubini and Jonathan Corbet.
-  :URL: http://www.xml.com/ldd/chapter/book/index.html
-  :Keywords: device drivers, modules, debugging, memory, hardware,
-interrupt handling, char drivers, block drivers, kmod, mmap, DMA,
-buses.
-  :Description: O'Reilly's popular book, now also on-line under the
-GNU Free Documentation License.
-  :Notes: You can also buy it in paper-form from O'Reilly. See below
-under BOOKS (Not on-line).
-
 * Title: **Conceptual Architecture of the Linux Kernel**
 
   :Author: Ivan T. Bowman.
@@ -465,23 +454,7 @@ On-line docs
 Published books
 ---
 
-* Title: **Linux Device Drivers**
-
-  :Author: Alessandro Rubini
-  :Publisher: O'Reilly & Associates
-  :Date: 1998
-  :Pages: 439
-  :ISBN: 1-56592-292-1
-
-* Title: **Linux Device Drivers, 2nd Edition**
-
-  :Author: Alessandro Rubini and Jonathan Corbet
-  :Publisher: O'Reilly & Associates
-  :Date: 2001
-  :Pages: 586
-  :ISBN: 0-59600-008-1
-  :Notes: Further information in
-http://www.oreilly.com/catalog/linuxdrive2/
+.. _ldd3_published:
 
 * Title: **Linux Device Drivers, 3rd Edition**
 
-- 
2.7.4


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

Re: [PATCH 0/4] Update kernel-docs.rst

[Mauro Carvalho Chehab]

Em Tue, 20 Sep 2016 02:40:21 +0200
Richard Sailer  escreveu:

> I think kernel-docs.rst should be kept. (Or at least another/updated
> file fullfilling this purpose should exist) Therefore I put 
> some effort into updating it.
> 
> This patch relies on Mauros: 
>[Patch v2 ...] Create a book for Kernel development
> 
> 
> Summary
> ---
> This patch: 
> 
>  * Removes all the dead links according to Jon and Mauro in 
>https://lkml.kernel.org/r/20160916182849.2a7101ea () vento ! lan
> 
>  * Removes some very old articles covering linux 2.0 or 2.2 
>(I could have been cleaning up much more aggressive, but 
> I wanted to be carefull for the first patch. I can send a 
> further patch deleting several more IMHO outdated entries 
> if this is appreciated/wanted.)
> 
>  * Adds 4 recent books/articles, which are helpfull IMHO
> 
>  * Fixes some minor layouting and indentation issues
> 
> 
> kernel-docs.rst: Remove offline or outdated entries
> kernel-docs.rst: Improve layouting of book list
> kernel-docs.rst: Add 4 paper/book references
> kernel-docs.rst: Consistent indenting: 4 spaces

Looks good to me.

Reviewed-by: Mauro Carvalho Chehab 

I actually rebased them on my tree to apply them before the patch that
renames everything, and added on my experimental tree:

https://git.linuxtv.org//mchehab/experimental.git/log/?h=docs-next

I couldn't resist: I made my own set of patches improving it,
adding timestamps to all online documents, removing some stuff,
adding other stuff, etc ;)

I updated the documents at mchehab.fedorapeople.org to reflect the
changes:

HTML:   https://mchehab.fedorapeople.org/development-process/
LaTex:  
https://mchehab.fedorapeople.org/development-process/latex/development-process.tex
PDF:
https://mchehab.fedorapeople.org/development-process/latex/development-process.pdf
  
ePub:   
https://mchehab.fedorapeople.org/development-process/epub/LinuxKernelDevelopmentDocumentation.epub

I'll be sending such patch series in a few.

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

XDP (eXpress Data Path) documentation

[Jesper Dangaard Brouer]

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 ;-))

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

Re: [PATCH v4 22/29] Documentation/HOWTO: add cross-references to other documents

[Greg KH]

On Mon, Sep 19, 2016 at 08:07:56AM -0300, Mauro Carvalho Chehab wrote:
> Add cross references for the documents mentioned at HOWTO and
> are under the Documentation/ directory, using the ReST notation.
> 
> It should be noticed that HOWTO also mentions the /README file.
> We opted to not touch it, for now, as making it build on
> Sphinx would require it to be moved to a Documentation/foo
> directory.
> 
> Signed-off-by: Mauro Carvalho Chehab 
> ---


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

Re: [PATCH v4 17/29] Documentation/stable_kernel_rules.txt: convert it to ReST markup

[Greg KH]

On Mon, Sep 19, 2016 at 08:07:51AM -0300, Mauro Carvalho Chehab wrote:
> - use ReST markups for section headers;
> - add cross-references to the options;
> - mark code blocks;
> - a few minor changes to make Sphinx happy.
> 
> Signed-off-by: Mauro Carvalho Chehab 
> ---
>  Documentation/stable_kernel_rules.txt | 101 
> +++---
>  1 file changed, 68 insertions(+), 33 deletions(-)
> 

Acked-by: Greg Kroah-Hartman 
--
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 (was Re: [PATCH 03/47] block-rbd: Adjust the position of a jump label in rbd_header_from_disk())

[Julia Lawall]

On Mon, 19 Sep 2016, Joe Perches wrote:

> On Tue, 2016-09-20 at 07:53 +0200, Julia Lawall wrote:
> > On Mon, 19 Sep 2016, Joe Perches wrote:
> > > On Tue, 2016-09-20 at 01:11 +0100, Al Viro wrote:
> > > > IMO what we need is to go through all rules in CodingStyle and if for
> > > > some rule there is no overwhelming majority in the core kernel, well,
> > > > the list has grown way too large and could use massive trimming.
> > >
> > > I'm in complete agreement.
> > >
> > > I also think that checkpatch's ERROR/WARNING/CHECK message naming is
> > > far too severe and injunctive and could use a renaming to something
> > > more silly, bug related and less commanding like FLEAS/GNATS/NITS.
> > 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,

It's not necessarily the case that changing the error type will change the
behavior of the persons in question.

> Maybe prefix various different types of style messages.
>
> Something like:
>
> ERROR -> CODE_STYLE_DEFECT
> WARNING -> CODE_STYLE_UNPREFERRED
> CHECK -> CODE_STYLE_NIT
>
> I doubt additional external documentation would help much.
>
> Some checkpatch bleats really are errors though.

Maybe just downgrade more things?

Perhaps SUGGESTION would be more clear than CHECK?

julia

Re: "CodingStyle: Clarify and complete chapter 7" in docs-next (was Re: [PATCH 03/47] block-rbd: Adjust the position of a jump label in rbd_header_from_disk())

[Joe Perches]

On Tue, 2016-09-20 at 07:53 +0200, Julia Lawall wrote:
> On Mon, 19 Sep 2016, Joe Perches wrote:
> > On Tue, 2016-09-20 at 01:11 +0100, Al Viro wrote:
> > > IMO what we need is to go through all rules in CodingStyle and if for
> > > some rule there is no overwhelming majority in the core kernel, well,
> > > the list has grown way too large and could use massive trimming.
> >
> > I'm in complete agreement.
> >
> > I also think that checkpatch's ERROR/WARNING/CHECK message naming is
> > far too severe and injunctive and could use a renaming to something
> > more silly, bug related and less commanding like FLEAS/GNATS/NITS.
> 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,

Maybe prefix various different types of style messages.

Something like:

ERROR   -> CODE_STYLE_DEFECT
WARNING -> CODE_STYLE_UNPREFERRED
CHECK   -> CODE_STYLE_NIT

I doubt additional external documentation would help much.

Some checkpatch bleats really are errors though.
--
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 5/8] samples: move misc-devices/mei example code from Documentation

[Winkler, Tomas]

> -Original Message-
> From: Jonathan Corbet [mailto:cor...@lwn.net]
> Sent: Monday, September 19, 2016 19:14
> To: Shuah Khan 
> Cc: Dutt, Sudeep ; Dixit, Ashutosh
> ; Winkler, Tomas ;
> t...@linutronix.de; w...@iguana.be; li...@roeck-us.net;
> elfr...@users.sourceforge.net; nicolas.dich...@6wind.com;
> da...@davemloft.net; gre...@linuxfoundation.org; Chandramouli,
> Dasaratharaman ;
> maheshkhanwal...@gmail.com; mikedan...@google.com;
> b...@decadent.org.uk; ghackm...@google.com; linux-doc@vger.kernel.org;
> linux-ker...@vger.kernel.org; linux-pcm...@lists.infradead.org; linux-
> watch...@vger.kernel.org
> Subject: Re: [PATCH 5/8] samples: move misc-devices/mei example code
> from Documentation
> 
> On Mon, 19 Sep 2016 08:47:36 -0600
> Shuah Khan  wrote:
> 
> > Move misc-devices/mei examples to samples/mei and remove it from
> > Documentation Makefile. Delete misc-devices/Makefile.
> >
> > Create a new Makefile to build samples/mei. It can be built from top
> > level directory or from mei directory:
> 
> This one still has a fair amount of code hiding in the .txt files, but that's 
> a
> separate job.
> 
> Acked-by: Jonathan Corbet 

Shouldn't  this update also the  MAINTAINERS file?
Tomas

--
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