Re: [PATCH v4 6/7] ocxl: Add an IOCTL so userspace knows what OCXL features are available

[Michael Ellerman]

"Alastair D'Silva"  writes:

> diff --git a/include/uapi/misc/ocxl.h b/include/uapi/misc/ocxl.h
> index 8d2748e69c84..bb80f294b429 100644
> --- a/include/uapi/misc/ocxl.h
> +++ b/include/uapi/misc/ocxl.h
> @@ -72,5 +75,6 @@ struct ocxl_ioctl_irq_fd {
>  #define OCXL_IOCTL_IRQ_SET_FD_IOW(OCXL_MAGIC, 0x13, struct 
> ocxl_ioctl_irq_fd)
>  #define OCXL_IOCTL_GET_METADATA _IOR(OCXL_MAGIC, 0x14, struct 
> ocxl_ioctl_metadata)
>  #define OCXL_IOCTL_ENABLE_P9_WAIT_IOR(OCXL_MAGIC, 0x15, struct 
> ocxl_ioctl_p9_wait)
> +#define OCXL_IOCTL_GET_FEATURES _IOR(OCXL_MAGIC, 0x16, struct 
> ocxl_ioctl_platform)

I don't have ocxl_ioctl_platform ?

../include/uapi/misc/ocxl.h:78:56: error: invalid application of ‘sizeof’ to 
incomplete type ‘struct ocxl_ioctl_platform’
 #define OCXL_IOCTL_GET_FEATURES _IOR(OCXL_MAGIC, 0x16, struct 
ocxl_ioctl_platform)
^
../include/uapi/asm-generic/ioctl.h:73:5: note: in definition of macro ‘_IOC’
   ((size) << _IOC_SIZESHIFT))
 ^~~~
../include/uapi/asm-generic/ioctl.h:86:56: note: in expansion of macro 
‘_IOC_TYPECHECK’
 #define _IOR(type,nr,size) _IOC(_IOC_READ,(type),(nr),(_IOC_TYPECHECK(size)))
^~
../include/uapi/misc/ocxl.h:78:33: note: in expansion of macro ‘_IOR’
 #define OCXL_IOCTL_GET_FEATURES _IOR(OCXL_MAGIC, 0x16, struct 
ocxl_ioctl_platform)
 ^~~~
../drivers/misc/ocxl/file.c:262:7: note: in expansion of macro 
‘OCXL_IOCTL_GET_FEATURES’
  case OCXL_IOCTL_GET_FEATURES:
   ^~~

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

Re: [PATCH v3 5/7] ocxl: Expose the thread_id needed for wait on POWER9

[Michael Ellerman]

"Alastair D'Silva"  writes:
> diff --git a/include/uapi/misc/ocxl.h b/include/uapi/misc/ocxl.h
> index 0af83d80fb3e..8d2748e69c84 100644
> --- a/include/uapi/misc/ocxl.h
> +++ b/include/uapi/misc/ocxl.h
> @@ -48,6 +48,15 @@ struct ocxl_ioctl_metadata {
>   __u64 reserved[13]; // Total of 16*u64
>  };
>  
> +struct ocxl_ioctl_p9_wait {
> + __u16 thread_id; // The thread ID required to wake this thread
> + __u16 reserved1;
> + __u32 reserved2;
> + __u64 reserved3[3];
> +};
> +
> +};
> +

O_o

???

cheers
--
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] bpf, doc: clarification for the meaning of 'id'

[Daniel Borkmann]

On 05/10/2018 05:09 AM, Wang YanQing wrote:
> 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 

Applied to bpf-next, thanks Wang!
--
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 00/11] Fix some doc build warnings/errors and broken links

[Mauro Carvalho Chehab]

Em Thu, 10 May 2018 14:22:35 -0600
Jonathan Corbet  escreveu:

> On Wed,  9 May 2018 10:18:43 -0300
> Mauro Carvalho Chehab  wrote:
> 
> > Patches 1 to 5 on this series contain the patches that weren't yet
> > applied from the past patch series and touch only at Documentation.
> > There are two changes there:
> >   patch 2: fixed the description and added a c/c to cgroup maintainers;
> >   patch 4: rewritten according with Louis request, droping several hunks.  
> 
> Of these, I've applied 2, 4, and 6.  The networking and crypto folks like
> to apply their own documentation fixes; I assume they'll pick these up.

Hmm... I'm pretty sure I emailed about patch 4. Luis actually came with
a better solution: he partially removed the note, as it is outdated.
Better to revert it as otherwise it will rise conflicts at -next once
merged.

