[PATCH] bpf, doc: clarification for the meaning of 'id'

[Wang YanQing]

For me, as a reader whose mother language isn't English, the
old words bring a little difficulty to catch the meaning, this
patch rewords the subsection in a more clarificatory way.

This patch also add blank lines as separator at two places
to improve readability.

Signed-off-by: Wang YanQing 
---
 Documentation/networking/filter.txt | 15 +--
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/Documentation/networking/filter.txt 
b/Documentation/networking/filter.txt
index 5032e12..e6b4ebb 100644
--- a/Documentation/networking/filter.txt
+++ b/Documentation/networking/filter.txt
@@ -1142,6 +1142,7 @@ into a register from memory, the register's top 56 bits 
are known zero, while
 the low 8 are unknown - which is represented as the tnum (0x0; 0xff).  If we
 then OR this with 0x40, we get (0x40; 0xbf), then if we add 1 we get (0x0;
 0x1ff), because of potential carries.
+
 Besides arithmetic, the register state can also be updated by conditional
 branches.  For instance, if a SCALAR_VALUE is compared > 8, in the 'true' 
branch
 it will have a umin_value (unsigned minimum value) of 9, whereas in the 'false'
@@ -1150,14 +1151,16 @@ BPF_JSGE) would instead update the signed 
minimum/maximum values.  Information
 from the signed and unsigned bounds can be combined; for instance if a value is
 first tested < 8 and then tested s> 4, the verifier will conclude that the 
value
 is also > 4 and s< 8, since the bounds prevent crossing the sign boundary.
+
 PTR_TO_PACKETs with a variable offset part have an 'id', which is common to all
 pointers sharing that same variable offset.  This is important for packet range
-checks: after adding some variable to a packet pointer, if you then copy it to
-another register and (say) add a constant 4, both registers will share the same
-'id' but one will have a fixed offset of +4.  Then if it is bounds-checked and
-found to be less than a PTR_TO_PACKET_END, the other register is now known to
-have a safe range of at least 4 bytes.  See 'Direct packet access', below, for
-more on PTR_TO_PACKET ranges.
+checks: after adding a variable to a packet pointer register A, if you then 
copy
+it to another register B and then add a constant 4 to A, both registers will
+share the same 'id' but the A will have a fixed offset of +4.  Then if A is
+bounds-checked and found to be less than a PTR_TO_PACKET_END, the register B is
+now known to have a safe range of at least 4 bytes.  See 'Direct packet 
access',
+below, for more on PTR_TO_PACKET ranges.
+
 The 'id' field is also used on PTR_TO_MAP_VALUE_OR_NULL, common to all copies 
of
 the pointer returned from a map lookup.  This means that when one copy is
 checked and found to be non-NULL, all copies can become PTR_TO_MAP_VALUEs.
-- 
1.8.5.6.2.g3d8a54e.dirty
--
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 2/2] ThunderX2: Add Cavium ThunderX2 SoC UNCORE PMU driver

[Kim Phillips]

On Fri, 4 May 2018 18:10:44 +0100
Robin Murphy  wrote:

> Hi Kim,

Hi Robin,

> On 04/05/18 01:30, Kim Phillips wrote:
> > On Tue, 1 May 2018 12:54:05 +0100
> > Will Deacon  wrote:
> >> On Fri, Apr 27, 2018 at 11:56:25AM -0500, Kim Phillips wrote:
> >>> On Fri, 27 Apr 2018 17:09:14 +0100
> >>> Will Deacon  wrote:
>  On Fri, Apr 27, 2018 at 10:46:29AM -0500, Kim Phillips wrote:
> > On Fri, 27 Apr 2018 15:37:20 +0100
> > Will Deacon  wrote:
> >> For anything under drivers/perf/, I'd prefer not to have these prints
> >> and instead see efforts to improve error reporting via the perf system
> >> call interface.
> >
> > We'd all prefer that, and for all PMU drivers, why should ones under
> > drivers/perf be treated differently?
> 
>  Because they're the ones I maintain...
> >>>
> >>> You represent a minority on your opinion on this matter though.
> >>
> >> I'm not sure that's true
> > 
> > I haven't seen another arch/PMU driver maintainer actively oppose it
> > other than you (and Mark).
> > 
> >> -- you tend to be the only one raising this issue;
> > 
> > If you're basing that on list activity, I wouldn't, since most Arm perf
> > users don't subscribe to LKML.  I'm trying to represent current and
> > future Arm perf users that shouldn't be expected to hang out here on
> > LKML and review PMU drivers.  Couldn't tell you why PMU driver authors
> > themselves don't chime in, but will note that some drivers in
> > drivers/perf do print things from their event_init functions.
> 
> As a PMU driver author who *has* already invested not-inconsiderable 
> time and effort in trying to explain to you the technical issues from a 
> non-maintainer perspective (and is about to do so again), I can't help 
> but feel rather slighted by that comment.

Very sorry!  You're quite right.  I believe I had considered you as a
kernel developer first, and was trying to keep LKML activity affined to
LKML, vs. other activity on other mailing lists.

> > Also, you have been cc'd on off-list email threads where SPE users had
> > to debug the SPE driver's event_init() manually.  There are other SPE
> > users I know that have had to go through the same painstaking process of
> > debugging the SPE driver.  Last but not least, there's me, and I'd sure
> > appreciate more verbose PMU drivers, based on my real-life performance
> > monitoring experience(s).
> > 
> >> I think most people don't actually care one way or the other. If you know 
> >> of
> > 
> > Like I said, I think you're limiting your audience to LKML subscribers,
> > who are more amenable to being convinced they need to debug their
> > kernel.
> > 
> >> others who care about it too then I suggest you work together as a group to
> >> solve the problem in a way which is amenable to the upstream maintainers.
> > 
> > I know a few off-list people that would like a more user-friendly Arm
> > perf experience, but we're not qualified to solve the larger problem
> > that perf has had since its inception, and I think it's a little unfair
> > for you to suggest that, esp. given you're one of the maintainers, and
> > there's Linus on top of you.
> > 
> >> Then you won't have to worry about fixing it personally. You could even
> >> propose a topic for plumbers if there is enough interest in a general
> >> framework for propagating error messages to userspace.
> > 
> > I'm not worried about fixing it personally or not.  I'm worried about
> > our perf users' experience given your objection to using the vehicle
> > already in use on other architectures and PMU drivers.
> > 
> > If you - or anyone else for that matter - know of a way that'll get us
> > past this, by all means, say something.
> > 
> > If it helps, I recently asked acme if we could borrow bits from struct
> > perf_event and got no response.
> > 
> > As you are already aware, I've personally tried to fix this problem -
> > that has existed since before the introduction of the perf tool (I
> > consider it a syscall-independent enhanced error interface), multiple
> > times, and failed.
> 
>  Why is that my problem? Try harder?
> >>>
> >>> It's your problem because we're here reviewing a patch that happens to
> >>> fall under your maintainership.  I'll be the first person to tell you
> >>> I'm obviously incompetent and haven't been able to come up with a
> >>> solution that is acceptable for everyone up to and including Linus
> >>> Torvalds.  I'm just noticing a chronic usability problem that can be
> >>> easily alleviated in the context of this patch review.
> >>
> >> I don't see how incompetence has anything to do with it and, like most
> > 
> > Well you told me to try harder, and I'm trying to let you know that I
> > can try harder - ad infinitum - and still not get it, so telling me to
> > try harder isn't going to necessarily resolve the issue.
> > 
> >> people (lucky gits...), I 

Re: [PATCH v7 1/4] ipc: IPCMNI limit check for msgmni and shmmni

[Luis R. Rodriguez]