> 
> > Patch 6 rewrites scripts/documentation-file-ref-check on Perl,
> > adding an auto-fix feature.  
> 
> Applied this one.
> 
> > Patches 7 and 8 fix things that would cause troubles for the
> > automatic autocorrection tool.  
> 
> #7 is applied.  #8 doesn't apply, though; I'm not sure which tree you made
> it against?  In any case, I've stopped here for now.

Andrea commented about #8. You already applied an identical patch :-)

> > Patch 9 touches a lot of random places (including MAINTAINERS)
> > that contain broken links and can be auto-fixed. It could be
> > broken into one patch per touched file, but I think that is
> > overkill.   
> 
> Let's keep this one (and the ones that follow) aside.  I'm happy to apply
> them, but I think they are best applied as an end-of-merge-window thing.  I
> envision lots of conflicts, and I already have a pile of those to explain
> to Linus this time around.

Yeah, this patch touches on a lot of stuff. Better to handle it by the
end of a merge window.

I suspect you'll need to re-generate it by running this command again:

./scripts/documentation-file-ref-check --fix

But you should check the results, as false positives may arise.

If you prefer, I rebased the tree with the pending patches, placing
patch 9 at the end. This way, you'll likely avoid conflicts with
patches 10 and 11.

https://git.linuxtv.org/mchehab/experimental.git/log/?h=broken-links-v4

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 00/11] Fix some doc build warnings/errors and broken links

[Jonathan Corbet]

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

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

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

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

Applied this one.

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

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

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

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

Sound good?

Thanks,

jon
--
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 -mm] mm, THP, doc: Add document for thp_swpout/thp_swpout_fallback

[Jonathan Corbet]

On Wed,  9 May 2018 16:23:41 +0800
"Huang, Ying"  wrote:

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

Applied, thanks.

jon
--
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/process/posting: wrap text at 80 cols

[Jonathan Corbet]

On Thu, 10 May 2018 20:37:37 +0100
Justin Skists  wrote:

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

Applied, thanks.

jon
--
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 02/11] docs: admin-guide: add cgroup-v2 documentation

[Jonathan Corbet]

On Thu, 10 May 2018 11:40:18 -0700
Tejun Heo  wrote:

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

Applied to the docs tree, thanks.

jon
--
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/process/posting: wrap text at 80 cols

[Justin Skists]

Trivial patch to adjust the text formatting to wrap at 80 columns. No
actual content has changed.

Signed-off-by: Justin Skists 
---
 Documentation/process/5.Posting.rst | 16 
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/process/5.Posting.rst 
b/Documentation/process/5.Posting.rst
index c209d70da66f..c418c5d6cae4 100644
--- a/Documentation/process/5.Posting.rst
+++ b/Documentation/process/5.Posting.rst
@@ -10,8 +10,8 @@ of conventions and procedures which are used in the posting 
of patches;
 following them will make life much easier for everybody involved.  This
 document will attempt to cover these expectations in reasonable detail;
 more information can also be found in the files process/submitting-patches.rst,
-process/submitting-drivers.rst, and process/submit-checklist.rst in the kernel 
documentation
-directory.
+process/submitting-drivers.rst, and process/submit-checklist.rst in the kernel
+documentation directory.
 
 
 When to post
@@ -198,8 +198,8 @@ pass it to diff with the "-X" option.
 
 The tags mentioned above are used to describe how various developers have
 been associated with the development of this patch.  They are described in
-detail in the process/submitting-patches.rst document; what follows here is a 
brief
-summary.  Each of these lines has the format:
+detail in the process/submitting-patches.rst document; what follows here is a
+brief summary.  Each of these lines has the format:
 
 ::
 
@@ -210,8 +210,8 @@ The tags in common use are:
  - Signed-off-by: this is a developer's certification that he or she has
the right to submit the patch for inclusion into the kernel.  It is an
agreement to the Developer's Certificate of Origin, the full text of
-   which can be found in Documentation/process/submitting-patches.rst.  Code 
without a
-   proper signoff cannot be merged into the mainline.
+   which can be found in Documentation/process/submitting-patches.rst.  Code
+   without a proper signoff cannot be merged into the mainline.
 
  - Co-developed-by: states that the patch was also created by another developer
along with the original author.  This is useful at times when multiple
@@ -226,8 +226,8 @@ The tags in common use are:
it to work.
 
  - Reviewed-by: the named developer has reviewed the patch for correctness;
-   see the reviewer's statement in 
Documentation/process/submitting-patches.rst for more
-   detail.
+   see the reviewer's statement in Documentation/process/submitting-patches.rst
+   for more detail.
 
  - Reported-by: names a user who reported a problem which is fixed by this
patch; this tag is used to give credit to the (often underappreciated)
-- 
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 v2 02/11] docs: admin-guide: add cgroup-v2 documentation