On Mon, May 07, 2018 at 07:57:12PM -0400, Waiman Long wrote:
> On 05/07/2018 06:39 PM, Luis R. Rodriguez wrote:
> > On Mon, May 07, 2018 at 04:59:09PM -0400, Waiman Long wrote:
> >> A user can write arbitrary integer values to msgmni and shmmni sysctl
> >> parameters without getting error, but the actual limit is really
> >> IPCMNI (32k). This can mislead users as they think they can get a
> >> value that is not real.
> >>
> >> The right limits are now set for msgmni and shmmni so that the users
> >> will become aware if they set a value outside of the acceptable range.
> >>
> >> Signed-off-by: Waiman Long 
> >> ---
> >>  ipc/ipc_sysctl.c | 7 +--
> >>  1 file changed, 5 insertions(+), 2 deletions(-)
> >>
> >> diff --git a/ipc/ipc_sysctl.c b/ipc/ipc_sysctl.c
> >> index 8ad93c2..f87cb29 100644
> >> --- a/ipc/ipc_sysctl.c
> >> +++ b/ipc/ipc_sysctl.c
> >> @@ -99,6 +99,7 @@ static int proc_ipc_auto_msgmni(struct ctl_table *table, 
> >> int write,
> >>  static int zero;
> >>  static int one = 1;
> >>  static int int_max = INT_MAX;
> >> +static int ipc_mni = IPCMNI;
> >>  
> >>  static struct ctl_table ipc_kern_table[] = {
> >>{
> >> @@ -120,7 +121,9 @@ static int proc_ipc_auto_msgmni(struct ctl_table 
> >> *table, int write,
> >>.data   = _ipc_ns.shm_ctlmni,
> >>.maxlen = sizeof(init_ipc_ns.shm_ctlmni),
> >>.mode   = 0644,
> >> -  .proc_handler   = proc_ipc_dointvec,
> >> +  .proc_handler   = proc_ipc_dointvec_minmax,
> >> +  .extra1 = ,
> >> +  .extra2 = _mni,
> >>},
> >>{
> >>.procname   = "shm_rmid_forced",
> >> @@ -147,7 +150,7 @@ static int proc_ipc_auto_msgmni(struct ctl_table 
> >> *table, int write,
> >>.mode   = 0644,
> >>.proc_handler   = proc_ipc_dointvec_minmax,
> >>.extra1 = ,
> >> -  .extra2 = _max,
> >> +  .extra2 = _mni,
> >>},
> >>{
> >>.procname   = "auto_msgmni",
> >> -- 
> >> 1.8.3.1
> > It seems negative values are not allowed, if true then having
> > a caller to use proc_douintvec_minmax() would help with ensuring
> > no invalid negative input values are used as well.
> >
> >   Luis
> 
> Negative value doesn't mean sense here. So it is true that we can use
> proc_douintvec_minmax() instead. However, the data types themselves are
> defined as "int". So I think it is better to keep using
> proc_dointvec_minmax() to be consistent with the data type.

Huh, no... If you *know* the valid values *are* only positive, the right
thing to do is to then *change* the data type. Tons of odd bugs can creep
up because of these stupid things.

  Luis
--
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 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Peter Zijlstra]

On Wed, May 09, 2018 at 12:35:40PM -0600, Jonathan Corbet wrote:
> On Wed, 9 May 2018 17:20:26 +0200
> Peter Zijlstra  wrote:
> 
> > The whole rst wankery is detrimental to that interface in order to
> > pander to something else.. I don't see the value. I've objected before,
> > and I suppose I'll object again.
> 
> One person's wankery is another's integrated, browsable, and searchable
> documentation that shows some signs of having actually been thought about,
> I guess.

Browsable is what we have ctags/cscope for and searchable is git-grep, right?
--
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 11/11] docs: fix broken references with multiple hints

[James Morris]

On Wed, 9 May 2018, Mauro Carvalho Chehab wrote:

> The script:
>   ./scripts/documentation-file-ref-check --fix-rst
> 
> Gives multiple hints for broken references on some files.
> Manually use the one that applies for some files.
> 
> Signed-off-by: Mauro Carvalho Chehab 


Acked-by: James Morris 


-- 
James Morris


--
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 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Markus Heiser]

> Am 09.05.2018 um 20:35 schrieb Jonathan Corbet :
> 
>> Why should I care for people not using text editors to write code?

Eh? .. why must readers write code?

We have rules how to write kernel-doc markup since the beginning of the century.
If you do not want to contribute kernel-doc markups, then just leave it, change
your comment start-tag to

 /*

and feel free to type what ever you want. Sorry, but this discussion is 
superfluous.

-- Markus -




--
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 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Jonathan Corbet]

On Wed, 9 May 2018 17:20:26 +0200
Peter Zijlstra  wrote:

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

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

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

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

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

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

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

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

Thanks,

jon
--
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 16/18] mtd: rawnand.h: use nested union kernel-doc markups

[Boris Brezillon]

On Mon,  7 May 2018 06:35:52 -0300
Mauro Carvalho Chehab  wrote:

> Gets rid of those warnings and better document the parameters.
> 
>   ./include/linux/mtd/rawnand.h:752: warning: Function parameter or member 
> 'timings.sdr' not described in 'nand_data_interface'
>   ./include/linux/mtd/rawnand.h:817: warning: Function parameter or member 
> 'buf' not described in 'nand_op_data_instr'
>   ./include/linux/mtd/rawnand.h:817: warning: Function parameter or member 
> 'buf.in' not described in 'nand_op_data_instr'
>   ./include/linux/mtd/rawnand.h:817: warning: Function parameter or member 
> 'buf.out' not described in 'nand_op_data_instr'
>   ./include/linux/mtd/rawnand.h:863: warning: Function parameter or member 
> 'ctx' not described in 'nand_op_instr'
>   ./include/linux/mtd/rawnand.h:863: warning: Function parameter or member 
> 'ctx.cmd' not described in 'nand_op_instr'
>   ./include/linux/mtd/rawnand.h:863: warning: Function parameter or member 
> 'ctx.addr' not described in 'nand_op_instr'
>   ./include/linux/mtd/rawnand.h:863: warning: Function parameter or member 
> 'ctx.data' not described in 'nand_op_instr'
>   ./include/linux/mtd/rawnand.h:863: warning: Function parameter or member 
> 'ctx.waitrdy' not described in 'nand_op_instr'
>   ./include/linux/mtd/rawnand.h:1010: warning: Function parameter or member 
> 'ctx' not described in 'nand_op_parser_pattern_elem'
>   ./include/linux/mtd/rawnand.h:1010: warning: Function parameter or member 
> 'ctx.addr' not described in 'nand_op_parser_pattern_elem'
>   ./include/linux/mtd/rawnand.h:1010: warning: Function parameter or member 
> 'ctx.data' not described in 'nand_op_parser_pattern_elem'
>   ./include/linux/mtd/rawnand.h:1313: warning: Function parameter or member 
> 'manufacturer.desc' not described in 'nand_chip'
>   ./include/linux/mtd/rawnand.h:1313: warning: Function parameter or member 
> 'manufacturer.priv' not described in 'nand_chip'
> 
>   ./include/linux/mtd/rawnand.h:848: WARNING: Unexpected indentation.
> 
> Signed-off-by: Mauro Carvalho Chehab 

Applied.

Thanks,

Boris

> ---
>  include/linux/mtd/rawnand.h | 26 ++
>  1 file changed, 18 insertions(+), 8 deletions(-)
> 
> diff --git a/include/linux/mtd/rawnand.h b/include/linux/mtd/rawnand.h
> index 5dad59b31244..b986f94906df 100644
> --- a/include/linux/mtd/rawnand.h
> +++ b/include/linux/mtd/rawnand.h
> @@ -740,8 +740,9 @@ enum nand_data_interface_type {
>  
>  /**
>   * struct nand_data_interface - NAND interface timing
> - * @type:type of the timing
> - * @timings: The timing, type according to @type
> + * @type: type of the timing
> + * @timings:  The timing, type according to @type
> + * @timings.sdr: Use it when @type is %NAND_SDR_IFACE.
>   */
>  struct nand_data_interface {
>   enum nand_data_interface_type type;
> @@ -798,8 +799,9 @@ struct nand_op_addr_instr {
>  /**
>   * struct nand_op_data_instr - Definition of a data instruction
>   * @len: number of data bytes to move
> - * @in: buffer to fill when reading from the NAND chip
> - * @out: buffer to read from when writing to the NAND chip
> + * @buf: buffer to fill
> + * @buf.in: buffer to fill when reading from the NAND chip
> + * @buf.out: buffer to read from when writing to the NAND chip
>   * @force_8bit: force 8-bit access
>   *
>   * Please note that "in" and "out" are inverted from the ONFI specification
> @@ -842,9 +844,13 @@ enum nand_op_instr_type {
>  /**
>   * struct nand_op_instr - Instruction object
>   * @type: the instruction type
> - * @cmd/@addr/@data/@waitrdy: extra data associated to the instruction.
> - *You'll have to use the appropriate element
> - *depending on @type
> + * @ctx:  extra data associated to the instruction. You'll have to use the
> + *appropriate element depending on @type
> + * @ctx.cmd: use it if @type is %NAND_OP_CMD_INSTR
> + * @ctx.addr: use it if @type is %NAND_OP_ADDR_INSTR
> + * @ctx.data: use it if @type is %NAND_OP_DATA_IN_INSTR
> + * or %NAND_OP_DATA_OUT_INSTR
> + * @ctx.waitrdy: use it if @type is %NAND_OP_WAITRDY_INSTR
>   * @delay_ns: delay the controller should apply after the instruction has 
> been
>   * issued on the bus. Most modern controllers have internal timings
>   * control logic, and in this case, the controller driver can ignore
> @@ -997,7 +1003,9 @@ struct nand_op_parser_data_constraints {
>   * struct nand_op_parser_pattern_elem - One element of a pattern
>   * @type: the instructuction type
>   * @optional: whether this element of the pattern is optional or mandatory
> - * @addr/@data: address or data constraint (number of cycles or data length)
> + * @ctx: address or data constraint
> + * @ctx.addr: address constraint (number of cycles)
> + * @ctx.data: data constraint (data length)
>   */
>  struct nand_op_parser_pattern_elem {
>   enum nand_op_instr_type type;
> @@ 

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

[Peter Zijlstra]

On Wed, May 09, 2018 at 08:45:18AM -0600, Jonathan Corbet wrote:
> On Wed, 9 May 2018 10:41:20 +0200
> Peter Zijlstra  wrote:
> 
> > > This is easily done by using "::" instead of just ":".  
> > 
> > And I'll voice my objection once again. This makes a regular comment
> > worse. This rst stuff is utter shit for making normal text files less
> > readable in your favourite text editor.
> > 
> > If this gets merged, I'll simply remove that spurious ':' the next time
> > I'm near that comment.
> 
> Seriously, Peter?

Yep... it makes for pointlessly ugly text. And seeing that the only way
to write code is using text editors, the text editor is the primary
interface to our code.

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

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

Barely, and personally I tend to not bother with kerneldoc much. Most of
the comments I write lack the extra *, and I note that the other fix to
this problem it to drop that spurious * here as well.

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

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

Clearly I don't agree. It reads like crap. I suspect many of the other
options, which I suppose there were, were even worse. Doesn't mean rst
is any good.

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

Why should I care for people not using text editors to write code?

--
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 04/11] docs: dell_rbu.txt: fix location of request_firmware

[Mauro Carvalho Chehab]

Em Wed,  9 May 2018 10:18:47 -0300
Mauro Carvalho Chehab  escreveu:

> commit 5d6d1ddd2730 ("firmware: move firmware loader into its own directory")
> and other commits renamed the old firmware_class.c file and split it
> into separate files, but documentation was not changed accordingly,
> causing Sphinx errors.
> 
> Fixes for other files were already applied but dell_rbu.txt remains
> pointing to the old location.
> 
> Fixes: 5d6d1ddd2730 ("firmware: move firmware loader into its own directory")
> Cc: Kees Cook 
> Cc: Luis R. Rodriguez 
> Cc: Greg Kroah-Hartman 
> Signed-off-by: Mauro Carvalho Chehab 
> ---
>  Documentation/dell_rbu.txt | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/dell_rbu.txt b/Documentation/dell_rbu.txt
> index 0fdb6aa2704c..befeff80e7ec 100644
> --- a/Documentation/dell_rbu.txt
> +++ b/Documentation/dell_rbu.txt
> @@ -121,8 +121,8 @@ read back the image downloaded.
>  
>  .. note::
>  
> -   This driver requires a patch for firmware_class.c which has the modified
> -   request_firmware_nowait function.
> +   This driver requires a patch for drivers/base/firmware_loader/main.c
> +   which has the modified request_firmware_nowait() function.

Please ignore this one. Luis send a patch updating it just removing this
comment, as it is outdated.

Regards,
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 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Jonathan Corbet]

On Wed, 9 May 2018 10:41:20 +0200
Peter Zijlstra  wrote:

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

Seriously, Peter?

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

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

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

Thanks,

jon
--
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 08/11] docs: refcount-vs-atomic.rst: prefix url with https

[Mauro Carvalho Chehab]

Em Wed, 9 May 2018 15:43:19 +0200
Andrea Parri  escreveu:

> Hi Mauro,
> 
> On Wed, May 09, 2018 at 10:18:51AM -0300, Mauro Carvalho Chehab wrote:
> > There's a github URL there, but it is not prefixed by https.
> > Add a prefix, to avoid false-positives with:
> > ./scripts/documentation-file-ref-check
> > 
> > As a side effect, Sphinx should also generate a cross-ref.
> > 
> > Signed-off-by: Mauro Carvalho Chehab   
> 
> There seems to be a "conflicting" patch ("applied" according to Jon):
> 
> 
> http://lkml.kernel.org/r/1525468309-5310-1-git-send-email-andrea.pa...@amarulasolutions.com
> 
> Let me stress here that the github repo. is out-of-date (and we have
> no plans to keep that in sync with mainline).

Good! One less patch pending :-)

Yeah, it seems that Jon pushed it from his repository today. I did a new
git remote update and I'm now seeing this one too.

> 
>   Andrea
> 
> 
> > ---
> >  Documentation/core-api/refcount-vs-atomic.rst | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/Documentation/core-api/refcount-vs-atomic.rst 
> > b/Documentation/core-api/refcount-vs-atomic.rst
> > index 83351c258cdb..185d659e350a 100644
> > --- a/Documentation/core-api/refcount-vs-atomic.rst
> > +++ b/Documentation/core-api/refcount-vs-atomic.rst
> > @@ -17,7 +17,7 @@ in order to help maintainers validate their code against 
> > the change in
> >  these memory ordering guarantees.
> >  
> >  The terms used through this document try to follow the formal LKMM defined 
> > in
> > -github.com/aparri/memory-model/blob/master/Documentation/explanation.txt
> > +https://github.com/aparri/memory-model/blob/master/Documentation/explanation.txt
> >  
> >  memory-barriers.txt and atomic_t.txt provide more background to the
> >  memory ordering in general and for atomic operations specifically.
> > -- 
> > 2.17.0
> >   



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 08/11] docs: refcount-vs-atomic.rst: prefix url with https

[Andrea Parri]

Hi Mauro,

On Wed, May 09, 2018 at 10:18:51AM -0300, Mauro Carvalho Chehab wrote:
> There's a github URL there, but it is not prefixed by https.
> Add a prefix, to avoid false-positives with:
>   ./scripts/documentation-file-ref-check
> 
> As a side effect, Sphinx should also generate a cross-ref.
> 
> Signed-off-by: Mauro Carvalho Chehab 

There seems to be a "conflicting" patch ("applied" according to Jon):


http://lkml.kernel.org/r/1525468309-5310-1-git-send-email-andrea.pa...@amarulasolutions.com

Let me stress here that the github repo. is out-of-date (and we have
no plans to keep that in sync with mainline).

  Andrea


> ---
>  Documentation/core-api/refcount-vs-atomic.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/core-api/refcount-vs-atomic.rst 
> b/Documentation/core-api/refcount-vs-atomic.rst
> index 83351c258cdb..185d659e350a 100644
> --- a/Documentation/core-api/refcount-vs-atomic.rst
> +++ b/Documentation/core-api/refcount-vs-atomic.rst
> @@ -17,7 +17,7 @@ in order to help maintainers validate their code against 
> the change in
>  these memory ordering guarantees.
>  
>  The terms used through this document try to follow the formal LKMM defined in
> -github.com/aparri/memory-model/blob/master/Documentation/explanation.txt
> +https://github.com/aparri/memory-model/blob/master/Documentation/explanation.txt
>  
>  memory-barriers.txt and atomic_t.txt provide more background to the
>  memory ordering in general and for atomic operations specifically.
> -- 
> 2.17.0
> 
--
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 16/18] mtd: rawnand.h: use nested union kernel-doc markups

[Mauro Carvalho Chehab]

Em Wed, 9 May 2018 14:22:21 +0200
Boris Brezillon  escreveu:

> On Wed, 9 May 2018 09:10:34 -0300
> Mauro Carvalho Chehab  wrote:
> 
> > Hi Boris,
> > 
> > Em Mon, 7 May 2018 08:32:32 -0300
> > Mauro Carvalho Chehab  escreveu:
> >   
> > > Hi Boris,
> > > 
> > > Em Mon, 7 May 2018 11:46:50 +0200
> > > Boris Brezillon  escreveu:
> >   
> > > > Is there a simple
> > > > way we can get rid of the warning we have when not describing timings
> > > > but all of its fields?  
> > > 
> > > There's no direct way. It won't be hard to add a way to do it,
> > > like applying the enclosed patch with ends by declaring timings as:
> > > 
> > >   * @timings:  -- undescribed --
> > > 
> > > IMHO, this is uglier.
> > 
> > Didn't hear from you.  
> 
> I replied just a few minutes ago ;).

OK!

> > What do you prefer for me to do with regards to
> > this patch?   
> 
> Will queue the initial patch to nand/next (I can also queue it to the
> fixes branch if you prefer).

No need. it can follow the usual workflow.

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

[PATCH v2 01/11] docs: can.rst: fix a footnote reference

[Mauro Carvalho Chehab]

As stated at:

http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#footnotes