[Tejun Heo]

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

Acked-by: Tejun Heo 

Thanks.

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

[Mauro Carvalho Chehab]

Em Thu, 10 May 2018 18:52:20 +0200
Andrea Parri  escreveu:

> On Thu, May 10, 2018 at 07:15:59AM -0600, Jonathan Corbet wrote:
> > On Thu, 10 May 2018 14:23:35 +0200
> > Andrea Parri  wrote:
> >   
> > > only
> > > remember that other people (including some developers running into the
> > > "disadventure" of opening an RST doc. from their preferred text editor
> > > and being brought to conclude:  "WTH!  I need to open a web browser, I
> > > guess...") _use_ such doc. and _do care_ about it, and that what might
> > > be an improvement for some people might look as "vandalizing" to others.  
> > 
> > If you have an example of a place where use of a web browser has been
> > made mandatory, please point it out.  Avoiding that was at the top of the
> > list of explicit requirements.  
> 
> That's all I need.
> 
> 
> >Surely an extra colon is not going to
> > force you to run screaming to the protective embrace of Firefox...?  
> 
> Let me put it in these terms: I believe that that extra colon (or the
> "diagram" keywork) is not going to improve/help my use of the doc. ;D

No, it won't improve, but, it won't make it harder for a human
to understand if a "diagram" or "::" is added at the description.

The thing is that we need something that works for the Kernel as
a hole, and not just on a few places.

On some subsystems, just a text is not good enough to describe
things. See, for example:
https://www.kernel.org/doc/html/latest/media/uapi/v4l/crop.html

https://www.kernel.org/doc/html/latest/media/uapi/v4l/pixfmt-packed-rgb.html

https://www.kernel.org/doc/html/latest/media/uapi/v4l/pixfmt-srggb10-ipu3.html
https://www.kernel.org/doc/html/latest/gpu/drm-kms.html

Images, complex tables, etc are sometimes required to show some things.
Trying to explain just on text is harder to write, longer and worse
for readers. In the past, DocBook was used. ReST made very simple to
write documentation. From where I sit, I'm reviewing documentation
patches from a lot more people than the usage of a markup language.

As a bonus, we can now create cross-references for kernel-doc functions,
with is really great when reading documentation for complex hardware.

From where I sit at media, the subsystem documentation, if generated
in PDF, becomes a book with more than 1,100 pages, full of long tables,
images and graphs[1], covering uAPI, kAPI and driver-specific
documentation.

[1] https://linuxtv.org/downloads/v4l-dvb-apis-new/media.pdf

As on all subsystems, developers write documentation directly
at .rst or as kernel-doc comments. But for reading it, even developers
prefer to read the docs via the html (or pdf) output, as it better
shows tables and images. It is also faster to follow the dozen
thousands of links inside it.

The point is: we shouldn't enforce everyone to use our own view
about how to navigate through documentation. People are free to
use whatever improves their 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

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

[Mauro Carvalho Chehab]

Em Thu, 10 May 2018 13:42:58 -0300
Mauro Carvalho Chehab  escreveu:

> Em Thu, 10 May 2018 09:38:46 -0600
> Jonathan Corbet  escreveu:
> 
> > On Thu, 10 May 2018 11:21:13 -0300
> > Mauro Carvalho Chehab  wrote:
> > 
> > > The problem with a hint-based mechanism is that it will generate
> > > false hints. If added, we may end by needing to add extra tags to
> > > disable the hints mechanism where it gets wrong, or to periodically
> > > do code changes at kernel-doc comments in order to make the hints
> > > logic happy.
> > > 
> > > So, IMO, we should provide non-hints based mechanism, like forcing the
> > > string that prepends the colon to have a keyword that will make it to
> > > parse the block as literal, where expressions like:
> > > 
> > >   See the code-block foo:
> > >   See the following code example:
> > >   See the following flow diagram:
> > >   See the following artwork:
> > > 
> > > Is the best alternative to avoid "::", as on the enclosed patch.  
> > 
> > But this, too, is a hint-based mechanism.  Thanks for the patches, I'll
> > keep them around, but I would like an opportunity to try to do better
> > before applying them.  I fear that using magic words in this way will
> > lead to a constant stream of surprises, and I'd like to avoid that if
> > possible...
> 
> Yes, it is still hint-based. A careful selection of the "magic spell
> words/phrases" would minimize the risks of false positives, but it
> could still lead into some unwanted surprises.

Btw, running this:

$ git grep -A2 "\*\s.*following.*(code|example|artwork|flow|diagram).*:$"

currently doesn't have a single match. 

If we force a two word combination, and an ending with ":" should
be enough to not having too much false positives.

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

[Andrea Parri]

On Thu, May 10, 2018 at 07:15:59AM -0600, Jonathan Corbet wrote:
> On Thu, 10 May 2018 14:23:35 +0200
> Andrea Parri  wrote:
> 
> > only
> > remember that other people (including some developers running into the
> > "disadventure" of opening an RST doc. from their preferred text editor
> > and being brought to conclude:  "WTH!  I need to open a web browser, I
> > guess...") _use_ such doc. and _do care_ about it, and that what might
> > be an improvement for some people might look as "vandalizing" to others.
> 
> If you have an example of a place where use of a web browser has been
> made mandatory, please point it out.  Avoiding that was at the top of the
> list of explicit requirements.

That's all I need.


>Surely an extra colon is not going to
> force you to run screaming to the protective embrace of Firefox...?

Let me put it in these terms: I believe that that extra colon (or the
"diagram" keywork) is not going to improve/help my use of the doc. ;D

  Andrea


> 
> 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: [RFC PATCH 1/2] scripts/kernel-doc: Auto-detect common code-blocks

[Jonathan Corbet]

On Thu, 10 May 2018 09:34:56 -0700
Matthew Wilcox  wrote:

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

Yeah, we might want to write something like:

 - Leading off a bulleted list

 1) or a numbered list

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

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

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

[Mauro Carvalho Chehab]

Em Thu, 10 May 2018 09:38:46 -0600
Jonathan Corbet  escreveu:

> On Thu, 10 May 2018 11:21:13 -0300
> Mauro Carvalho Chehab  wrote:
> 
> > The problem with a hint-based mechanism is that it will generate
> > false hints. If added, we may end by needing to add extra tags to
> > disable the hints mechanism where it gets wrong, or to periodically
> > do code changes at kernel-doc comments in order to make the hints
> > logic happy.
> > 
> > So, IMO, we should provide non-hints based mechanism, like forcing the
> > string that prepends the colon to have a keyword that will make it to
> > parse the block as literal, where expressions like:
> > 
> > See the code-block foo:
> > See the following code example:
> > See the following flow diagram:
> > See the following artwork:
> > 
> > Is the best alternative to avoid "::", as on the enclosed patch.  
> 
> But this, too, is a hint-based mechanism.  Thanks for the patches, I'll
> keep them around, but I would like an opportunity to try to do better
> before applying them.  I fear that using magic words in this way will
> lead to a constant stream of surprises, and I'd like to avoid that if
> possible...

Yes, it is still hint-based. A careful selection of the "magic spell
words/phrases" would minimize the risks of false positives, but it
could still lead into some unwanted surprises.

IMO, "::" (or some other character combination that is not used
elsewhere) is still the safest option.


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: [RFC PATCH 1/2] scripts/kernel-doc: Auto-detect common code-blocks

[Matthew Wilcox]

On Thu, May 10, 2018 at 10:38:16AM -0400, Mauro Carvalho Chehab wrote:
> Comments that end with a comma and have certain keywords
> should be presented as code-blocks

I think this is a bit fragile.  Why not just search for ':\n'?  Is
there ever a case where we want to write:

/**
 * foo is a bar:
 * wibble
 */
and have wibble not be a code-block?

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

Re: [RFC PATCH 2/2] wait: add a keyword to indicate a diagram code block on a kernel-doc

[Randy Dunlap]

On 05/10/2018 07:38 AM, Mauro Carvalho Chehab wrote:
> When handling code-blocks, usual parsing should be disabled.
> Indicate it by using the keyword disagram.

   diagram.

Please add such keyword(s) to one of 
Documentation/doc-guide/{kernel-doc,sphinx}.rst.

> 
> 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..653814475ee9 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() as shown in this diagram:
>   *
>   *  CPU0 - wakerCPU1 - waiter
>   *
> 


-- 
~Randy
--
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 Thu, 10 May 2018 11:21:13 -0300
Mauro Carvalho Chehab  wrote:

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

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

Thanks,

jon
--
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 1/2] scripts/kernel-doc: Auto-detect common code-blocks