A footnote should contain either a number, a reference or
an auto number, e. g.:
[1], [#f1] or [#].

While using [*] accidentaly works for html, it fails for other
document outputs. In particular, it causes an error with LaTeX
output, causing all books after networking to not be built.

So, replace it by a valid syntax.

Acked-by: Oliver Hartkopp 
Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/networking/can.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/networking/can.rst b/Documentation/networking/can.rst
index d23c51abf8c6..2fd0b51a8c52 100644
--- a/Documentation/networking/can.rst
+++ b/Documentation/networking/can.rst
@@ -164,7 +164,7 @@ The Linux network devices (by default) just can handle the
 transmission and reception of media dependent frames. Due to the
 arbitration on the CAN bus the transmission of a low prio CAN-ID
 may be delayed by the reception of a high prio CAN frame. To
-reflect the correct [*]_ traffic on the node the loopback of the sent
+reflect the correct [#f1]_ traffic on the node the loopback of the sent
 data has to be performed right after a successful transmission. If
 the CAN network interface is not capable of performing the loopback for
 some reason the SocketCAN core can do this task as a fallback solution.
@@ -175,7 +175,7 @@ networking behaviour for CAN applications. Due to some 
requests from
 the RT-SocketCAN group the loopback optionally may be disabled for each
 separate socket. See sockopts from the CAN RAW sockets in 
:ref:`socketcan-raw-sockets`.
 
-.. [*] you really like to have this when you're running analyser
+.. [#f1] you really like to have this when you're running analyser
tools like 'candump' or 'cansniffer' on the (same) node.
 
 
-- 
2.17.0

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

[PATCH v2 08/11] docs: refcount-vs-atomic.rst: prefix url with https

[Mauro Carvalho Chehab]

There's a github URL there, but it is not prefixed by https.
Add a prefix, to avoid false-positives with:
./scripts/documentation-file-ref-check

As a side effect, Sphinx should also generate a cross-ref.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/core-api/refcount-vs-atomic.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/core-api/refcount-vs-atomic.rst 
b/Documentation/core-api/refcount-vs-atomic.rst
index 83351c258cdb..185d659e350a 100644
--- a/Documentation/core-api/refcount-vs-atomic.rst
+++ b/Documentation/core-api/refcount-vs-atomic.rst
@@ -17,7 +17,7 @@ in order to help maintainers validate their code against the 
change in
 these memory ordering guarantees.
 
 The terms used through this document try to follow the formal LKMM defined in
-github.com/aparri/memory-model/blob/master/Documentation/explanation.txt
+https://github.com/aparri/memory-model/blob/master/Documentation/explanation.txt
 
 memory-barriers.txt and atomic_t.txt provide more background to the
 memory ordering in general and for atomic operations specifically.
-- 
2.17.0

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

[PATCH v2 03/11] docs: crypto_engine.rst: Fix two parse warnings

[Mauro Carvalho Chehab]

./Documentation/crypto/crypto_engine.rst:13: WARNING: Unexpected indentation.
./Documentation/crypto/crypto_engine.rst:15: WARNING: Block quote ends without 
a blank line; unexpected unindent.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/crypto/crypto_engine.rst | 8 +---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/Documentation/crypto/crypto_engine.rst 
b/Documentation/crypto/crypto_engine.rst
index 8272ac92a14f..1d56221dfe35 100644
--- a/Documentation/crypto/crypto_engine.rst
+++ b/Documentation/crypto/crypto_engine.rst
@@ -8,11 +8,13 @@ The crypto engine API (CE), is a crypto queue manager.
 
 Requirement
 ---
-You have to put at start of your tfm_ctx the struct crypto_engine_ctx
-struct your_tfm_ctx {
+You have to put at start of your tfm_ctx the struct crypto_engine_ctx::
+
+  struct your_tfm_ctx {
 struct crypto_engine_ctx enginectx;
 ...
-};
+  };
+
 Why: Since CE manage only crypto_async_request, it cannot know the underlying
 request_type and so have access only on the TFM.
 So using container_of for accessing __ctx is impossible.
-- 
2.17.0

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

[PATCH v2 07/11] docs: ranoops.rst: fix location of ramoops.txt

[Mauro Carvalho Chehab]

The location of the dt bindings file is wrong: it was probably
badly renamed by some script.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/admin-guide/ramoops.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/admin-guide/ramoops.rst 
b/Documentation/admin-guide/ramoops.rst
index 4efd7ce77565..6dbcc5481000 100644
--- a/Documentation/admin-guide/ramoops.rst
+++ b/Documentation/admin-guide/ramoops.rst
@@ -61,7 +61,7 @@ Setting the ramoops parameters can be done in several 
different manners:
mem=128M ramoops.mem_address=0x800 ramoops.ecc=1
 
  B. Use Device Tree bindings, as described in
- 
``Documentation/device-tree/bindings/reserved-memory/admin-guide/ramoops.rst``.
+ ``Documentation/devicetree/bindings/reserved-memory/ramoops.txt``.
  For example::
 
reserved-memory {
-- 
2.17.0

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

[PATCH v2 04/11] docs: dell_rbu.txt: fix location of request_firmware

[Mauro Carvalho Chehab]

commit 5d6d1ddd2730 ("firmware: move firmware loader into its own directory")
and other commits renamed the old firmware_class.c file and split it
into separate files, but documentation was not changed accordingly,
causing Sphinx errors.

Fixes for other files were already applied but dell_rbu.txt remains
pointing to the old location.

Fixes: 5d6d1ddd2730 ("firmware: move firmware loader into its own directory")
Cc: Kees Cook 
Cc: Luis R. Rodriguez 
Cc: Greg Kroah-Hartman 
Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/dell_rbu.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/dell_rbu.txt b/Documentation/dell_rbu.txt
index 0fdb6aa2704c..befeff80e7ec 100644
--- a/Documentation/dell_rbu.txt
+++ b/Documentation/dell_rbu.txt
@@ -121,8 +121,8 @@ read back the image downloaded.
 
 .. note::
 
-   This driver requires a patch for firmware_class.c which has the modified
-   request_firmware_nowait function.
+   This driver requires a patch for drivers/base/firmware_loader/main.c
+   which has the modified request_firmware_nowait() function.
 
Also after updating the BIOS image a user mode application needs to execute
code which sends the BIOS update request to the BIOS. So on the next reboot
-- 
2.17.0

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

[PATCH v2 05/11] docs: uio-howto.rst: use a code block to solve a warning

[Mauro Carvalho Chehab]

/devel/v4l/docs/Documentation/driver-api/uio-howto.rst:715: WARNING: Unexpected 
indentation.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/uio-howto.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/driver-api/uio-howto.rst 
b/Documentation/driver-api/uio-howto.rst
index 92056c20e070..fb2eb73be4a3 100644
--- a/Documentation/driver-api/uio-howto.rst
+++ b/Documentation/driver-api/uio-howto.rst
@@ -711,7 +711,8 @@ The vmbus device regions are mapped into uio device 
resources:
 
 If a subchannel is created by a request to host, then the uio_hv_generic
 device driver will create a sysfs binary file for the per-channel ring buffer.
-For example:
+For example::
+

/sys/bus/vmbus/devices/3811fe4d-0fa0-4b62-981a-74fc1084c757/channels/21/ring
 
 Further information
-- 
2.17.0

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

[PATCH v2 06/11] scripts/documentation-file-ref-check: rewrite it in perl with auto-fix mode

[Mauro Carvalho Chehab]

The original shell script works, but:
1) it is too slow;
2) it is hard to exclude rejex patterns

Convert it to perl.

Here, the new version is able to check the entire tree in
less than a second (after cached):

real0m0,284s
user0m0,668s
sys 0m0,778s

The old version takes more than a minute to complete (also
after cached):
real1m17,905s
user0m25,583s
sys 0m55,334s

It also produce less false-positives (if any).

The new script also contains an auto-fix mode.

Usually, file references get lost when they're moved to some other
place and/or renamed to .rst.

Add an experimental mode to auto-fix those.

Signed-off-by: Mauro Carvalho Chehab 
---
 scripts/documentation-file-ref-check | 125 ---
 1 file changed, 113 insertions(+), 12 deletions(-)

diff --git a/scripts/documentation-file-ref-check 
b/scripts/documentation-file-ref-check
index bc1659900e89..2520bc14ffac 100755
--- a/scripts/documentation-file-ref-check
+++ b/scripts/documentation-file-ref-check
@@ -1,15 +1,116 @@
-#!/bin/sh
+#!/usr/bin/env perl
+# SPDX-License-Identifier: GPL-2.0
+#
 # Treewide grep for references to files under Documentation, and report
 # non-existing files in stderr.
 
-for f in $(git ls-files); do
-   for ref in $(grep -ho "Documentation/[A-Za-z0-9_.,~/*+-]*" "$f"); do
-   # presume trailing . and , are not part of the name
-   ref=${ref%%[.,]}
-
-   # use ls to handle wildcards
-   if ! ls $ref >/dev/null 2>&1; then
-   echo "$f: $ref" >&2
-   fi
-   done
-done
+use warnings;
+use strict;
+use Getopt::Long qw(:config no_auto_abbrev);
+
+my $scriptname = $0;
+$scriptname =~ s,.*/([^/]+/),$1,;
+
+# Parse arguments
+my $help = 0;
+my $fix = 0;
+
+GetOptions(
+   'fix' => \$fix,
+   'h|help|usage' => \$help,
+);
+
+if ($help != 0) {
+print "$scriptname [--help] [--fix-rst]\n";
+exit -1;
+}
+
+# Step 1: find broken references
+print "Finding broken references. This may take a while...  " if ($fix);
+
+my %broken_ref;
+
+open IN, "git grep 'Documentation/'|"
+ or die "Failed to run git grep";
+while () {
+   next if (!m/^([^:]+):(.*)/);
+
+   my $f = $1;
+   my $ln = $2;
+
+   # Makefiles contain nasty expressions to parse docs
+   next if ($f =~ m/Makefile/);
+   # Skip this script
+   next if ($f eq $scriptname);
+
+   if ($ln =~ m,\b(\S*)(Documentation/[A-Za-z0-9\_\.\,\~/\*+-]*),) {
+   my $prefix = $1;
+   my $ref = $2;
+   my $base = $2;
+
+   $ref =~ s/[\,\.]+$//;
+
+   my $fulref = "$prefix$ref";
+
+   $fulref =~ s/^(\ 1) {
+   print STDERR "WARNING: Won't auto-replace, as found multiple 
files close to $ref:\n";
+   foreach my $j (@find) {
+   $j =~ s,^./,,;
+   print STDERR "$j\n";
+   }
+   } else {
+   $f = $find[0];
+   $f =~ s,^./,,;
+   print "INFO: Replacing $ref to $f\n";
+   foreach my $j (qx(git grep -l $ref)) {
+   qx(sed "s\@$ref\@$f\@g" -i $j);
+   }
+   }
+}
-- 
2.17.0

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

[PATCH v2 11/11] docs: fix broken references with multiple hints

[Mauro Carvalho Chehab]

The script:
./scripts/documentation-file-ref-check --fix-rst

Gives multiple hints for broken references on some files.
Manually use the one that applies for some files.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/ABI/obsolete/sysfs-gpio | 2 +-
 .../devicetree/bindings/display/bridge/tda998x.txt| 2 +-
 Documentation/trace/events.rst| 2 +-
 Documentation/trace/tracepoint-analysis.rst   | 2 +-
 Documentation/translations/zh_CN/SubmittingDrivers| 2 +-
 Documentation/translations/zh_CN/gpio.txt | 4 ++--
 MAINTAINERS   | 2 +-
 drivers/hid/usbhid/Kconfig| 2 +-
 drivers/input/Kconfig | 4 ++--
 drivers/input/joystick/Kconfig| 4 ++--
 drivers/input/joystick/iforce/Kconfig | 2 +-
 drivers/input/serio/Kconfig   | 4 ++--
 drivers/staging/fsl-mc/bus/dpio/dpio-driver.txt   | 2 +-
 drivers/video/fbdev/skeletonfb.c  | 8 
 include/linux/tracepoint.h| 2 +-
 security/device_cgroup.c  | 2 +-
 16 files changed, 23 insertions(+), 23 deletions(-)

diff --git a/Documentation/ABI/obsolete/sysfs-gpio 
b/Documentation/ABI/obsolete/sysfs-gpio
index 32513dc2eec9..40d41ea1a3f5 100644
--- a/Documentation/ABI/obsolete/sysfs-gpio
+++ b/Documentation/ABI/obsolete/sysfs-gpio
@@ -11,7 +11,7 @@ Description:
   Kernel code may export it for complete or partial access.
 
   GPIOs are identified as they are inside the kernel, using integers in
-  the range 0..INT_MAX.  See Documentation/gpio/gpio.txt for more information.
+  the range 0..INT_MAX.  See Documentation/gpio for more information.
 
 /sys/class/gpio
/export ... asks the kernel to export a GPIO to userspace
diff --git a/Documentation/devicetree/bindings/display/bridge/tda998x.txt 
b/Documentation/devicetree/bindings/display/bridge/tda998x.txt
index 24cc2466185a..3484af33c879 100644
--- a/Documentation/devicetree/bindings/display/bridge/tda998x.txt
+++ b/Documentation/devicetree/bindings/display/bridge/tda998x.txt
@@ -27,7 +27,7 @@ Optional properties:
in question is used. The implementation allows one or two DAIs. If two
DAIs are defined, they must be of different type.
 
-[1] Documentation/sound/alsa/soc/DAI.txt
+[1] Documentation/sound/soc/dai.rst
 [2] include/dt-bindings/display/tda998x.h
 
 Example:
diff --git a/Documentation/trace/events.rst b/Documentation/trace/events.rst
index 7b6b1236ec2e..c292117b83a9 100644
--- a/Documentation/trace/events.rst
+++ b/Documentation/trace/events.rst
@@ -8,7 +8,7 @@ Event Tracing
 1. Introduction
 ===
 
-Tracepoints (see Documentation/trace/tracepoints.txt) can be used
+Tracepoints (see Documentation/trace/tracepoints.rst) can be used
 without creating custom kernel modules to register probe functions
 using the event tracing infrastructure.
 
diff --git a/Documentation/trace/tracepoint-analysis.rst 
b/Documentation/trace/tracepoint-analysis.rst
index b0c9c21f129d..716326b9f152 100644
--- a/Documentation/trace/tracepoint-analysis.rst
+++ b/Documentation/trace/tracepoint-analysis.rst
@@ -6,7 +6,7 @@ Notes on Analysing Behaviour Using Events and Tracepoints
 1. Introduction
 ===
 
-Tracepoints (see Documentation/trace/tracepoints.txt) can be used without
+Tracepoints (see Documentation/trace/tracepoints.rst) can be used without
 creating custom kernel modules to register probe functions using the event
 tracing infrastructure.
 
diff --git a/Documentation/translations/zh_CN/SubmittingDrivers 
b/Documentation/translations/zh_CN/SubmittingDrivers
index 929385e4b194..15e73562f710 100644
--- a/Documentation/translations/zh_CN/SubmittingDrivers
+++ b/Documentation/translations/zh_CN/SubmittingDrivers
@@ -107,7 +107,7 @@ Linux 2.6:
程序测试的指导，请参阅
Documentation/power/drivers-testing.txt。有关驱动程序电
源管理问题相对全面的概述，请参阅
-   Documentation/power/admin-guide/devices.rst。
+   Documentation/driver-api/pm/devices.rst。
 
 管理：如果一个驱动程序的作者还在进行有效的维护，那么通常除了那
些明显正确且不需要任何检查的补丁以外，其他所有的补丁都会
diff --git a/Documentation/translations/zh_CN/gpio.txt 
b/Documentation/translations/zh_CN/gpio.txt
index 4f8bf30a41dc..4cb1ba8b8fed 100644
--- a/Documentation/translations/zh_CN/gpio.txt
+++ b/Documentation/translations/zh_CN/gpio.txt
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/gpio.txt
+Chinese translated version of Documentation/gpio
 
 If you have any comment or update to the content, please contact the
 original document maintainer directly.  However, if you have a problem
@@ -10,7 +10,7 @@ Maintainer: Grant Likely 
Linus Walleij 

[PATCH v2 10/11] arch/*: Kconfig: fix documentation for NMI watchdog

[Mauro Carvalho Chehab]

Changeset 9919cba7ff71 ("watchdog: Update documentation") updated
the documentation, removing the old nmi_watchdog.txt and adding
a file with a new content.

Update Kconfig files accordingly.

Fixes: 9919cba7ff71 ("watchdog: Update documentation")

Signed-off-by: Mauro Carvalho Chehab 
---
 arch/arm/Kconfig| 2 +-
 arch/parisc/Kconfig | 2 +-
 arch/sh/Kconfig | 2 +-
 arch/sparc/Kconfig  | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/arch/arm/Kconfig b/arch/arm/Kconfig
index a7f8e7f4b88f..7b4fa8356978 100644
--- a/arch/arm/Kconfig
+++ b/arch/arm/Kconfig
@@ -1305,7 +1305,7 @@ config SMP
  will run faster if you say N here.
 
  See also ,
-  and the SMP-HOWTO available at
+  and the SMP-HOWTO available 
at
  .
 
  If you don't know what to do here, say N.
diff --git a/arch/parisc/Kconfig b/arch/parisc/Kconfig
index fc5a574c3482..b6823215cc9a 100644
--- a/arch/parisc/Kconfig
+++ b/arch/parisc/Kconfig
@@ -279,7 +279,7 @@ config SMP
  machines, but will use only one CPU of a multiprocessor machine.
  On a uniprocessor machine, the kernel will run faster if you say N.
 
- See also  and the SMP-HOWTO
+ See also  and the SMP-HOWTO
  available at .
 
  If you don't know what to do here, say N.
diff --git a/arch/sh/Kconfig b/arch/sh/Kconfig
index 97fe29316476..bf628dd7c195 100644
--- a/arch/sh/Kconfig
+++ b/arch/sh/Kconfig
@@ -689,7 +689,7 @@ config SMP
  People using multiprocessor machines who say Y here should also say
  Y to "Enhanced Real Time Clock Support", below.
 
- See also  and the SMP-HOWTO
+ See also  and the SMP-HOWTO
  available at .
 
  If you don't know what to do here, say N.
diff --git a/arch/sparc/Kconfig b/arch/sparc/Kconfig
index 8767e45f1b2b..66171c2e428b 100644
--- a/arch/sparc/Kconfig
+++ b/arch/sparc/Kconfig
@@ -189,7 +189,7 @@ config SMP
  Y to "Enhanced Real Time Clock Support", below. The "Advanced Power
  Management" code will be disabled if you say Y here.
 
- See also  and the SMP-HOWTO
+ See also  and the SMP-HOWTO
  available at .
 
  If you don't know what to do here, say N.
-- 
2.17.0

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

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

[Mauro Carvalho Chehab]

The cgroup-v2.txt is already in ReST format. So, move it to the
admin-guide, where it belongs.

Cc: Tejun Heo 
Cc: Li Zefan 
Cc: Johannes Weiner 
Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/00-INDEX | 2 --
 Documentation/{cgroup-v2.txt => admin-guide/cgroup-v2.rst} | 0
 Documentation/admin-guide/index.rst| 1 +
 3 files changed, 1 insertion(+), 2 deletions(-)
 rename Documentation/{cgroup-v2.txt => admin-guide/cgroup-v2.rst} (100%)

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index a50d2380b6fb..2754fe83f0d4 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -80,8 +80,6 @@ cdrom/
- directory with information on the CD-ROM drivers that Linux has.
 cgroup-v1/
- cgroups v1 features, including cpusets and memory controller.
-cgroup-v2.txt
-   - cgroups v2 features, including cpusets and memory controller.
 cma/
- Continuous Memory Area (CMA) debugfs interface.
 conf.py
diff --git a/Documentation/cgroup-v2.txt 
b/Documentation/admin-guide/cgroup-v2.rst
similarity index 100%
rename from Documentation/cgroup-v2.txt
rename to Documentation/admin-guide/cgroup-v2.rst
diff --git a/Documentation/admin-guide/index.rst 
b/Documentation/admin-guide/index.rst
index 52eb3408f9a0..48d70af11652 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -48,6 +48,7 @@ configure specific aspects of kernel behavior to your liking.
:maxdepth: 1
 
initrd
+   cgroup-v2
serial-console
braille-console
parport
-- 
2.17.0

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

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

[Mauro Carvalho Chehab]

Hi Jon,

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

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

Before doing that, I made a shell script version, but there are
several false positives there that would require some regex
parsing to get rid. Also, performance was problematic: even
on an i7core with SSD M.2 disk, it was taking more than a minute
just to identify the errors. The perl version makes it in less
than a second and gives more reliable results.

It should be noticed that, as any other auto-fix tool, the
resuls of the fix should be validated.

The next 5 patches contain several fixes based on its results.

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

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

Patch 10 fixes the removal of nmi_watchdog.txt.

Patch 11 do some manual fixes on most of the places where
the automatic fix tool found multiple hints.

Ah, I noticed also several broken links on media. Those
were fixed on 3 separate patches, submitted to linux-media.
I intend to apply them via my own tree.

Regards,
Mauro


Mauro Carvalho Chehab (11):
  docs: can.rst: fix a footnote reference
  docs: admin-guide: add cgroup-v2 documentation
  docs: crypto_engine.rst: Fix two parse warnings
  docs: dell_rbu.txt: fix location of request_firmware
  docs: uio-howto.rst: use a code block to solve a warning
  scripts/documentation-file-ref-check: rewrite it in perl with auto-fix
mode
  docs: ranoops.rst: fix location of ramoops.txt
  docs: refcount-vs-atomic.rst: prefix url with https
  docs: Fix some broken references
  arch/*: Kconfig: fix documentation for NMI watchdog
  docs: fix broken references with multiple hints

 Documentation/00-INDEX|   2 -
 Documentation/ABI/obsolete/sysfs-gpio |   2 +-
 .../cgroup-v2.rst}|   0
 Documentation/admin-guide/index.rst   |   1 +
 .../admin-guide/kernel-parameters.txt |   4 +-
 Documentation/admin-guide/ramoops.rst |   2 +-
 Documentation/core-api/refcount-vs-atomic.rst |   2 +-
 Documentation/crypto/crypto_engine.rst|   8 +-
 Documentation/dell_rbu.txt|   4 +-
 .../bindings/display/bridge/tda998x.txt   |   2 +-
 .../bindings/input/rotary-encoder.txt |   2 +-
 Documentation/driver-api/gpio/consumer.rst|   2 +-
 Documentation/driver-api/uio-howto.rst|   3 +-
 Documentation/kprobes.txt |   4 +-
 Documentation/networking/can.rst  |   4 +-
 Documentation/trace/coresight.txt |   2 +-
 Documentation/trace/events.rst|   4 +-
 Documentation/trace/ftrace-uses.rst   |   2 +-
 Documentation/trace/histogram.txt |   2 +-
 Documentation/trace/intel_th.rst  |   2 +-
 Documentation/trace/tracepoint-analysis.rst   |   8 +-
 Documentation/translations/ja_JP/howto.rst|   4 +-
 .../translations/zh_CN/SubmittingDrivers  |   2 +-
 Documentation/translations/zh_CN/gpio.txt |   4 +-
 .../translations/zh_CN/magic-number.txt   |   4 +-
 .../zh_CN/video4linux/omap3isp.txt|   4 +-
 MAINTAINERS   |  22 +--
 arch/Kconfig  |   2 +-
 arch/arm/Kconfig  |   2 +-
 arch/arm/include/asm/cacheflush.h |   2 +-
 arch/arm64/include/asm/cacheflush.h   |   2 +-
 arch/microblaze/include/asm/cacheflush.h  |   2 +-
 arch/parisc/Kconfig   |   2 +-
 arch/sh/Kconfig   |   2 +-
 arch/sparc/Kconfig|   2 +-
 arch/um/Kconfig.um|   2 +-
 arch/unicore32/include/asm/cacheflush.h   |   2 +-
 arch/x86/entry/vsyscall/vsyscall_64.c |   2 +-
 arch/xtensa/include/asm/cacheflush.h  |   4 +-
 block/Kconfig |   2 +-
 certs/Kconfig |   2 +-
 crypto/asymmetric_keys/asymmetric_type.c  |   2 +-
 crypto/asymmetric_keys/signature.c|   2 +-
 drivers/char/Kconfig  |   2 +-
 drivers/clk/clk.c |   4 +-
 drivers/clk/ingenic/cgu.h |   2 +-
 drivers/gpu/vga/Kconfig   |   2 +-
 drivers/gpu/vga/vgaarb.c  |   2 +-
 drivers/hid/usbhid/Kconfig|   2 +-
 drivers/input/Kconfig |   4 +-
 drivers/input/joystick/Kconfig 

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

[Jonathan Corbet]

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

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

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

Thanks,

jon
--
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] MAINTAINERS & files: Canonize the e-mails I use at files

[Jan Kara]

On Fri 04-05-18 08:33:55, Mauro Carvalho Chehab wrote:
> Em Fri, 04 May 2018 13:58:39 +0300
> Jani Nikula  escreveu:
> 
> > On Fri, 04 May 2018, Mauro Carvalho Chehab  
> > wrote:
> > > From now on, I'll start using my @kernel.org as my development e-mail.
> > >
> > > As such, let's remove the entries that point to the old
> > > mche...@s-opensource.com at MAINTAINERS file.
> > >
> > > For the files written with a copyright with mchehab@s-opensource,
> > > let's keep Samsung on their names, using mchehab+sams...@kernel.org,
> > > in order to keep pointing to my employer, with sponsors the work.
> > >
> > > For the files written before I join Samsung (on July, 4 2013),
> > > let's just use mche...@kernel.org.
> > >
> > > For bug reports, we can simply point to just kernel.org, as
> > > this will reach my mchehab+samsung inbox anyway.  
> > 
> > I suppose this begs the question, why do we insist on adding our email
> > addresses all over the place? On a quick grep, there are at least 40k+
> > email addresses in the sources. Do we expect them all to be up-to-date
> > too?
> 
> That's a good question.
> 
> The usual use case is that the e-mail allows people to contact developers
> if needed. Such contact could simply due to something like handling SPDX
> or other license-related issues or for troubleshooting.
> 
> There's also another reason (with IMHO, is more relevant): just the name
> may not be enough to uniquely identify the author of some code. While
> that might happen on occidental Countries, this is a way more relevant
> for Asian Countries. For example, there are very few surnames on
> some Countries there[1], and common names are usually... common. So, it
> is not hard to find several people with exactly the same name working at
> the same company. I've seen e-mails from those people that are things like
> john.doe51@some.company, john.doe69@some.company, ...
> 
> [1] For example: https://en.wikipedia.org/wiki/List_of_Korean_surnames.
> 
> The e-mail is a way to uniquely identify a person. If we remove it,
> then we may need to add another thing instead (like parents names,
> security number or whatever), with would be weird, IMO. 
> 
> As we all use e-mails to uniquely identify contributors submissions,
> IMHO, the best is to keep using e-mails. The side effect is that
> we should keep those emails updated.

Understood but e-mails in code get stale eventually as people rarely update
those. So I think having a contact email in MAINTAINERS and git logs is
enough for practical purposes.

Honza
-- 
Jan Kara 
SUSE Labs, CR
--
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 3/3] media: v4l: fix broken video4linux docs locations

[Mauro Carvalho Chehab]

There are several places pointing to old documentation files:

  Documentation/video4linux/API.html
  Documentation/video4linux/bttv/
  Documentation/video4linux/cx2341x/fw-encoder-api.txt
  Documentation/video4linux/m5602.txt
  Documentation/video4linux/v4l2-framework.txt
  Documentation/video4linux/videobuf
  Documentation/video4linux/Zoran

Make them point to the new location where available, removing
otherwise.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../translations/zh_CN/video4linux/v4l2-framework.txt  |  6 +++---
 drivers/media/pci/bt8xx/Kconfig|  2 +-
 drivers/media/pci/cx18/cx18-streams.c  |  4 ++--
 drivers/media/pci/zoran/Kconfig|  2 +-
 drivers/media/radio/Kconfig| 10 +-
 drivers/media/radio/wl128x/Kconfig |  2 +-
 drivers/media/usb/gspca/m5602/Kconfig  |  2 --
 7 files changed, 13 insertions(+), 15 deletions(-)

diff --git a/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt 
b/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt
index 698660b7f21f..054716a7ae77 100644
--- a/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt
+++ b/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/video4linux/v4l2-framework.txt
+Chinese translated version of Documentation/media/media_kapi.rst
 
 If you have any comment or update to the content, please contact the
 original document maintainer directly.  However, if you have a problem
@@ -9,7 +9,7 @@ or if there is a problem with the translation.
 Maintainer: Mauro Carvalho Chehab 
 Chinese maintainer: Fu Wei 
 -
-Documentation/video4linux/v4l2-framework.txt 的中文翻译
+Documentation/media/media_kapi.rst 的中文翻译
 
 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
@@ -777,7 +777,7 @@ v4l2 核心 API 提供了一个处理视频缓冲的标准方法(称为“videob
 线性 DMA(videobuf-dma-contig)以及大多用于 USB 设备的用 vmalloc
 分配的缓冲(videobuf-vmalloc)。
 
-请参阅 Documentation/video4linux/videobuf，以获得更多关于 videobuf
+请参阅 Documentation/media/kapi/v4l2-videobuf.rst，以获得更多关于 videobuf
 层的使用信息。
 
 v4l2_fh 结构体
diff --git a/drivers/media/pci/bt8xx/Kconfig b/drivers/media/pci/bt8xx/Kconfig
index 4a93f6ded100..bc89e37608cd 100644
--- a/drivers/media/pci/bt8xx/Kconfig
+++ b/drivers/media/pci/bt8xx/Kconfig
@@ -16,7 +16,7 @@ config VIDEO_BT848
---help---
  Support for BT848 based frame grabber/overlay boards. This includes
  the Miro, Hauppauge and STB boards. Please read the material in
-  for more information.
+  for more information.
 
  To compile this driver as a module, choose M here: the
  module will be called bttv.
diff --git a/drivers/media/pci/cx18/cx18-streams.c 
b/drivers/media/pci/cx18/cx18-streams.c
index a594cfdeca20..b36f4ce25d22 100644
--- a/drivers/media/pci/cx18/cx18-streams.c
+++ b/drivers/media/pci/cx18/cx18-streams.c
@@ -853,7 +853,7 @@ int cx18_start_v4l2_encode_stream(struct cx18_stream *s)
 
/*
 * Audio related reset according to
-* Documentation/video4linux/cx2341x/fw-encoder-api.txt
+* Documentation/media/v4l-drivers/cx2341x.rst
 */
if (atomic_read(>ana_capturing) == 0)
cx18_vapi(cx, CX18_CPU_SET_MISC_PARAMETERS, 2,
@@ -861,7 +861,7 @@ int cx18_start_v4l2_encode_stream(struct cx18_stream *s)
 
/*
 * Number of lines for Field 1 & Field 2 according to
-* Documentation/video4linux/cx2341x/fw-encoder-api.txt
+* Documentation/media/v4l-drivers/cx2341x.rst
 * Field 1 is 312 for 625 line systems in BT.656
 * Field 2 is 313 for 625 line systems in BT.656
 */
diff --git a/drivers/media/pci/zoran/Kconfig b/drivers/media/pci/zoran/Kconfig
index 39ec35bd21a5..66c4c238ac0f 100644
--- a/drivers/media/pci/zoran/Kconfig
+++ b/drivers/media/pci/zoran/Kconfig
@@ -7,7 +7,7 @@ config VIDEO_ZORAN
  36057/36067 PCI controller chipset. This includes the Iomega
  Buz, Pinnacle DC10+ and the Linux Media Labs LML33. There is
  a driver homepage at . For
- more information, check .
+ more information, check 
.
 
  To compile this driver as a module, choose M here: the
  module will be called zr36067.
diff --git a/drivers/media/radio/Kconfig b/drivers/media/radio/Kconfig
index 8fa403c7149e..04ddd5057098 100644
--- a/drivers/media/radio/Kconfig
+++ b/drivers/media/radio/Kconfig
@@ -35,7 +35,7 @@ config RADIO_SI476X
  In order to control your radio card, you will need to use programs
  that are compatible with the Video For Linux 2 API.  

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

[Mauro Carvalho Chehab]

Em Tue, 08 May 2018 14:03:39 +0300
Evgeniy Polyakov  escreveu:

> Hi
> 
> 07.05.2018, 12:36, "Mauro Carvalho Chehab" :
> > Add a blank line to avoid this Sphinx warning:
> > ./drivers/w1/w1_io.c:197: WARNING: Definition list ends without a 
> > blank line; unexpected unindent.
> >
> > Signed-off-by: Mauro Carvalho Chehab   
> 
> Looks good to me, thank you!
> What tree should this be forwarded to, or folks from linux doc will pick it 
> up?
> 
> Acked-by: Evgeniy Polyakov 

Jon prefers if this could go via the usual maintainer's tree.

So, could you send it via yours?

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 02/18] docs: fix location of request_firmware & friends

[Mauro Carvalho Chehab]

Em Tue, 8 May 2018 15:49:08 +
"Luis R. Rodriguez"  escreveu:

> On Mon, May 07, 2018 at 06:35:38AM -0300, Mauro Carvalho Chehab wrote:
> > commit 5d6d1ddd2730 ("firmware: move firmware loader into its own 
> > directory")
> > and other commits renamed the old firmware_class.c file and split it
> > into separate files, but documentation was not changed accordingly,
> > causing Sphinx errors.
> > 
> > Change the location accordingly at the documentation files.
> > 
> > While here, add a missing entry at request_firmware.rst for
> > release_firmware() function.
> > 
> > Fixes: 5d6d1ddd2730 ("firmware: move firmware loader into its own 
> > directory")
> > Cc: Kees Cook 
> > Cc: Luis R. Rodriguez 
> > Cc: Greg Kroah-Hartman 
> > Signed-off-by: Mauro Carvalho Chehab 
> > ---
> >  Documentation/dell_rbu.txt  |  4 ++--
> >  .../driver-api/firmware/fallback-mechanisms.rst |  2 +-
> >  .../driver-api/firmware/request_firmware.rst| 17 +++--
> >  Documentation/driver-api/infrastructure.rst |  2 +-
> >  Documentation/power/suspend-and-cpuhotplug.txt  |  2 +-
> >  5 files changed, 16 insertions(+), 11 deletions(-)
> > 
> > diff --git a/Documentation/dell_rbu.txt b/Documentation/dell_rbu.txt
> > index 0fdb6aa2704c..befeff80e7ec 100644
> > --- a/Documentation/dell_rbu.txt
> > +++ b/Documentation/dell_rbu.txt
> > @@ -121,8 +121,8 @@ read back the image downloaded.
> >  
> >  .. note::
> >  
> > -   This driver requires a patch for firmware_class.c which has the modified
> > -   request_firmware_nowait function.
> > +   This driver requires a patch for drivers/base/firmware_loader/main.c
> > +   which has the modified request_firmware_nowait() function.
> >  
> > Also after updating the BIOS image a user mode application needs to 
> > execute
> > code which sends the BIOS update request to the BIOS. So on the next 
> > reboot  
> 
> This part looks good and is needed.

Ok. I'll submit this as a separate patch.

> 
> > diff --git a/Documentation/driver-api/firmware/fallback-mechanisms.rst 
> > b/Documentation/driver-api/firmware/fallback-mechanisms.rst
> > index f353783ae0be..7aed31b5a439 100644
> > --- a/Documentation/driver-api/firmware/fallback-mechanisms.rst
> > +++ b/Documentation/driver-api/firmware/fallback-mechanisms.rst
> > @@ -72,7 +72,7 @@ the firmware requested, and establishes it in the device 
> > hierarchy by
> >  associating the device used to make the request as the device's parent.
> >  The sysfs directory's file attributes are defined and controlled through
> >  the new device's class (firmware_class) and group (fw_dev_attr_groups).
> > -This is actually where the original firmware_class.c file name comes from,
> > +This is actually where drivers/base/firmware_loader/fallback.c comes from, 
> >  
> 
> Not this part.
> 
> What I meant to keep well documented here was not just only the old firmware
> file name for the code, but also the module name firmware_class, and its
> respective sysfs class name which is registered. From what I recall testing, 
> we
> could not rename the module now because of this. I believe it had to do with
> the modular case, given the sysfs class could still be registered.
> 
> The fact that I forget the exact *issue* which prevented the module rename 
> shows
> how important it is to document this.
> 
> Folks 10 years from now may wonder why the hell that name stuck, and the 
> point was
> to document that the *original* loader was the sysfs fallback mechanism.

Yeah, I was in doubt about this one too. Yet, IMHO, mentioning a filename
that got removed will also be problematic 10 years from now. Perhaps you 
could say something similar to:

Originally, the only firmware loading mechanism available was the
one that it is now used as fallback. The file containing it used
to be named after it, as firmware_class.c (nowadays, the fallback
mechanism is at drivers/base/firmware_loader/fallback.c).

This way, you keep providing the explanations while pointing to the new
location of the code.

Just my 2 cents.

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 16/18] mtd: rawnand.h: use nested union kernel-doc markups

[Boris Brezillon]

On Wed, 9 May 2018 09:10:34 -0300
Mauro Carvalho Chehab  wrote:

> Hi Boris,
> 
> Em Mon, 7 May 2018 08:32:32 -0300
> Mauro Carvalho Chehab  escreveu:
> 
> > Hi Boris,
> > 
> > Em Mon, 7 May 2018 11:46:50 +0200
> > Boris Brezillon  escreveu:  
> 
> > > Is there a simple
> > > way we can get rid of the warning we have when not describing timings
> > > but all of its fields?
> > 
> > There's no direct way. It won't be hard to add a way to do it,
> > like applying the enclosed patch with ends by declaring timings as:
> > 
> > * @timings:  -- undescribed --
> > 
> > IMHO, this is uglier.  
> 
> Didn't hear from you.

I replied just a few minutes ago ;).

> What do you prefer for me to do with regards to
> this patch? 

Will queue the initial patch to nand/next (I can also queue it to the
fixes branch if you prefer).


--
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 16/18] mtd: rawnand.h: use nested union kernel-doc markups

[Mauro Carvalho Chehab]

Hi Boris,

Em Mon, 7 May 2018 08:32:32 -0300
Mauro Carvalho Chehab  escreveu:

> Hi Boris,
> 
> Em Mon, 7 May 2018 11:46:50 +0200
> Boris Brezillon  escreveu:

> > Is there a simple
> > way we can get rid of the warning we have when not describing timings
> > but all of its fields?  
> 
> There's no direct way. It won't be hard to add a way to do it,
> like applying the enclosed patch with ends by declaring timings as:
> 
>   * @timings:  -- undescribed --
> 
> IMHO, this is uglier.

Didn't hear from you. What do you prefer for me to do with regards to
this patch? 

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 09/18] net: mac80211.h: fix a bad comment line

[Johannes Berg]

On Wed, 2018-05-09 at 09:04 -0300, Mauro Carvalho Chehab wrote:
> Em Mon, 07 May 2018 14:38:26 +0200
> Johannes Berg  escreveu:
> 
> > On Mon, 2018-05-07 at 15:37 +0300, Kalle Valo wrote:
> > > Mauro Carvalho Chehab  writes:
> > >   
> > > > Sphinx produces a lot of errors like this:
> > > > ./include/net/mac80211.h:2083: warning: bad line:  >
> > > > 
> > > > Signed-off-by: Mauro Carvalho Chehab   
> > > 
> > > Randy already submitted a similar patch:
> > > 
> > > https://patchwork.kernel.org/patch/10367275/
> > > 
> > > But it seems Johannes has not applied that yet.  
> > 
> > Yeah, I've been super busy preparing for the plugfest.
> > 
> > I'll make a pass over all the patches as soon as I can, hopefully today
> > or tomorrow.
> 
> Thanks. I'll drop it from my patchset, assuming that you'll
> be applying Randy's version or mine via your tree.

Right, I did, just need to send a pull request.

johannes
--
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 09/18] net: mac80211.h: fix a bad comment line