[Mauro Carvalho Chehab]

Comments that end with a comma and have certain keywords
should be presented as code-blocks

Signed-off-by: Mauro Carvalho Chehab 
---
 scripts/kernel-doc | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 0057d8eafcc1..8ce2d0f54369 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -803,7 +803,8 @@ sub output_highlight_rst {
#
if (! $in_literal) {
$block .= $line . "\n";
-   if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) {
+   if (($block =~ 
s/(code|example|artwork|flow|diagram)([^\:]*:)\n/$1$2:\n/) ||
+   ($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) {
$in_literal = 1;
$litprefix = "";
$output .= highlight_block($block);
-- 
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

[RFC PATCH 2/2] wait: add a keyword to indicate a diagram code block on a kernel-doc

[Mauro Carvalho Chehab]

When handling code-blocks, usual parsing should be disabled.
Indicate it by using the keyword disagram.

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..653814475ee9 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() as shown in this diagram:
  *
  *  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

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

[Mauro Carvalho Chehab]

Em Thu, 10 May 2018 07:30:12 -0600
Jonathan Corbet  escreveu:

> On Thu, 10 May 2018 06:38:05 -0300
> Mauro Carvalho Chehab  wrote:
> 
> > (Peter said):  
> > > Independent of any philosophical discussion not allowing a setence to
> > > end with a single ':' is completely idiotic.  Please fix the tooling
> > > instead to allow it, as it is very important for being able to just
> > > write understandable comments.
> 
> FWIW, there's no problem with a sentence ending with a single colon.
> It's only an issue if you want to flag a special interpretation for the
> text that follows that sentence.  Just to be precise.
> 
> > Patches are welcome, although I don't see any easy way to solve it.  
> 
> I could envision some sort of heuristic that would recognize an indented
> block containing code.  Probably we could go simpler and force the
> "literal block" treatment for any indented block that lacks explicit
> enumeration markers.  So:
> 
>   this->would_be("a literal block");
> 
> but:
> 
>   - This would not be
> 
> Such a thing would likely be a bit fragile (people feel, rightly, that
> they can put anything into normal text) but it might just work well
> enough.  For best results, it should probably be done as part of Sphinx
> itself, rather than yet another ugly hack in the kerneldoc script.

I guess that it also won't work...

$ git grep -A2 "\*\s.*\s.*:$" -- $(git grep kernel-doc:: Documentation/|cut -d 
: -f 4-)

Present some matches that seem to be violating such hint.

drivers/edac/edac_device.h:/* The offset value can be:
drivers/edac/edac_device.h- *   -1 indicating no offset value
drivers/edac/edac_device.h- *   0 for zero-based block numbers

drivers/gpu/drm/drm_scdc_helper.c: *As per the spec:
drivers/gpu/drm/drm_scdc_helper.c- *TMDS clock rate for pixel clock 
< 340 MHz = 1x the character
drivers/gpu/drm/drm_scdc_helper.c- *rate = 1/10 pixel clock rate

I didn't actually check if those are part of a Kernel-doc markup, though,
but it shows that people sometimes don't add a "prepend" character to
a list.

In the specific case of errors, prepending with a "-" can be weird,
as it may lead ugly things like:

* - -1 indicating no offset value
* - 0 for zero-based block numbers

The problem with a hint-based mechanism is that it will generate
false hints. If added, we may end by needing to add extra tags to
disable the hints mechanism where it gets wrong, or to periodically
do code changes at kernel-doc comments in order to make the hints
logic happy.

So, IMO, we should provide non-hints based mechanism, like forcing the
string that prepends the colon to have a keyword that will make it to
parse the block as literal, where expressions like:

See the code-block foo:
See the following code example:
See the following flow diagram:
See the following artwork:

Is the best alternative to avoid "::", as on the enclosed patch.

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

Thanks,
Mauro

[PATCH] Mark a diagram at wait.h as such, using a code-block for it

Instead of explicitly using "::" to mark the diagram,
detect it based on code words inside the description.

Signed-off-by: Mauro Carvalho Chehab 

diff --git a/include/linux/wait.h b/include/linux/wait.h
index d9f131ecf708..c360c5947374 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 on this diagram:
  *
  *  CPU0 - wakerCPU1 - waiter
  *
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 0057d8eafcc1..1c69072997f8 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -803,7 +803,12 @@ sub output_highlight_rst {
#
if (! $in_literal) {
$block .= $line . "\n";
-   if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) {
+   if ($block =~ 
s/(code|example|artwork|flow|diagram)([^\:]*:)\n/$1$2:\n/) {
+   $in_literal = 1;
+   $litprefix = "";
+   $output .= highlight_block($block);
+   $block = ""
+   } elsif (($line =~ /$sphinx_literal/) || ($line =~ 
/$sphinx_cblock/)) {
$in_literal = 1;
$litprefix = "";
$output .= highlight_block($block);


--
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 Thu, 10 May 2018 07:30:12 -0600
Jonathan Corbet  wrote:

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

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

jon
--
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 Thu, 10 May 2018 06:38:05 -0300
Mauro Carvalho Chehab  wrote:

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

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

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

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

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

but:

  - This would not be

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

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

jon
--
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 Thu, 10 May 2018 14:23:35 +0200
Andrea Parri  wrote:

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

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

Thanks,

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

[Mauro Carvalho Chehab]

Em Thu, 10 May 2018 14:20:36 +0200
Peter Zijlstra  escreveu:

> On Thu, May 10, 2018 at 06:38:05AM -0300, Mauro Carvalho Chehab wrote:
> > Em Thu, 10 May 2018 01:38:38 -0700
> > Christoph Hellwig  escreveu:
> >   
> > > >   * 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::
> > > 
> > > Independent of any philosophical discussion not allowing a setence to
> > > end with a single ':' is completely idiotic.  Please fix the tooling
> > > instead to allow it, as it is very important for being able to just
> > > write understandable comments.  
> 
> That is exactly my point; the whole rst stuff detracts from normal text.
> It makes both reading and writing harder than it needs to be.
> 
> > Patches are welcome, although I don't see any easy way to solve it.
> > 
> > In English, the common case is that a line with ends with a colon is
> > followed by a list. E. g.  
> 
> (google) Dictionary says:
> 
> "a punctuation mark (:) used to precede a list of items, a quotation, or
> an expansion or explanation."
> 
> An enumeration (list) is just one of many possible uses of the colon.

True, but the point is that whatever tool is used, it should be able
to uniquely unambiguously identify what it follows.

For example, it if is a list of items, it should keep parsing the
semantics markups inside it e. g. marking %FOO as a constant,
and bar() as a function, etc, following kernel-doc syntax. 

But, if it is a quote, a code example or an ascii artwork, it
should disable all such parsers, enclosing the result into a
literal block.

> > However, in this specific case, it is followed by an ascii artwork. 
> > The double colon is a notation that tells Sphinx to not parse the
> > lines at the next block, placing the contents of it inside a literal
> > block. It is used also when the next lines contain a code example,
> > in order to avoid parsing things like @, () and * inside the code 
> > block.
> > 
> > The kernel-doc tool might eventually have some parsing logic that
> > would replace something to a '::' before sending it to Sphinx.  
> 
> I think typically there will be an 'empty' line between the colon ending
> and the 'example/explanation'. This seems true for a number of comments
> I found in drm using the '::' nonsense.

Unfortunately, that's not true treewide. The presense/absense of a
blank line after a line ending with a colon doesn't indicate if the contents
below should be handled as a literal block or not[1].

[1] you can verify some use cases with:
$ git grep -A2 "\*.*\s.*:$" -- $(git grep kernel-doc:: 
Documentation/|cut -d : -f 4-)

> Simple regexes don't do multi-line patterns, but maybe the kerneldoc
> thing can parse it differently.

kernel-doc is a regex-based parser (and not an AI engine). It will do only
what it is programmed for, based on a clear regex-based semantics.

Independently on how easy/hard it would be to use a multi-line pattern
for this, what it is required is a clear non-hint based pattern that
will provide a match for a part of the tag that should be escaped
from normal parsing rules. The m/::$/ is a clear rule.

Do you have a proposal for some other rule? If so, I can see how
feasible is to add it there.

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

[Andrea Parri]

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

You wrote it:  the fact that some people (including its developers) see
a value in the RST work or the fact that such work made the kernel doc.
accessible to a larger group of readers are not in question here;  only
remember that other people (including some developers running into the
"disadventure" of opening an RST doc. from their preferred text editor
and being brought to conclude:  "WTH!  I need to open a web browser, I
guess...") _use_ such doc. and _do care_ about it, and that what might
be an improvement for some people might look as "vandalizing" to others.

We're talking about readability/accessibility here, but I think similar
considerations apply to other aspects of the doc. such as availability/
completeness (yes, I did hear developers arguing "I won't write such a
doc., because...") and consistency (w.r.t. the doc. itself and sources).

  Andrea


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

[Peter Zijlstra]

On Thu, May 10, 2018 at 06:38:05AM -0300, Mauro Carvalho Chehab wrote:
> Em Thu, 10 May 2018 01:38:38 -0700
> Christoph Hellwig  escreveu:
> 
> > >   * 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::  
> > 
> > Independent of any philosophical discussion not allowing a setence to
> > end with a single ':' is completely idiotic.  Please fix the tooling
> > instead to allow it, as it is very important for being able to just
> > write understandable comments.

That is exactly my point; the whole rst stuff detracts from normal text.
It makes both reading and writing harder than it needs to be.

> Patches are welcome, although I don't see any easy way to solve it.
> 
> In English, the common case is that a line with ends with a colon is
> followed by a list. E. g.

(google) Dictionary says:

"a punctuation mark (:) used to precede a list of items, a quotation, or
an expansion or explanation."

An enumeration (list) is just one of many possible uses of the colon.

> However, in this specific case, it is followed by an ascii artwork. 
> The double colon is a notation that tells Sphinx to not parse the
> lines at the next block, placing the contents of it inside a literal
> block. It is used also when the next lines contain a code example,
> in order to avoid parsing things like @, () and * inside the code 
> block.
> 
> The kernel-doc tool might eventually have some parsing logic that
> would replace something to a '::' before sending it to Sphinx.

I think typically there will be an 'empty' line between the colon ending
and the 'example/explanation'. This seems true for a number of comments
I found in drm using the '::' nonsense.

Simple regexes don't do multi-line patterns, but maybe the kerneldoc
thing can parse it differently.
--
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 18/18] w1: w1_io.c: fix a kernel-doc warning

[Evgeniy Polyakov]

Hi

09.05.2018, 16:11, "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.

Great, thank you!
Let me know if you want me to push it upstream via my tree.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC 01/10] PCI: dwc: Add MSI-X callbacks handler

[Gustavo Pimentel]

Hi Alan,

Sorry for the delay on the response, I only have time to proper analyze this 
now.

On 24/04/2018 10:15, Alan Douglas wrote:
> Hi,
> 
> On 10 April 2018 18:15 Gustavo Pimentel wrote:
>> Changes the pcie_raise_irq function signature, namely the interrupt_num
>> variable type from u8 to u16 to accommodate the MSI-X maximum interrupts
>> of 2048.
>>
>> Implements a PCIe config space capability iterator function to search and 
>> save
>> the MSI and MSI-X pointers. With this method the code becomes more
>> generic and flexible.
>>
>> Implements MSI-X set/get functions for sysfs interface in order to change the
>> EP entries number.
>>
>> Implements EP MSI-X interface for triggering interruptions.
>>
>> Signed-off-by: Gustavo Pimentel 
>> ---
>>  drivers/pci/dwc/pci-dra7xx.c   |   2 +-
>>  drivers/pci/dwc/pcie-artpec6.c |   2 +-
>>  drivers/pci/dwc/pcie-designware-ep.c   | 145
>> -
>>  drivers/pci/dwc/pcie-designware-plat.c |   6 +-
>>  drivers/pci/dwc/pcie-designware.h  |  23 +-
>>  5 files changed, 173 insertions(+), 5 deletions(-)
>>
>> diff --git a/drivers/pci/dwc/pci-dra7xx.c b/drivers/pci/dwc/pci-dra7xx.c 
>> index
>> ed8558d..5265725 100644
>> --- a/drivers/pci/dwc/pci-dra7xx.c
>> +++ b/drivers/pci/dwc/pci-dra7xx.c
>> @@ -369,7 +369,7 @@ static void dra7xx_pcie_raise_msi_irq(struct
>> dra7xx_pcie *dra7xx,  }
>>
>>  static int dra7xx_pcie_raise_irq(struct dw_pcie_ep *ep, u8 func_no,
>> - enum pci_epc_irq_type type, u8
>> interrupt_num)
>> + enum pci_epc_irq_type type, u16
>> interrupt_num)
>>  {
>>  struct dw_pcie *pci = to_dw_pcie_from_ep(ep);
>>  struct dra7xx_pcie *dra7xx = to_dra7xx_pcie(pci); diff --git
>> a/drivers/pci/dwc/pcie-artpec6.c b/drivers/pci/dwc/pcie-artpec6.c index
>> e66cede..96dc259 100644
>> --- a/drivers/pci/dwc/pcie-artpec6.c
>> +++ b/drivers/pci/dwc/pcie-artpec6.c
>> @@ -428,7 +428,7 @@ static void artpec6_pcie_ep_init(struct dw_pcie_ep
>> *ep)  }
>>
>>  static int artpec6_pcie_raise_irq(struct dw_pcie_ep *ep, u8 func_no,
>> -  enum pci_epc_irq_type type, u8
>> interrupt_num)
>> +  enum pci_epc_irq_type type, u16
>> interrupt_num)
>>  {
>>  struct dw_pcie *pci = to_dw_pcie_from_ep(ep);
>>
>> diff --git a/drivers/pci/dwc/pcie-designware-ep.c b/drivers/pci/dwc/pcie-
>> designware-ep.c
>> index 15b22a6..874d4c2 100644
>> --- a/drivers/pci/dwc/pcie-designware-ep.c
>> +++ b/drivers/pci/dwc/pcie-designware-ep.c
>> @@ -40,6 +40,44 @@ void dw_pcie_ep_reset_bar(struct dw_pcie *pci,
>> enum pci_barno bar)
>>  __dw_pcie_ep_reset_bar(pci, bar, 0);
>>  }
>>
>> +void dw_pcie_ep_find_cap_addr(struct dw_pcie_ep *ep) {
>> +struct dw_pcie *pci = to_dw_pcie_from_ep(ep);
>> +u8 next_ptr, curr_ptr, cap_id;
>> +u16 reg;
>> +
>> +memset(>cap_addr, 0, sizeof(ep->cap_addr));
>> +
>> +reg = dw_pcie_readw_dbi(pci, PCI_STATUS);
>> +if (!(reg & PCI_STATUS_CAP_LIST))
>> +return;
>> +
>> +reg = dw_pcie_readw_dbi(pci, PCI_CAPABILITY_LIST);
>> +next_ptr = (reg & 0x00ff);
>> +if (!next_ptr)
>> +return;
>> +
>> +reg = dw_pcie_readw_dbi(pci, next_ptr);
>> +curr_ptr = next_ptr;
>> +next_ptr = (reg & 0xff00) >> 8;
>> +cap_id = (reg & 0x00ff);
>> +
>> +while (next_ptr && (cap_id <= PCI_CAP_ID_MAX)) {
>> +switch (cap_id) {
>> +case PCI_CAP_ID_MSI:
>> +ep->cap_addr.msi_addr = curr_ptr;
>> +break;
>> +case PCI_CAP_ID_MSIX:
>> +ep->cap_addr.msix_addr = curr_ptr;
>> +break;
>> +}
>> +reg = dw_pcie_readw_dbi(pci, next_ptr);
>> +curr_ptr = next_ptr;
>> +next_ptr = (reg & 0xff00) >> 8;
>> +cap_id = (reg & 0x00ff);
>> +}
>> +}
>> +
>>  static int dw_pcie_ep_write_header(struct pci_epc *epc, u8 func_no,
>> struct pci_epf_header *hdr)
>>  {
>> @@ -241,8 +279,47 @@ static int dw_pcie_ep_set_msi(struct pci_epc *epc,
>> u8 func_no, u8 encode_int)
>>  return 0;
>>  }
>>
>> +static int dw_pcie_ep_get_msix(struct pci_epc *epc, u8 func_no) {
>> +struct dw_pcie_ep *ep = epc_get_drvdata(epc);
>> +struct dw_pcie *pci = to_dw_pcie_from_ep(ep);
>> +u32 val, reg;
>> +
>> +if (ep->cap_addr.msix_addr == 0)
>> +return 0;
>> +
>> +reg = ep->cap_addr.msix_addr + PCI_MSIX_FLAGS;
>> +val = dw_pcie_readw_dbi(pci, reg);
>> +if (!(val & PCI_MSIX_FLAGS_ENABLE))
>> +return -EINVAL;
>> +
>> +val &= PCI_MSIX_FLAGS_QSIZE;
>> +
>> +return val;
>> +}
>> +
>> +static int dw_pcie_ep_set_msix(struct pci_epc *epc, u8 func_no, u16
>> +interrupts) {
>> +struct dw_pcie_ep *ep = epc_get_drvdata(epc);
>> +struct dw_pcie *pci = to_dw_pcie_from_ep(ep);
>> +u32 val, reg;
>> +
>> +if 

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

[Mauro Carvalho Chehab]

Em Thu, 10 May 2018 01:38:38 -0700
Christoph Hellwig  escreveu:

> >   * 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::  
> 
> Independent of any philosophical discussion not allowing a setence to
> end with a single ':' is completely idiotic.  Please fix the tooling
> instead to allow it, as it is very important for being able to just
> write understandable comments.

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

In English, the common case is that a line with ends with a colon is
followed by a list. E. g.

foo:
  - bar1;
  - bar2.

However, in this specific case, it is followed by an ascii artwork. 
The double colon is a notation that tells Sphinx to not parse the
lines at the next block, placing the contents of it inside a literal
block. It is used also when the next lines contain a code example,
in order to avoid parsing things like @, () and * inside the code 
block.

The kernel-doc tool might eventually have some parsing logic that
would replace something to a '::' before sending it to Sphinx.
It could, for example, have a "hint" regex that would expect a
certain sequence of characters to be at the last line, like:

s/ascii\s+artwork.*:/ascii artwork.*::/
or
s/code\s+block.*:/code block.*::/

Then, change the kernel-doc comment to use it, like:

 * with an extra smp_mb() like shown at the following ascii artwork:

but IMHO, this is a lot worse than "::": it would be more intrusive
and more error-prune.

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

[Christoph Hellwig]

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

Independent of any philosophical discussion not allowing a setence to
end with a single ':' is completely idiotic.  Please fix the tooling
instead to allow it, as it is very important for being able to just
write understandable comments.
--
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