[Mauro Carvalho Chehab]

Em Mon, 07 May 2018 14:38:26 +0200
Johannes Berg  escreveu:

> On Mon, 2018-05-07 at 15:37 +0300, Kalle Valo wrote:
> > Mauro Carvalho Chehab  writes:
> >   
> > > Sphinx produces a lot of errors like this:
> > >   ./include/net/mac80211.h:2083: warning: bad line:  >
> > > 
> > > Signed-off-by: Mauro Carvalho Chehab   
> > 
> > Randy already submitted a similar patch:
> > 
> > https://patchwork.kernel.org/patch/10367275/
> > 
> > But it seems Johannes has not applied that yet.  
> 
> Yeah, I've been super busy preparing for the plugfest.
> 
> I'll make a pass over all the patches as soon as I can, hopefully today
> or tomorrow.

Thanks. I'll drop it from my patchset, assuming that you'll
be applying Randy's version or mine via your tree.

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 16/18] mtd: rawnand.h: use nested union kernel-doc markups

[Boris Brezillon]

On Mon, 7 May 2018 08:32:32 -0300
Mauro Carvalho Chehab  wrote:

> Hi Boris,
> 
> Em Mon, 7 May 2018 11:46:50 +0200
> Boris Brezillon  escreveu:
> 
> > Hi Mauro,  
> 
> > > diff --git a/include/linux/mtd/rawnand.h b/include/linux/mtd/rawnand.h
> > > index 5dad59b31244..b986f94906df 100644
> > > --- a/include/linux/mtd/rawnand.h
> > > +++ b/include/linux/mtd/rawnand.h
> > > @@ -740,8 +740,9 @@ enum nand_data_interface_type {
> > >  
> > >  /**
> > >   * struct nand_data_interface - NAND interface timing
> > > - * @type:type of the timing
> > > - * @timings: The timing, type according to @type
> > > + * @type: type of the timing
> > > + * @timings:  The timing, type according to @type
> > > + * @timings.sdr: Use it when @type is %NAND_SDR_IFACE.
> > 
> > Hm, really feels weird to do that. I mean, either we describe
> > timings.sdr or timings, but not both. I this case, I agree that
> > describing timings.sdr would make more sense than generically
> > describing any possible entries in the timings union.  
> 
> This struct is funny, as the union has just one item. I assume
> that the original intend is to be ready to have more timing
> types (or you had it in the past). By the time you have a
> second value there, describing the union would make more
> sense.
> 
> > Is there a simple
> > way we can get rid of the warning we have when not describing timings
> > but all of its fields?  
> 
> There's no direct way. It won't be hard to add a way to do it,
> like applying the enclosed patch with ends by declaring timings as:
> 
>   * @timings:  -- undescribed --
> 
> IMHO, this is uglier.

Yep, don't like it either. I'll just take your initial patch.

Thanks,

Boris
--
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 06/18] docs: core-api: add cgroup-v2 documentation

[Mauro Carvalho Chehab]

Em Tue, 8 May 2018 09:51:14 -0600
Jonathan Corbet  escreveu:

> On Mon,  7 May 2018 06:35:42 -0300
> Mauro Carvalho Chehab  wrote:
> 
> > The cgroup-v2.txt is already in ReST format. So, move it to the
> > core-api guide, where it belongs.
> > 
> > Signed-off-by: Mauro Carvalho Chehab   
> 
> Honestly, this seems to me like sysadmin material, so I think it should
> go into the admin guide instead.
> 
> Actually, looking at the patch, it seems you agree - it's just the
> changelog that's wrong :)

Yeah, wrong cut-and-paste. Sorry for that.

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

I'll repost it c/c to cgroup maintainers with the right
description.

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 15/18] iio: iio.h: use nested struct support on kernel-doc markup

[Mauro Carvalho Chehab]

Em Mon, 7 May 2018 18:08:03 +0100
Jonathan Cameron  escreveu:

> On Mon,  7 May 2018 06:35:51 -0300
> Mauro Carvalho Chehab  wrote:
> 
> > Solve those Sphinx warnings:
> > 
> > ./include/linux/iio/iio.h:270: warning: Function parameter or member 
> > 'scan_type.sign' not described in 'iio_chan_spec'
> > ./include/linux/iio/iio.h:270: warning: Function parameter or member 
> > 'scan_type.realbits' not described in 'iio_chan_spec'
> > ./include/linux/iio/iio.h:270: warning: Function parameter or member 
> > 'scan_type.storagebits' not described in 'iio_chan_spec'
> > ./include/linux/iio/iio.h:270: warning: Function parameter or member 
> > 'scan_type.shift' not described in 'iio_chan_spec'
> > ./include/linux/iio/iio.h:270: warning: Function parameter or member 
> > 'scan_type.repeat' not described in 'iio_chan_spec'
> > ./include/linux/iio/iio.h:270: warning: Function parameter or member 
> > 'scan_type.endianness' not described in 'iio_chan_spec'
> > 
> > ./include/linux/iio/iio.h:191: WARNING: Unexpected indentation.
> > ./include/linux/iio/iio.h:192: WARNING: Block quote ends without a 
> > blank line; unexpected unindent.
> > ./include/linux/iio/iio.h:198: WARNING: Definition list ends without a 
> > blank line; unexpected unindent.
> > 
> > Signed-off-by: Mauro Carvalho Chehab   
> Great thanks.  I couldn't figure out how to do this last time
> I looked at it.

Support for nested structs were only recently introduced :-)

> 
> Applied to the togreg branch of iio.git and pushed out as testing for
> the autobuilders to ignore it.

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 10/18] rcu: rcupdate.h: get rid of Sphinx warnings at rcu_pointer_handoff()

[Mauro Carvalho Chehab]

Em Mon, 7 May 2018 07:23:22 -0700
"Paul E. McKenney"  escreveu:

> On Mon, May 07, 2018 at 06:35:46AM -0300, Mauro Carvalho Chehab wrote:
> > The code example at rcupdate.h currently produce lots of warnings:
> > 
> > ./include/linux/rcupdate.h:572: WARNING: Unexpected indentation.
> > ./include/linux/rcupdate.h:576: WARNING: Unexpected indentation.
> > ./include/linux/rcupdate.h:580: WARNING: Block quote ends without a 
> > blank line; unexpected unindent.
> > ./include/linux/rcupdate.h:582: WARNING: Block quote ends without a 
> > blank line; unexpected unindent.
> > ./include/linux/rcupdate.h:582: WARNING: Inline literal start-string 
> > without end-string.
> > 
> > Change it to a code-block.
> > 
> > Signed-off-by: Mauro Carvalho Chehab   
> 
> Acked-by: Paul E. McKenney 
> 
> If you don't tell me otherwise, I will assume that you are pushing this.
> If you would rather that I take it, please let me know!

Hi Paul,

Feel free to merge it via your tree. It seems that Jon prefers to have
code changes merged via the usual maintainers.

Regards,
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 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Peter Zijlstra]

On Mon, May 07, 2018 at 06:35:49AM -0300, Mauro Carvalho Chehab wrote:
> The flow diagram should be inside a code-block to avoid those
> warnings:
>   ./include/linux/wait.h:110: WARNING: Block quote ends without a blank 
> line; unexpected unindent.
>   ./include/linux/wait.h:113: WARNING: Unexpected indentation.
>   ./include/linux/wait.h:115: WARNING: Block quote ends without a blank 
> line; unexpected unindent.
> 
> This is easily done by using "::" instead of just ":".

And I'll voice my objection once again. This makes a regular comment
worse. This rst stuff is utter shit for making normal text files less
readable in your favourite text editor.

If this gets merged, I'll simply remove that spurious ':' the next time
I'm near that comment.

> Signed-off-by: Mauro Carvalho Chehab 
> ---
>  include/linux/wait.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/include/linux/wait.h b/include/linux/wait.h
> index d9f131ecf708..d907ed761a7f 100644
> --- a/include/linux/wait.h
> +++ b/include/linux/wait.h
> @@ -101,7 +101,7 @@ init_waitqueue_func_entry(struct wait_queue_entry 
> *wq_entry, wait_queue_func_t f
>   * lead to sporadic and non-obvious failure.
>   *
>   * Use either while holding wait_queue_head::lock or when used for wakeups
> - * with an extra smp_mb() like:
> + * with an extra smp_mb() like::
>   *
>   *  CPU0 - wakerCPU1 - waiter
>   *
> -- 
> 2.17.0
> 
--
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 -mm] mm, THP, doc: Add document for thp_swpout/thp_swpout_fallback

[Huang, Ying]

From: Huang Ying 

Add document for newly added thp_swpout, thp_swpout_fallback fields in
/proc/vmstat.

Signed-off-by: "Huang, Ying" 
Cc: "Kirill A. Shutemov" 
Cc: Andrea Arcangeli 
Cc: Johannes Weiner 
---
 Documentation/vm/transhuge.rst | 9 +
 1 file changed, 9 insertions(+)

diff --git a/Documentation/vm/transhuge.rst b/Documentation/vm/transhuge.rst
index 569d182cc973..2c6867fca6ff 100644
--- a/Documentation/vm/transhuge.rst
+++ b/Documentation/vm/transhuge.rst
@@ -355,6 +355,15 @@ thp_zero_page_alloc_failed
is incremented if kernel fails to allocate
huge zero page and falls back to using small pages.
 
+thp_swpout
+   is incremented every time a huge page is swapout in one
+   piece without splitting.
+
+thp_swpout_fallback
+   is incremented if a huge page has to be split before swapout.
+   Usually because failed to allocate some continuous swap space
+   for the huge page.
+
 As the system ages, allocating huge pages may be expensive as the
 system uses memory compaction to copy data around memory to free a
 huge page for use. There are some counters in ``/proc/vmstat`` to help
-- 
2.16.1

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