Re: [PATCH 04/22] gadget.rst: Enrich its ReST representation and add kernel-doc tag

[Jani Nikula]

On Wed, 29 Mar 2017, Mauro Carvalho Chehab  wrote:
> The pandoc conversion is not perfect. Do handwork in order to:
>
> - add a title to this chapter;
> - use the proper warning and note markups;
> - use kernel-doc to include Kernel header and c files;

Please look at Documentation/sphinx/tmplcvt which takes care of all of
that.

BR,
Jani.

> - remove legacy notes with regards to DocBook;
> - some other minor adjustments to make it better to read in
>   text mode and in html.
>
> Signed-off-by: Mauro Carvalho Chehab 
> ---
>  Documentation/driver-api/usb/gadget.rst | 69 
> +
>  1 file changed, 45 insertions(+), 24 deletions(-)
>
> diff --git a/Documentation/driver-api/usb/gadget.rst 
> b/Documentation/driver-api/usb/gadget.rst
> index 4fd9862f3f21..c4c76ebb51d3 100644
> --- a/Documentation/driver-api/usb/gadget.rst
> +++ b/Documentation/driver-api/usb/gadget.rst
> @@ -1,3 +1,7 @@
> +Linux-USB "Gadget" kernel mode API
> +~~
> +
> +
>  Introduction
>  
>  
> @@ -175,16 +179,12 @@ the gadget, and submitting one or more *struct 
> usb\_request* buffers to
>  transfer data. Understand those four data types, and their operations,
>  and you will understand how this API works.
>  
> -**Note**
> +.. Note::
>  
> -This documentation was prepared using the standard Linux kernel
> -``docproc`` tool, which turns text and in-code comments into SGML
> -DocBook and then into usable formats such as HTML or PDF. Other than
> -the "Chapter 9" data types, most of the significant data types and
> -functions are described here.
> +Other than the "Chapter 9" data types, most of the significant data
> +types and functions are described here.
>  
> -However, docproc does not understand all the C constructs that are
> -used, so some relevant information is likely omitted from what you
> +However, some relevant information is likely omitted from what you
>  are reading. One example of such information is endpoint
>  autoconfiguration. You'll have to read the header file, and use
>  example source code (such as that for "Gadget Zero"), to fully
> @@ -192,10 +192,10 @@ and you will understand how this API works.
>  
>  The part of the API implementing some basic driver capabilities is
>  specific to the version of the Linux kernel that's in use. The 2.6
> -kernel includes a *driver model* framework that has no analogue on
> -earlier kernels; so those parts of the gadget API are not fully
> -portable. (They are implemented on 2.4 kernels, but in a different
> -way.) The driver model state is another part of this API that is
> +and upper kernel versions include a *driver model* framework that has
> +no analogue on earlier kernels; so those parts of the gadget API are
> +not fully portable. (They are implemented on 2.4 kernels, but in a
> +different way.) The driver model state is another part of this API that 
> is
>  ignored by the kerneldoc tools.
>  
>  The core API does not expose every possible hardware feature, only the
> @@ -301,18 +301,19 @@ USB 2.0 Chapter 9 Types and Constants
>  -
>  
>  Gadget drivers rely on common USB structures and constants defined in
> -the  header file, which is standard in Linux 2.6
> -kernels. These are the same types and constants used by host side
> +the :ref:`linux/usb/ch9.h ` header file, which is standard in
> +Linux 2.6+ kernels. These are the same types and constants used by host side
>  drivers (and usbcore).
>  
> -!Iinclude/linux/usb/ch9.h
>  Core Objects and Methods
>  
>  
>  These are declared in , and are used by gadget
>  drivers to interact with USB peripheral controller drivers.
>  
> -!Iinclude/linux/usb/gadget.h
> +.. kernel-doc:: include/linux/usb/gadget.h
> +   :internal:
> +
>  Optional Utilities
>  --
>  
> @@ -320,7 +321,12 @@ The core API is sufficient for writing a USB Gadget 
> Driver, but some
>  optional utilities are provided to simplify common tasks. These
>  utilities include endpoint autoconfiguration.
>  
> -!Edrivers/usb/gadget/usbstring.c !Edrivers/usb/gadget/config.c
> +.. kernel-doc:: drivers/usb/gadget/usbstring.c
> +   :export:
> +
> +.. kernel-doc:: drivers/usb/gadget/config.c
> +   :export:
> +
>  Composite Device Framework
>  --
>  
> @@ -337,7 +343,12 @@ usb\_function*, which packages a user visible role such 
> as "network
>  link" or "mass storage device". Management functions may also exist,
>  such as "Device Firmware Upgrade".
>  
> -!Iinclude/linux/usb/composite.h !Edrivers/usb/gadget/composite.c
> +.. kernel-doc:: include/linux/usb/composite.h
> +   :internal:
> +
> +.. kernel-doc:: drivers/usb/gadget/composite.c
> +   :export:
> +
>  Composite Device Functions
>  --
>  
> @@ -345,11 +356,21 @@ At this writing, a few of the current gadget drivers 

Re: [PATCH 04/22] gadget.rst: Enrich its ReST representation and add kernel-doc tag

[Jani Nikula]

On Thu, 30 Mar 2017, Jani Nikula  wrote:
> On Wed, 29 Mar 2017, Mauro Carvalho Chehab  wrote:
>> The pandoc conversion is not perfect. Do handwork in order to:
>>
>> - add a title to this chapter;
>> - use the proper warning and note markups;
>> - use kernel-doc to include Kernel header and c files;
>
> Please look at Documentation/sphinx/tmplcvt which takes care of all of
> that.

That said, since you've already manually done the work, you might want
to do another conversion using the script, and diff the results to see
if there's something you've perhaps missed. I'm pretty sure nobody's
going to read patch 2 line-by-line...

BR,
Jani.

>
> BR,
> Jani.
>
>> - remove legacy notes with regards to DocBook;
>> - some other minor adjustments to make it better to read in
>>   text mode and in html.
>>
>> Signed-off-by: Mauro Carvalho Chehab 
>> ---
>>  Documentation/driver-api/usb/gadget.rst | 69 
>> +
>>  1 file changed, 45 insertions(+), 24 deletions(-)
>>
>> diff --git a/Documentation/driver-api/usb/gadget.rst 
>> b/Documentation/driver-api/usb/gadget.rst
>> index 4fd9862f3f21..c4c76ebb51d3 100644
>> --- a/Documentation/driver-api/usb/gadget.rst
>> +++ b/Documentation/driver-api/usb/gadget.rst
>> @@ -1,3 +1,7 @@
>> +Linux-USB "Gadget" kernel mode API
>> +~~
>> +
>> +
>>  Introduction
>>  
>>  
>> @@ -175,16 +179,12 @@ the gadget, and submitting one or more *struct 
>> usb\_request* buffers to
>>  transfer data. Understand those four data types, and their operations,
>>  and you will understand how this API works.
>>  
>> -**Note**
>> +.. Note::
>>  
>> -This documentation was prepared using the standard Linux kernel
>> -``docproc`` tool, which turns text and in-code comments into SGML
>> -DocBook and then into usable formats such as HTML or PDF. Other than
>> -the "Chapter 9" data types, most of the significant data types and
>> -functions are described here.
>> +Other than the "Chapter 9" data types, most of the significant data
>> +types and functions are described here.
>>  
>> -However, docproc does not understand all the C constructs that are
>> -used, so some relevant information is likely omitted from what you
>> +However, some relevant information is likely omitted from what you
>>  are reading. One example of such information is endpoint
>>  autoconfiguration. You'll have to read the header file, and use
>>  example source code (such as that for "Gadget Zero"), to fully
>> @@ -192,10 +192,10 @@ and you will understand how this API works.
>>  
>>  The part of the API implementing some basic driver capabilities is
>>  specific to the version of the Linux kernel that's in use. The 2.6
>> -kernel includes a *driver model* framework that has no analogue on
>> -earlier kernels; so those parts of the gadget API are not fully
>> -portable. (They are implemented on 2.4 kernels, but in a different
>> -way.) The driver model state is another part of this API that is
>> +and upper kernel versions include a *driver model* framework that has
>> +no analogue on earlier kernels; so those parts of the gadget API are
>> +not fully portable. (They are implemented on 2.4 kernels, but in a
>> +different way.) The driver model state is another part of this API that 
>> is
>>  ignored by the kerneldoc tools.
>>  
>>  The core API does not expose every possible hardware feature, only the
>> @@ -301,18 +301,19 @@ USB 2.0 Chapter 9 Types and Constants
>>  -
>>  
>>  Gadget drivers rely on common USB structures and constants defined in
>> -the  header file, which is standard in Linux 2.6
>> -kernels. These are the same types and constants used by host side
>> +the :ref:`linux/usb/ch9.h ` header file, which is standard in
>> +Linux 2.6+ kernels. These are the same types and constants used by host side
>>  drivers (and usbcore).
>>  
>> -!Iinclude/linux/usb/ch9.h
>>  Core Objects and Methods
>>  
>>  
>>  These are declared in , and are used by gadget
>>  drivers to interact with USB peripheral controller drivers.
>>  
>> -!Iinclude/linux/usb/gadget.h
>> +.. kernel-doc:: include/linux/usb/gadget.h
>> +   :internal:
>> +
>>  Optional Utilities
>>  --
>>  
>> @@ -320,7 +321,12 @@ The core API is sufficient for writing a USB Gadget 
>> Driver, but some
>>  optional utilities are provided to simplify common tasks. These
>>  utilities include endpoint autoconfiguration.
>>  
>> -!Edrivers/usb/gadget/usbstring.c !Edrivers/usb/gadget/config.c
>> +.. kernel-doc:: drivers/usb/gadget/usbstring.c
>> +   :export:
>> +
>> +.. kernel-doc:: drivers/usb/gadget/config.c
>> +   :export:
>> +
>>  Composite Device Framework
>>  --
>>  
>> @@ -337,7 +343,12 @@ usb\_function*, which packages a user visible role such 
>> as "network
>>  link" or "mass storage device". Man

Re: [PATCH v12 00/10] mux controller abstraction and iio/i2c muxes

[Peter Rosin]

On 2017-03-27 16:21, Peter Rosin wrote:
> Hi Greg!
> 
> Please apply.
>

*snip snip*

> v10 -> v11 changes
> - added a new patch (12) with a fix for messed up error path reported
>   by Paul Gortmaker.

Oops, should be Dan Carpenter. Sorry about that...

And, I forgot to high-light this:

> v4 -> v5 changes
> - driver for Analog Devices ADG792A/G, literally the first mux chip
>   I found on the Internet with an i2c interface (that was not a
>   dedicated i2c multiplexer like PCA9547) which I used to verify
>   that the abstractions in the mux core are up to the task. Untested,
>   just proof of concept that at least looks pretty and compiles...

Maybe the patches related to adg792 (last two patches in v12) should
not be applied? I don't care much either way, your call Greg...

Cheers,
peda

--
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/22] docs-rst: convert usb docbooks to ReST

[Markus Heiser]

Hi Mauro,

Am 29.03.2017 um 20:54 schrieb Mauro Carvalho Chehab :

> As we're moving out of DocBook, let's convert the remaining
> USB docbooks to ReST.
> 
> The transformation itself on this patch is a no-brainer
> conversion using pandoc.

right, its a no-brainer ;-) I'am not very happy with this
conversions, some examples see below.

I recommend to use a more elaborate conversion as starting point,
e.g. from my sphkerneldoc project:

* 
https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/gadget
* 
https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/writing_musb_glue_layer
* 
https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/writing_usb_driver

Since these DocBooks hasn't been changed in the last month, the linked reST
should be up to date.


> +Kernel Mode Gadget API
> +==
> +
> +Gadget drivers declare themselves through a *struct
> +usb\_gadget\_driver*, which is responsible for most parts of enumeration
> +for a *struct usb\_gadget*. The response to a set\_configuration usually
> +involves enabling one or more of the *struct usb\_ep* objects exposed by
> +the gadget, and submitting one or more *struct usb\_request* buffers to

quoting of all underlines is not needed.

> +!Iinclude/linux/usb/composite.h !Edrivers/usb/gadget/composite.c
> +Composite Device Functions
> +--
> +
> +At this writing, a few of the current gadget drivers have been converted
> +to this framework. Near-term plans include converting all of them,
> +except for "gadgetfs".
> +
> +!Edrivers/usb/gadget/function/f\_acm.c
> +!Edrivers/usb/gadget/function/f\_ecm.c
> +!Edrivers/usb/gadget/function/f\_subset.c
> +!Edrivers/usb/gadget/function/f\_obex.c
> +!Edrivers/usb/gadget/function/f\_serial.c
> +Peripheral Controller Drivers
> +=

I guess we miss some documentation here.

-- 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 v12 00/10] mux controller abstraction and iio/i2c muxes

[Greg Kroah-Hartman]

On Thu, Mar 30, 2017 at 09:34:52AM +0200, Peter Rosin wrote:
> On 2017-03-27 16:21, Peter Rosin wrote:
> > Hi Greg!
> > 
> > Please apply.
> >
> 
> *snip snip*
> 
> > v10 -> v11 changes
> > - added a new patch (12) with a fix for messed up error path reported
> >   by Paul Gortmaker.
> 
> Oops, should be Dan Carpenter. Sorry about that...
> 
> And, I forgot to high-light this:
> 
> > v4 -> v5 changes
> > - driver for Analog Devices ADG792A/G, literally the first mux chip
> >   I found on the Internet with an i2c interface (that was not a
> >   dedicated i2c multiplexer like PCA9547) which I used to verify
> >   that the abstractions in the mux core are up to the task. Untested,
> >   just proof of concept that at least looks pretty and compiles...
> 
> Maybe the patches related to adg792 (last two patches in v12) should
> not be applied? I don't care much either way, your call Greg...

Give me a chance to catch up on reviews, your patch series is behind
400+ other emails...

greg k-h
--
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 22/22] usb: document that URB transfer_buffer should be aligned

[Oliver Neukum]

Am Donnerstag, den 30.03.2017, 01:15 +0300 schrieb Laurent Pinchart:
> > +   may also override PAD bytes at the end of the ``transfer_buffer``, up to
> > the
> > +   size of the CPU word.
> 
> "May" is quite weak here. If some host controller drivers require buffers to 
> be aligned, then it's an API requirement, and all buffers must be aligned. 
> I'm 
> not even sure I would mention that some host drivers require it, I think we 
> should just state that the API requires buffers to be aligned.

That effectively changes the API. Many network drivers are written with
the assumption that any contiguous buffer is valid. In fact you could
argue that those drivers are buggy and must use bounce buffers in those
cases.

So we need to include the full story here.

Regards
Oliver

--
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/22] docs-rst: convert usb docbooks to ReST

[Jani Nikula]

On Thu, 30 Mar 2017, Markus Heiser  wrote:
> Hi Mauro,
>
> Am 29.03.2017 um 20:54 schrieb Mauro Carvalho Chehab 
> :
>
>> As we're moving out of DocBook, let's convert the remaining
>> USB docbooks to ReST.
>> 
>> The transformation itself on this patch is a no-brainer
>> conversion using pandoc.
>
> right, its a no-brainer ;-) I'am not very happy with this
> conversions, some examples see below.
>
> I recommend to use a more elaborate conversion as starting point,
> e.g. from my sphkerneldoc project:
>
> * 
> https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/gadget
> * 
> https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/writing_musb_glue_layer
> * 
> https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/writing_usb_driver
>
> Since these DocBooks hasn't been changed in the last month, the linked reST
> should be up to date.

Markus, I know you've done a lot of work on your conversions, and you
like to advocate them, but AFAICT you have never posted the conversions
as patches to the list. Your project isn't a clone of the kernel
tree. It's a pile of .rst files that nobody knows how to produce from
current upstream DocBook .tmpl files. I'm sorry, but this just doesn't
work that way.

At this point I'd just go with what Mauro has. It's here now, as
patches. We've seen from the GPU documentation that polishing the
one-time initial conversion is, after a point, wasted effort. Having the
documentation in rst attracts more attention and contributions, and any
remaining issues will get ironed out in rst.

This is also one reason I'm in favor of just bulk converting the rest of
the .tmpl files using Documentation/sphinx/tmplcvt, get rid of DocBook
and be done with it, and have the crowds focus on rst.


BR,
Jani.


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

Re: [PATCH 04/22] gadget.rst: Enrich its ReST representation and add kernel-doc tag

[Mauro Carvalho Chehab]

Em Thu, 30 Mar 2017 10:01:29 +0300
Jani Nikula  escreveu:

> On Wed, 29 Mar 2017, Mauro Carvalho Chehab  wrote:
> > The pandoc conversion is not perfect. Do handwork in order to:
> >
> > - add a title to this chapter;
> > - use the proper warning and note markups;
> > - use kernel-doc to include Kernel header and c files;  
> 
> Please look at Documentation/sphinx/tmplcvt which takes care of all of
> that.

Ah, didn't know about such script!

Trying it here:

$ Documentation/sphinx/tmplcvt Documentation/DocBook/writing_usb_driver.tmpl 
sed: couldn't open file convert_template.sed: No such file or directory

It would be good to change the script for it to seek for convert_template.sed
at the right place.

So, please consider the following patch.

Regards,
Mauro


[PATCH] tmplcvt: make the tool more robust

Currently, the script just assumes to be called at
Documentation/sphinx/. Change it to work on any directory,
and make it abort if something gets wrong.

Also, be sure that both parameters are specified.

That should avoid troubles like this:

$ Documentation/sphinx/tmplcvt Documentation/DocBook/writing_usb_driver.tmpl
sed: couldn't open file convert_template.sed: No such file or directory

Signed-off-by: Mauro Carvalho Chehab 

diff --git a/Documentation/sphinx/tmplcvt b/Documentation/sphinx/tmplcvt
index 909a73065e0a..31df8eb7feca 100755
--- a/Documentation/sphinx/tmplcvt
+++ b/Documentation/sphinx/tmplcvt
@@ -7,13 +7,22 @@
 # fix \_
 # title line?
 #
+set -eu
+
+if [ "$2" == "" ]; then
+   echo "$0  "
+   exit
+fi
+
+DIR=$(dirname $0)
 
 in=$1
 rst=$2
 tmp=$rst.tmp
 
 cp $in $tmp
-sed --in-place -f convert_template.sed $tmp
+sed --in-place -f $DIR/convert_template.sed $tmp
 pandoc -s -S -f docbook -t rst -o $rst $tmp
-sed --in-place -f post_convert.sed $rst
+sed --in-place -f $DIR/post_convert.sed $rst
 rm $tmp
+echo "book writen to $rst"
--
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 v5 6/9] coresight: add support for CPU debug module

[Suzuki K Poulose]

On 30/03/17 02:03, Leo Yan wrote:

On Wed, Mar 29, 2017 at 03:56:23PM +0100, Mike Leach wrote:

[...]


+   /*
+* Unfortunately the CPU cannot be powered up, so return
+* back and later has no permission to access other
+* registers. For this case, should set 'idle_constraint'
+* to ensure CPU power domain is enabled!
+*/
+   if (!(drvdata->edprsr & EDPRSR_PU)) {
+   pr_err("%s: power up request for CPU%d failed\n",
+   __func__, drvdata->cpu);
+   goto out;
+   }
+
+out_powered_up:
+   debug_os_unlock(drvdata);
+
+   /*
+* At this point the CPU is powered up, so set the no powerdown
+* request bit so we don't lose power and emulate power down.
+*/
+   drvdata->edprsr = readl(drvdata->base + EDPRCR);
+   drvdata->edprsr |= EDPRCR_COREPURQ | EDPRCR_CORENPDRQ;


If we are here the core is already up.  Shouldn't we need to set
EDPRCR_CORENPDRQ only?


Yeah. Will fix.


No - EDPRCR_COREPURQ and EDPRCR_CORENPDRQ have different semantics and purposes

EDPRCR_COREPURQ is in the debug power domain an is tied to an external
debug request that should be an input to the external (to the PE)
system power controller.
The requirement is that the system power controller powers up the core
domain and does not power it down while it remains asserted.

EDPRCR_CORENPDRQ is in the core power domain and thus to the specific
core only. This ensures that any power control software running on
that core should emulate a power down if this is set to one.


I'm curious the exact meaning for "power control software".

Does it mean EDPRCR_CORENPDRQ should be checked by kernel or PSCI
liked code in ARM trusted firmware to avoid to run CPU power off flow?

Or will EDPRCR_CORENPDRQ assert CPU external signal to notify power
controller so power controller emulate a power down?


We cannot know the power control design of the system, so the safe
solution is to set both bits.


Thanks a lot for the suggestion. Will set both bits.


Leo,

Also, it would be good to restore the PRCR register back to the original state
after we read the registers (if we changed them). I am exploring ways to make
use of this feature on demand (e.g, tie it to sysrq-t or sysrq-l) and not just
at panic time. So it would be good to have the state restored to not affect the
normal functioning even after dumping the registers.

PS: I have a small hack to hook this into a sysrq-x at runtime, but on a second 
thought
it is better not to consume the key and rather tie it to something which 
already exist,
as mentioned above.

Thanks
Suzuki



Thanks,
Leo Yan



--
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 v5 4/6] drm: bridge: dw-hdmi: Switch to V4L bus format and encodings

[Neil Armstrong]

Some display pipelines can only provide non-RBG input pixels to the HDMI TX
Controller, this patch takes the pixel format from the plat_data if provided.

Reviewed-by: Jose Abreu 
Signed-off-by: Neil Armstrong 
---
 drivers/gpu/drm/bridge/synopsys/dw-hdmi.c | 326 +-
 include/drm/bridge/dw_hdmi.h  |  63 ++
 2 files changed, 294 insertions(+), 95 deletions(-)

diff --git a/drivers/gpu/drm/bridge/synopsys/dw-hdmi.c 
b/drivers/gpu/drm/bridge/synopsys/dw-hdmi.c
index ff1fae3..16d5fff3 100644
--- a/drivers/gpu/drm/bridge/synopsys/dw-hdmi.c
+++ b/drivers/gpu/drm/bridge/synopsys/dw-hdmi.c
@@ -30,18 +30,15 @@
 #include 
 #include 
 
+#include 
+#include 
+
 #include "dw-hdmi.h"
 #include "dw-hdmi-audio.h"
 
 #define DDC_SEGMENT_ADDR   0x30
 #define HDMI_EDID_LEN  512
 
-#define RGB0
-#define YCBCR444   1
-#define YCBCR422_16BITS2
-#define YCBCR422_8BITS 3
-#define XVYCC444   4
-
 enum hdmi_datamap {
RGB444_8B = 0x01,
RGB444_10B = 0x03,
@@ -95,10 +92,10 @@ struct hdmi_vmode {
 };
 
 struct hdmi_data_info {
-   unsigned int enc_in_format;
-   unsigned int enc_out_format;
-   unsigned int enc_color_depth;
-   unsigned int colorimetry;
+   unsigned int enc_in_bus_format;
+   unsigned int enc_out_bus_format;
+   unsigned int enc_in_encoding;
+   unsigned int enc_out_encoding;
unsigned int pix_repet_factor;
unsigned int hdcp_enable;
struct hdmi_vmode video_mode;
@@ -567,6 +564,92 @@ void dw_hdmi_audio_disable(struct dw_hdmi *hdmi)
 }
 EXPORT_SYMBOL_GPL(dw_hdmi_audio_disable);
 
+static bool hdmi_bus_fmt_is_rgb(unsigned int bus_format)
+{
+   switch (bus_format) {
+   case MEDIA_BUS_FMT_RGB888_1X24:
+   case MEDIA_BUS_FMT_RGB101010_1X30:
+   case MEDIA_BUS_FMT_RGB121212_1X36:
+   case MEDIA_BUS_FMT_RGB161616_1X48:
+   return true;
+
+   default:
+   return false;
+   }
+}
+
+static bool hdmi_bus_fmt_is_yuv444(unsigned int bus_format)
+{
+   switch (bus_format) {
+   case MEDIA_BUS_FMT_YUV8_1X24:
+   case MEDIA_BUS_FMT_YUV10_1X30:
+   case MEDIA_BUS_FMT_YUV12_1X36:
+   case MEDIA_BUS_FMT_YUV16_1X48:
+   return true;
+
+   default:
+   return false;
+   }
+}
+
+static bool hdmi_bus_fmt_is_yuv422(unsigned int bus_format)
+{
+   switch (bus_format) {
+   case MEDIA_BUS_FMT_UYVY8_1X16:
+   case MEDIA_BUS_FMT_UYVY10_1X20:
+   case MEDIA_BUS_FMT_UYVY12_1X24:
+   return true;
+
+   default:
+   return false;
+   }
+}
+
+static bool hdmi_bus_fmt_is_yuv420(unsigned int bus_format)
+{
+   switch (bus_format) {
+   case MEDIA_BUS_FMT_UYYVYY8_0_5X24:
+   case MEDIA_BUS_FMT_UYYVYY10_0_5X30:
+   case MEDIA_BUS_FMT_UYYVYY12_0_5X36:
+   case MEDIA_BUS_FMT_UYYVYY16_0_5X48:
+   return true;
+
+   default:
+   return false;
+   }
+}
+
+static int hdmi_bus_fmt_color_depth(unsigned int bus_format)
+{
+   switch (bus_format) {
+   case MEDIA_BUS_FMT_RGB888_1X24:
+   case MEDIA_BUS_FMT_YUV8_1X24:
+   case MEDIA_BUS_FMT_UYVY8_1X16:
+   case MEDIA_BUS_FMT_UYYVYY8_0_5X24:
+   return 8;
+
+   case MEDIA_BUS_FMT_RGB101010_1X30:
+   case MEDIA_BUS_FMT_YUV10_1X30:
+   case MEDIA_BUS_FMT_UYVY10_1X20:
+   case MEDIA_BUS_FMT_UYYVYY10_0_5X30:
+   return 10;
+
+   case MEDIA_BUS_FMT_RGB121212_1X36:
+   case MEDIA_BUS_FMT_YUV12_1X36:
+   case MEDIA_BUS_FMT_UYVY12_1X24:
+   case MEDIA_BUS_FMT_UYYVYY12_0_5X36:
+   return 12;
+
+   case MEDIA_BUS_FMT_RGB161616_1X48:
+   case MEDIA_BUS_FMT_YUV16_1X48:
+   case MEDIA_BUS_FMT_UYYVYY16_0_5X48:
+   return 16;
+
+   default:
+   return 0;
+   }
+}
+
 /*
  * this submodule is responsible for the video data synchronization.
  * for example, for RGB 4:4:4 input, the data map is defined as
@@ -579,37 +662,49 @@ static void hdmi_video_sample(struct dw_hdmi *hdmi)
int color_format = 0;
u8 val;
 
-   if (hdmi->hdmi_data.enc_in_format == RGB) {
-   if (hdmi->hdmi_data.enc_color_depth == 8)
-   color_format = 0x01;
-   else if (hdmi->hdmi_data.enc_color_depth == 10)
-   color_format = 0x03;
-   else if (hdmi->hdmi_data.enc_color_depth == 12)
-   color_format = 0x05;
-   else if (hdmi->hdmi_data.enc_color_depth == 16)
-   color_format = 0x07;
-   else
-   return;
-   } else if (hdmi->hdmi_data.enc_in_format == YCBCR444) {
-   if (hdmi->hdmi_data.enc_color_depth == 8)
-   color_format = 0x09;
-   else if (hdmi->hdmi_data.enc_color_depth == 10)
-   color_format = 

[PATCH v5 3/6] documentation: media: Add documentation for new RGB and YUV bus formats

[Neil Armstrong]

Add documentation for added Bus Formats to describe RGB and YUV formats used
as input to the Synopsys DesignWare HDMI TX Controller.

Signed-off-by: Neil Armstrong 
---
 Documentation/media/uapi/v4l/subdev-formats.rst | 871 +++-
 1 file changed, 857 insertions(+), 14 deletions(-)

diff --git a/Documentation/media/uapi/v4l/subdev-formats.rst 
b/Documentation/media/uapi/v4l/subdev-formats.rst
index d6152c9..038474d 100644
--- a/Documentation/media/uapi/v4l/subdev-formats.rst
+++ b/Documentation/media/uapi/v4l/subdev-formats.rst
@@ -1258,6 +1258,281 @@ The following tables list existing packed RGB formats.
   - b\ :sub:`2`
   - b\ :sub:`1`
   - b\ :sub:`0`
+* .. _MEDIA-BUS-FMT-RGB101010-1X30:
+
+  - MEDIA_BUS_FMT_RGB101010_1X30
+  - 0x1018
+  -
+  - 0
+  - 0
+  - r\ :sub:`9`
+  - r\ :sub:`8`
+  - r\ :sub:`7`
+  - r\ :sub:`6`
+  - r\ :sub:`5`
+  - r\ :sub:`4`
+  - r\ :sub:`3`
+  - r\ :sub:`2`
+  - r\ :sub:`1`
+  - r\ :sub:`0`
+  - g\ :sub:`9`
+  - g\ :sub:`8`
+  - g\ :sub:`7`
+  - g\ :sub:`6`
+  - g\ :sub:`5`
+  - g\ :sub:`4`
+  - g\ :sub:`3`
+  - g\ :sub:`2`
+  - g\ :sub:`1`
+  - g\ :sub:`0`
+  - b\ :sub:`9`
+  - b\ :sub:`8`
+  - b\ :sub:`7`
+  - b\ :sub:`6`
+  - b\ :sub:`5`
+  - b\ :sub:`4`
+  - b\ :sub:`3`
+  - b\ :sub:`2`
+  - b\ :sub:`1`
+  - b\ :sub:`0`
+
+.. raw:: latex
+
+\endgroup
+
+
+The following table list existing packed 36bit wide RGB formats.
+
+.. tabularcolumns:: 
|p{4.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|
+
+.. _v4l2-mbus-pixelcode-rgb-36:
+
+.. raw:: latex
+
+\begingroup
+\tiny
+\setlength{\tabcolsep}{2pt}
+
+.. flat-table:: 36bit RGB formats
+:header-rows:  2
+:stub-columns: 0
+:widths: 36 7 3 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 
2 2 2 2 2 2 2
+
+* - Identifier
+  - Code
+  -
+  - :cspan:`35` Data organization
+* -
+  -
+  - Bit
+  - 35
+  - 34
+  - 33
+  - 32
+  - 31
+  - 30
+  - 29
+  - 28
+  - 27
+  - 26
+  - 25
+  - 24
+  - 23
+  - 22
+  - 21
+  - 20
+  - 19
+  - 18
+  - 17
+  - 16
+  - 15
+  - 14
+  - 13
+  - 12
+  - 11
+  - 10
+  - 9
+  - 8
+  - 7
+  - 6
+  - 5
+  - 4
+  - 3
+  - 2
+  - 1
+  - 0
+* .. _MEDIA-BUS-FMT-RGB121212-1X36:
+
+  - MEDIA_BUS_FMT_RGB121212_1X36
+  - 0x1019
+  -
+  - r\ :sub:`11`
+  - r\ :sub:`10`
+  - r\ :sub:`9`
+  - r\ :sub:`8`
+  - r\ :sub:`7`
+  - r\ :sub:`6`
+  - r\ :sub:`5`
+  - r\ :sub:`4`
+  - r\ :sub:`3`
+  - r\ :sub:`2`
+  - r\ :sub:`1`
+  - r\ :sub:`0`
+  - g\ :sub:`11`
+  - g\ :sub:`10`
+  - g\ :sub:`9`
+  - g\ :sub:`8`
+  - g\ :sub:`7`
+  - g\ :sub:`6`
+  - g\ :sub:`5`
+  - g\ :sub:`4`
+  - g\ :sub:`3`
+  - g\ :sub:`2`
+  - g\ :sub:`1`
+  - g\ :sub:`0`
+  - b\ :sub:`11`
+  - b\ :sub:`10`
+  - b\ :sub:`9`
+  - b\ :sub:`8`
+  - b\ :sub:`7`
+  - b\ :sub:`6`
+  - b\ :sub:`5`
+  - b\ :sub:`4`
+  - b\ :sub:`3`
+  - b\ :sub:`2`
+  - b\ :sub:`1`
+  - b\ :sub:`0`
+
+.. raw:: latex
+
+\endgroup
+
+
+The following table list existing packed 48bit wide RGB formats.
+
+.. tabularcolumns:: 
|p{4.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|
+
+.. _v4l2-mbus-pixelcode-rgb-48:
+
+.. raw:: latex
+
+\begingroup
+\tiny
+\setlength{\tabcolsep}{2pt}
+
+.. flat-table:: 48bit RGB formats
+:header-rows:  2
+:stub-columns: 0
+:widths: 36 7 3 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 
2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2
+
+* - Identifier
+  - Code
+  -
+  - :cspan:`47` Data organization
+* -
+  -
+  - Bit
+  - 47
+  - 46
+  - 45
+  - 44
+  - 43
+  - 42
+  - 41
+  - 40
+  - 39
+  - 38
+  - 37
+  - 36
+  - 35
+  - 34
+  - 33
+  - 32
+  - 31
+  - 30
+  - 29
+  - 28
+  - 27
+  - 26

[PATCH v5 5/6] drm: bridge: dw-hdmi: Add Documentation on supported input formats

[Neil Armstrong]

This patch adds a new DRM documentation entry and links to the input
format table added in the dw_hdmi header.

Signed-off-by: Neil Armstrong 
---
 Documentation/gpu/bridge/dw-hdmi.rst | 15 +++
 Documentation/gpu/index.rst  |  1 +
 2 files changed, 16 insertions(+)
 create mode 100644 Documentation/gpu/bridge/dw-hdmi.rst

diff --git a/Documentation/gpu/bridge/dw-hdmi.rst 
b/Documentation/gpu/bridge/dw-hdmi.rst
new file mode 100644
index 000..486faad
--- /dev/null
+++ b/Documentation/gpu/bridge/dw-hdmi.rst
@@ -0,0 +1,15 @@
+===
+ drm/bridge/dw-hdmi Synopsys DesignWare HDMI Controller
+===
+
+Synopsys DesignWare HDMI Controller
+===
+
+This section covers everything related to the Synopsys DesignWare HDMI
+Controller implemented as a DRM bridge.
+
+Supported Input Formats and Encodings
+-
+
+.. kernel-doc:: include/drm/bridge/dw_hdmi.h
+   :doc: Supported input formats and encodings
diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst
index e998ee0..d81c6ff 100644
--- a/Documentation/gpu/index.rst
+++ b/Documentation/gpu/index.rst
@@ -15,6 +15,7 @@ Linux GPU Driver Developer's Guide
vc4
vga-switcheroo
vgaarbiter
+   bridge/dw-hdmi
todo
 
 .. only::  subproject and html
-- 
1.9.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

[PATCH v5 6/6] drm: bridge: dw-hdmi: Move HPD handling to PHY operations

[Neil Armstrong]

The HDMI TX controller support HPD and RXSENSE signaling from the PHY
via it's STAT0 PHY interface, but some vendor PHYs can manage these
signals independently from the controller, thus these STAT0 handling
should be moved to PHY specific operations and become optional.

The existing STAT0 HPD and RXSENSE handling code is refactored into
a supplementaty set of default PHY operations that are used automatically
when the platform glue doesn't provide its own operations.

Reviewed-by: Jose Abreu 
Signed-off-by: Neil Armstrong 
---
 drivers/gpu/drm/bridge/synopsys/dw-hdmi.c | 135 ++
 include/drm/bridge/dw_hdmi.h  |   5 ++
 2 files changed, 86 insertions(+), 54 deletions(-)

diff --git a/drivers/gpu/drm/bridge/synopsys/dw-hdmi.c 
b/drivers/gpu/drm/bridge/synopsys/dw-hdmi.c
index 16d5fff3..84cc949 100644
--- a/drivers/gpu/drm/bridge/synopsys/dw-hdmi.c
+++ b/drivers/gpu/drm/bridge/synopsys/dw-hdmi.c
@@ -1229,10 +1229,46 @@ static enum drm_connector_status 
dw_hdmi_phy_read_hpd(struct dw_hdmi *hdmi,
connector_status_connected : connector_status_disconnected;
 }
 
+static void dw_hdmi_phy_update_hpd(struct dw_hdmi *hdmi, void *data,
+  bool force, bool disabled, bool rxsense)
+{
+   u8 old_mask = hdmi->phy_mask;
+
+   if (force || disabled || !rxsense)
+   hdmi->phy_mask |= HDMI_PHY_RX_SENSE;
+   else
+   hdmi->phy_mask &= ~HDMI_PHY_RX_SENSE;
+
+   if (old_mask != hdmi->phy_mask)
+   hdmi_writeb(hdmi, hdmi->phy_mask, HDMI_PHY_MASK0);
+}
+
+static void dw_hdmi_phy_setup_hpd(struct dw_hdmi *hdmi, void *data)
+{
+   /*
+* Configure the PHY RX SENSE and HPD interrupts polarities and clear
+* any pending interrupt.
+*/
+   hdmi_writeb(hdmi, HDMI_PHY_HPD | HDMI_PHY_RX_SENSE, HDMI_PHY_POL0);
+   hdmi_writeb(hdmi, HDMI_IH_PHY_STAT0_HPD | HDMI_IH_PHY_STAT0_RX_SENSE,
+   HDMI_IH_PHY_STAT0);
+
+   /* Enable cable hot plug irq. */
+   hdmi_writeb(hdmi, hdmi->phy_mask, HDMI_PHY_MASK0);
+
+   /* Clear and unmute interrupts. */
+   hdmi_writeb(hdmi, HDMI_IH_PHY_STAT0_HPD | HDMI_IH_PHY_STAT0_RX_SENSE,
+   HDMI_IH_PHY_STAT0);
+   hdmi_writeb(hdmi, ~(HDMI_IH_PHY_STAT0_HPD | HDMI_IH_PHY_STAT0_RX_SENSE),
+   HDMI_IH_MUTE_PHY_STAT0);
+}
+
 static const struct dw_hdmi_phy_ops dw_hdmi_synopsys_phy_ops = {
.init = dw_hdmi_phy_init,
.disable = dw_hdmi_phy_disable,
.read_hpd = dw_hdmi_phy_read_hpd,
+   .update_hpd = dw_hdmi_phy_update_hpd,
+   .setup_hpd = dw_hdmi_phy_setup_hpd,
 };
 
 /* 
-
@@ -1808,35 +1844,10 @@ static void dw_hdmi_update_power(struct dw_hdmi *hdmi)
  */
 static void dw_hdmi_update_phy_mask(struct dw_hdmi *hdmi)
 {
-   u8 old_mask = hdmi->phy_mask;
-
-   if (hdmi->force || hdmi->disabled || !hdmi->rxsense)
-   hdmi->phy_mask |= HDMI_PHY_RX_SENSE;
-   else
-   hdmi->phy_mask &= ~HDMI_PHY_RX_SENSE;
-
-   if (old_mask != hdmi->phy_mask)
-   hdmi_writeb(hdmi, hdmi->phy_mask, HDMI_PHY_MASK0);
-}
-
-static void dw_hdmi_phy_setup_hpd(struct dw_hdmi *hdmi)
-{
-   /*
-* Configure the PHY RX SENSE and HPD interrupts polarities and clear
-* any pending interrupt.
-*/
-   hdmi_writeb(hdmi, HDMI_PHY_HPD | HDMI_PHY_RX_SENSE, HDMI_PHY_POL0);
-   hdmi_writeb(hdmi, HDMI_IH_PHY_STAT0_HPD | HDMI_IH_PHY_STAT0_RX_SENSE,
-   HDMI_IH_PHY_STAT0);
-
-   /* Enable cable hot plug irq. */
-   hdmi_writeb(hdmi, hdmi->phy_mask, HDMI_PHY_MASK0);
-
-   /* Clear and unmute interrupts. */
-   hdmi_writeb(hdmi, HDMI_IH_PHY_STAT0_HPD | HDMI_IH_PHY_STAT0_RX_SENSE,
-   HDMI_IH_PHY_STAT0);
-   hdmi_writeb(hdmi, ~(HDMI_IH_PHY_STAT0_HPD | HDMI_IH_PHY_STAT0_RX_SENSE),
-   HDMI_IH_MUTE_PHY_STAT0);
+   if (hdmi->phy.ops->update_hpd)
+   hdmi->phy.ops->update_hpd(hdmi, hdmi->phy.data,
+ hdmi->force, hdmi->disabled,
+ hdmi->rxsense);
 }
 
 static enum drm_connector_status
@@ -2028,6 +2039,41 @@ static irqreturn_t dw_hdmi_hardirq(int irq, void *dev_id)
return ret;
 }
 
+void __dw_hdmi_setup_rx_sense(struct dw_hdmi *hdmi, bool hpd, bool rx_sense)
+{
+   mutex_lock(&hdmi->mutex);
+
+   if (!hdmi->force) {
+   /*
+* If the RX sense status indicates we're disconnected,
+* clear the software rxsense status.
+*/
+   if (!rx_sense)
+   hdmi->rxsense = false;
+
+   /*
+* Only set the software rxsense status when both
+* rxsense and hpd indicates we're connected.
+* This avoids what seems to be bad behaviour in
+  

[PATCH v5 0/6] drm: bridge: dw-hdmi: Add support for Custom PHYs

[Neil Armstrong]

The Amlogic GX SoCs implements a Synopsys DesignWare HDMI TX Controller
in combination with a very custom PHY.

Thanks to Laurent Pinchart's changes, the HW report the following :
 Detected HDMI TX controller v2.01a with HDCP (meson_dw_hdmi_phy)

The following differs from common PHY integration as managed in the current
driver :
 - Amlogic PHY is not configured through the internal I2C link
 - Amlogic PHY do not use the ENTMDS, SVSRET, PDDQ, ... signals from the 
controller
 - Amlogic PHY do not export HPD ands RxSense signals to the controller

And finally, concerning the controller integration :
 - the Controller registers are not flat memory-mapped, and uses an
addr+read/write register pair to write all registers.
 - Inputs only YUV444 pixel data

Most of these uses case are implemented in Laurent Pinchart v5.1 patchset merged
in drm-misc-next branch.

This is why the following patchset implements :
 - Configure the Input format from the plat_data
 - Add PHY callback to handle HPD and RxSense out of the dw-hdmi driver

To implement the input format handling, the Synopsys HDMIT TX Controller input
V4L bus formats are used and missing formats + documentation are added.

This patchset makes the Amlogic GX SoCs HDMI output successfully work, and is
also tested on the RK3288 ACT8846 EVB Board.

Changes since v4 at [5] :
 - Rebased on drm-misc-next at bd283d2f66c2
 - Fix 4:2:0 bus formats naming
 - Renamed function fd_registered to i2c_init in dw-hdmi.c

Changes since v3 at [4] :
 - Fix 4:2:0 bus formats naming
 - Add separate 36bit and 48bit tables for bus formats documentation
 - Added 4:2:0 bus config in hdmi_video_sample
 - Moved dw_hdmi documentation in a "bridge" subdir
 - Rebase on drm-misc-next at 62c58af32c93

Changes since v2 at [3] :
 - Rebase on laurent patch "Extract PHY interrupt setup to a function"
 - Reduce phy operations
 - Switch the V4L bus formats and encodings instead of custom enum

Changes since v1 at [2] :
 - Drop patches submitted by laurent

Changes since RFC at [1] :
 - Regmap fixup for 4bytes register access, tested on RK3288 SoC
 - Move phy callbacks to phy_ops and move Synopsys PHY calls into default ops
 - Move HDMI link data into shared header
 - Move Pixel Encoding enum to shared header

[1] 
http://lkml.kernel.org/r/1484656294-6140-1-git-send-email-narmstr...@baylibre.com
[2] 
http://lkml.kernel.org/r/1485774318-21916-1-git-send-email-narmstr...@baylibre.com
[3] 
http://lkml.kernel.org/r/1488468572-31971-1-git-send-email-narmstr...@baylibre.com
[4] 
http://lkml.kernel.org/r/1488904944-14285-1-git-send-email-narmstr...@baylibre.com
[5] 
http://lkml.kernel.org/r/1490109161-20529-1-git-send-email-narmstr...@baylibre.com

Laurent Pinchart (1):
  drm: bridge: dw-hdmi: Extract PHY interrupt setup to a function

Neil Armstrong (5):
  media: uapi: Add RGB and YUV bus formats for Synopsys HDMI TX
Controller
  documentation: media: Add documentation for new RGB and YUV bus
formats
  drm: bridge: dw-hdmi: Switch to V4L bus format and encodings
  drm: bridge: dw-hdmi: Add Documentation on supported input formats
  drm: bridge: dw-hdmi: Move HPD handling to PHY operations

 Documentation/gpu/bridge/dw-hdmi.rst|  15 +
 Documentation/gpu/index.rst |   1 +
 Documentation/media/uapi/v4l/subdev-formats.rst | 871 +++-
 drivers/gpu/drm/bridge/synopsys/dw-hdmi.c   | 470 -
 include/drm/bridge/dw_hdmi.h|  68 ++
 include/uapi/linux/media-bus-format.h   |  13 +-
 6 files changed, 1266 insertions(+), 172 deletions(-)
 create mode 100644 Documentation/gpu/bridge/dw-hdmi.rst

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

Re: [PATCH 02/22] docs-rst: convert usb docbooks to ReST

[Markus Heiser]

Am 30.03.2017 um 10:21 schrieb Jani Nikula :

> On Thu, 30 Mar 2017, Markus Heiser  wrote:
>> Hi Mauro,
>> 
>> Am 29.03.2017 um 20:54 schrieb Mauro Carvalho Chehab 
>> :
>> 
>>> As we're moving out of DocBook, let's convert the remaining
>>> USB docbooks to ReST.
>>> 
>>> The transformation itself on this patch is a no-brainer
>>> conversion using pandoc.
>> 
>> right, its a no-brainer ;-) I'am not very happy with this
>> conversions, some examples see below.
>> 
>> I recommend to use a more elaborate conversion as starting point,
>> e.g. from my sphkerneldoc project:
>> 
>> * 
>> https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/gadget
>> * 
>> https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/writing_musb_glue_layer
>> * 
>> https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/writing_usb_driver
>> 
>> Since these DocBooks hasn't been changed in the last month, the linked reST
>> should be up to date.
> 
> Markus, I know you've done a lot of work on your conversions, and you
> like to advocate them, but AFAICT you have never posted the conversions
> as patches to the list. Your project isn't a clone of the kernel
> tree. It's a pile of .rst files that nobody knows how to produce from
> current upstream DocBook .tmpl files. I'm sorry, but this just doesn't
> work that way.

The conversion is done with the dbxml2rst tool:

  https://github.com/return42/dbxml2rst

But you are right, the links I send are decoupled from kernel. It is
a 5 month old snapshot of a DocBook to reST conversion (now updated,
with no affect to the linked files, since they have not been patched
in the meantime) ...

> At this point I'd just go with what Mauro has. It's here now, as
> patches. We've seen from the GPU documentation that polishing the
> one-time initial conversion is, after a point, wasted effort. Having the
> documentation in rst attracts more attention and contributions, and any
> remaining issues will get ironed out in rst.

I totally agree with you (I have never said something different)

> This is also one reason I'm in favor of just bulk converting the rest of
> the .tmpl files using Documentation/sphinx/tmplcvt, get rid of DocBook
> and be done with it, and have the crowds focus on rst.

I also agree with that. The tmplcvt script is good enough for this task,
the dbxml2rst tool is more elaborate.

If Jonathan also likes to have a bulk conversion of the rest DocBooks,
we can use tmplcvt or even dbxml2rst for this task. Everything under

  
https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated

is just a "make dbxm2rst", I can update every time and if a bulk conversion
is the way ... I can send such patches or you send a tmplcvt conversion.

@Jon: what do you think about a bulk conversion?

 -- 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 04/22] gadget.rst: Enrich its ReST representation and add kernel-doc tag

[Mauro Carvalho Chehab]

Em Thu, 30 Mar 2017 10:04:32 +0300
Jani Nikula  escreveu:

> On Thu, 30 Mar 2017, Jani Nikula  wrote:
> > On Wed, 29 Mar 2017, Mauro Carvalho Chehab  
> > wrote:  
> >> The pandoc conversion is not perfect. Do handwork in order to:
> >>
> >> - add a title to this chapter;
> >> - use the proper warning and note markups;
> >> - use kernel-doc to include Kernel header and c files;  
> >
> > Please look at Documentation/sphinx/tmplcvt which takes care of all of
> > that.  
> 
> That said, since you've already manually done the work, you might want
> to do another conversion using the script, and diff the results to see
> if there's something you've perhaps missed. I'm pretty sure nobody's
> going to read patch 2 line-by-line...

Done. The only thing left was the original docbook title and author
information.

The diff also showed that I was a little lazy manually adjust the
gadget.rst document ;) The enclosed patch should fix those issues.

I'll likely fold it with other patches when sending a version 2.

Regards,
Mauro

[PATCH] docs-rst: improve docbook-converted documents

The output of Documentation/sphinx/tmplcvt showed that a few
adjustments could be done in order to improve the output of
the two files that were converted from docbook:

- Use the original title from docbook;
- Add author info;
- Add C references for source code xrefs;
- Use monospaced fonts to be consistent with other docs.

Signed-off-by: Mauro Carvalho Chehab 

diff --git a/Documentation/driver-api/usb/gadget.rst 
b/Documentation/driver-api/usb/gadget.rst
index 0488b89de21c..4b02c61a389d 100644
--- a/Documentation/driver-api/usb/gadget.rst
+++ b/Documentation/driver-api/usb/gadget.rst
@@ -1,6 +1,9 @@
-Linux-USB "Gadget" kernel mode API
-~~
+
+USB Gadget API for Linux
+
 
+:Author: David Brownell
+:Date:   20 August 2004
 
 Introduction
 
@@ -35,7 +38,7 @@ address a number of important problems, including:
resources.
 
 Most Linux developers will not be able to use this API, since they have
-USB "host" hardware in a PC, workstation, or server. Linux users with
+USB ``host`` hardware in a PC, workstation, or server. Linux users with
 embedded systems are more likely to have USB peripheral hardware. To
 distinguish drivers running inside such hardware from the more familiar
 Linux "USB device drivers", which are host side proxies for the real USB
@@ -61,7 +64,7 @@ Structure of Gadget Drivers
 
 A system running inside a USB peripheral normally has at least three
 layers inside the kernel to handle USB protocol processing, and may have
-additional layers in user space code. The "gadget" API is used by the
+additional layers in user space code. The ``gadget`` API is used by the
 middle layer to interact with the lowest level (which directly handles
 hardware).
 
@@ -140,13 +143,13 @@ In Linux, from the bottom up, these layers are:
 *Additional Layers*
 Other layers may exist. These could include kernel layers, such as
 network protocol stacks, as well as user mode applications building
-on standard POSIX system call APIs such as *open()*, *close()*,
-*read()* and *write()*. On newer systems, POSIX Async I/O calls may
+on standard POSIX system call APIs such as ``open()``, ``close()``,
+``read()`` and ``write()``. On newer systems, POSIX Async I/O calls may
 be an option. Such user mode code will not necessarily be subject to
 the GNU General Public License (GPL).
 
 OTG-capable systems will also need to include a standard Linux-USB host
-side stack, with *usbcore*, one or more *Host Controller Drivers*
+side stack, with ``usbcore``, one or more *Host Controller Drivers*
 (HCDs), *USB Device Drivers* to support the OTG "Targeted Peripheral
 List", and so forth. There will also be an *OTG Controller Driver*,
 which is visible to gadget and device driver developers only indirectly.
@@ -171,11 +174,11 @@ combined, to implement composite devices.
 Kernel Mode Gadget API
 ==
 
-Gadget drivers declare themselves through a *struct
-usb\_gadget\_driver*, which is responsible for most parts of enumeration
-for a *struct usb\_gadget*. The response to a set\_configuration usually
-involves enabling one or more of the *struct usb\_ep* objects exposed by
-the gadget, and submitting one or more *struct usb\_request* buffers to
+Gadget drivers declare themselves through a struct
+:c:type:`usb_gadget_driver`, which is responsible for most parts of enumeration
+for a struct :c:type:`usb_gadget`. The response to a set_configuration usually
+involves enabling one or more of the struct :c:type:`usb_ep` objects exposed by
+the gadget, and submitting one or more struct :c:type:`usb_request` buffers to
 transfer data. Understand those four data types, and their operations,
 and you will understand how this API works.
 
@@ -239,28 +242,28 @@ needs to handle some differences. Use the API like this:
 1. Register a driver f

Re: [PATCH 22/22] usb: document that URB transfer_buffer should be aligned

[Laurent Pinchart]

Hi Oliver,

On Thursday 30 Mar 2017 10:11:31 Oliver Neukum wrote:
> Am Donnerstag, den 30.03.2017, 01:15 +0300 schrieb Laurent Pinchart:
> > > +   may also override PAD bytes at the end of the ``transfer_buffer``,
> > > up to the
> > > +   size of the CPU word.
> > 
> > "May" is quite weak here. If some host controller drivers require buffers
> > to be aligned, then it's an API requirement, and all buffers must be
> > aligned. I'm not even sure I would mention that some host drivers require
> > it, I think we should just state that the API requires buffers to be
> > aligned.
> 
> That effectively changes the API. Many network drivers are written with
> the assumption that any contiguous buffer is valid. In fact you could
> argue that those drivers are buggy and must use bounce buffers in those
> cases.
> 
> So we need to include the full story here.

I personally don't care much about whose side is responsible for handling the 
alignment constraints, but I want it to be documented before "fixing" any USB 
driver.

-- 
Regards,

Laurent Pinchart

--
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 22/22] usb: document that URB transfer_buffer should be aligned

[Laurent Pinchart]

Hi Mauro,

On Wednesday 29 Mar 2017 22:06:33 Mauro Carvalho Chehab wrote:
> Em Thu, 30 Mar 2017 01:15:27 +0300 Laurent Pinchart escreveu:
> > On Wednesday 29 Mar 2017 15:54:21 Mauro Carvalho Chehab wrote:
> > > Several host controllers, commonly found on ARM, like dwc2,
> > > require buffers that are CPU-word aligned for they to work.
> > > 
> > > Failing to do that will cause random troubles at the caller
> > > drivers, causing them to fail.
> > > 
> > > Document it.
> > > 
> > > Signed-off-by: Mauro Carvalho Chehab 
> > > ---
> > > 
> > >  Documentation/driver-api/usb/URB.rst | 18 ++
> > >  drivers/usb/core/message.c   | 15 +++
> > >  include/linux/usb.h  | 18 ++
> > >  3 files changed, 51 insertions(+)
> > > 
> > > diff --git a/Documentation/driver-api/usb/URB.rst
> > > b/Documentation/driver-api/usb/URB.rst index d9ea6a3996e7..b83b557e9891
> > > 100644
> > > --- a/Documentation/driver-api/usb/URB.rst
> > > +++ b/Documentation/driver-api/usb/URB.rst
> > > @@ -274,6 +274,24 @@ If you specify your own start frame, make sure it's
> > > several frames in advance of the current frame.  You might want this
> > > model
> > > if you're synchronizing ISO data with some other event stream.
> > > 
> > > +.. note::
> > > +
> > > +   Several host drivers require that the ``transfer_buffer`` to be
> > > aligned
> > > +   with the CPU word size (e. g. DWORD for 32 bits, QDWORD for 64
> > > bits).
> > 
> > Is it the CPU word size or the DMA transfer size ? I assume the latter,
> > and I wouldn't be surprised if the alignment requirement was 32-bit on at
> > least some of the 64-bit platforms.
> 
> Yeah, it is actually the DMA transfer size. Yet, worse case scenario is that
> the DMA transfer size to be 64 bits on 64 bits CPU.
> 
> > > +   It is up to USB drivers should ensure that they'll only pass buffers
> > > +   with such alignments.
> > > +
> > > +   Please also notice that, due to such restriction, the host driver
> > 
> > s/notice/note/ (and below as well) ?
> 
> OK.
> 
> > > +   may also override PAD bytes at the end of the ``transfer_buffer``,
> > > up to the
> > > +   size of the CPU word.
> > 
> > "May" is quite weak here. If some host controller drivers require buffers
> > to be aligned, then it's an API requirement, and all buffers must be
> > aligned. I'm not even sure I would mention that some host drivers require
> > it, I think we should just state that the API requires buffers to be
> > aligned.
> 
> What I'm trying to say here is that, on a 32-bits system, if the driver do
> a USB_DIR_IN transfer using some code similar to:
> 
>   size = 4;
>   buffer = kmalloc(size, GFP_KERNEL);
> 
>   usb_control_msg(udev, pipe, req, type, val, idx, buffer + 2, 2, 
timeout);
>   usb_control_msg(udev, pipe, req, type, val, idx, buffer, size, 
timeout);
> 
> Drivers like dwc2 will mess with the buffer.
> 
> The first transfer will actually work, due to a workaround inside the
> driver that will create a temporary DWORD-aligned buffer, avoiding it
> to go past the buffer.
> 
> However, the second transfer will destroy the data received from the
> first usb_control_msg(), as it will write 4 bytes at the buffer.
> 
> Not all drivers would do that, though.
> 
> Please notice that, as kmalloc will always return a CPU-aligned buffer,
> if the client do something like:
> 
>   size = 2;
>   buffer = kmalloc(size, GFP_KERNEL);
> 
>   usb_control_msg(udev, pipe, req, type, val, idx, buffer, 2, timeout);
> 
> What happens there is that the DMA engine will still write 4 bytes at
> the buffer, but the 2 bytes that go past the end of buffer will be
> written on a memory that will never be used.

I understand that, but stating that host controller drivers "may" do this 
won't help much. If they *may*, all USB device drivers *must* align buffers 
correctly. That's the part that needs to be documented. Let's not confuse 
developers by only stating that something may happened, let's be clear and 
tell what they must do.

> > > +   Please notice that ancillary routines that transfer URBs, like
> > > +   usb_control_msg() also have such restriction.
> > > +
> > > +   Such word alignment condition is normally ensured if the buffer is
> > > +   allocated with kmalloc(), but this may not be the case if the driver
> > > +   allocates a bigger buffer and point to a random place inside it.
> > > +
> > > 
> > >  How to start interrupt (INT) transfers?
> > >  ===
> > > 
> > > diff --git a/drivers/usb/core/message.c b/drivers/usb/core/message.c
> > > index 4c38ea41ae96..1662a4446475 100644
> > > --- a/drivers/usb/core/message.c
> > > +++ b/drivers/usb/core/message.c
> > > @@ -128,6 +128,21 @@ static int usb_internal_control_msg(struct
> > > usb_device
> > > *usb_dev, * make sure your disconnect() method can wait for it to
> > > complete.
> > > Since you * don't have a handle on the URB used, you can't cancel the
> >

Re: [PATCH 02/22] docs-rst: convert usb docbooks to ReST

[Mauro Carvalho Chehab]

Em Thu, 30 Mar 2017 11:20:14 +0200
Markus Heiser  escreveu:

> Am 30.03.2017 um 10:21 schrieb Jani Nikula :
> 
> > On Thu, 30 Mar 2017, Markus Heiser  wrote:  
> >> Hi Mauro,
> >> 
> >> Am 29.03.2017 um 20:54 schrieb Mauro Carvalho Chehab 
> >> :
> >>   
> >>> As we're moving out of DocBook, let's convert the remaining
> >>> USB docbooks to ReST.
> >>> 
> >>> The transformation itself on this patch is a no-brainer
> >>> conversion using pandoc.  
> >> 
> >> right, its a no-brainer ;-) I'am not very happy with this
> >> conversions, some examples see below.
> >> 
> >> I recommend to use a more elaborate conversion as starting point,
> >> e.g. from my sphkerneldoc project:
> >> 
> >> * 
> >> https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/gadget
> >> * 
> >> https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/writing_musb_glue_layer
> >> * 
> >> https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/writing_usb_driver
> >> 
> >> Since these DocBooks hasn't been changed in the last month, the linked reST
> >> should be up to date.  
> > 
> > Markus, I know you've done a lot of work on your conversions, and you
> > like to advocate them, but AFAICT you have never posted the conversions
> > as patches to the list. Your project isn't a clone of the kernel
> > tree. It's a pile of .rst files that nobody knows how to produce from
> > current upstream DocBook .tmpl files. I'm sorry, but this just doesn't
> > work that way.  
> 
> The conversion is done with the dbxml2rst tool:
> 
>   https://github.com/return42/dbxml2rst
> 
> But you are right, the links I send are decoupled from kernel. It is
> a 5 month old snapshot of a DocBook to reST conversion (now updated,
> with no affect to the linked files, since they have not been patched
> in the meantime) ...
> 
> > At this point I'd just go with what Mauro has. It's here now, as
> > patches. We've seen from the GPU documentation that polishing the
> > one-time initial conversion is, after a point, wasted effort. Having the
> > documentation in rst attracts more attention and contributions, and any
> > remaining issues will get ironed out in rst.  
> 
> I totally agree with you (I have never said something different)
> 
> > This is also one reason I'm in favor of just bulk converting the rest of
> > the .tmpl files using Documentation/sphinx/tmplcvt, get rid of DocBook
> > and be done with it, and have the crowds focus on rst.  
> 
> I also agree with that. The tmplcvt script is good enough for this task,
> the dbxml2rst tool is more elaborate.

I like the idea of a bulk conversion. My personal preference here is to
use the tmplcvt for such task, at least for simple books like the ones
I converted from USB.

The advantage is that it places everything on a single rst file, with,
IMHO, works best for books that aren't too complex.

Of course, it doesn't hurt to compare the end result with dbxml2rst
and see if something could be improved.

> 
> If Jonathan also likes to have a bulk conversion of the rest DocBooks,
> we can use tmplcvt or even dbxml2rst for this task. Everything under
> 
>   
> https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated
> 
> is just a "make dbxm2rst", I can update every time and if a bulk conversion
> is the way ... I can send such patches or you send a tmplcvt conversion.
> 
> @Jon: what do you think about a bulk conversion?
> 
>  -- Markus --
>   


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 22/22] usb: document that URB transfer_buffer should be aligned

[Mauro Carvalho Chehab]

Em Thu, 30 Mar 2017 12:34:32 +0300
Laurent Pinchart  escreveu:

> Hi Oliver,
> 
> On Thursday 30 Mar 2017 10:11:31 Oliver Neukum wrote:
> > Am Donnerstag, den 30.03.2017, 01:15 +0300 schrieb Laurent Pinchart:  
> > > > +   may also override PAD bytes at the end of the ``transfer_buffer``,
> > > > up to the
> > > > +   size of the CPU word.  
> > > 
> > > "May" is quite weak here. If some host controller drivers require buffers
> > > to be aligned, then it's an API requirement, and all buffers must be
> > > aligned. I'm not even sure I would mention that some host drivers require
> > > it, I think we should just state that the API requires buffers to be
> > > aligned.  
> > 
> > That effectively changes the API. Many network drivers are written with
> > the assumption that any contiguous buffer is valid. In fact you could
> > argue that those drivers are buggy and must use bounce buffers in those
> > cases.

Blaming the dwc2 driver was my first approach, but such patch got nacked ;)

Btw, the dwc2 driver has a routine that creates a temporary buffer if the
buffer pointer is not DWORD aligned. My first approach were to add
a logic there to also use the temporary buffer if the buffer size is
not DWORD aligned:
https://patchwork.linuxtv.org/patch/40093/

While debugging this issue, I saw *a lot* of network-generated URB
traffic from RPi3 Ethernet port drivers that were using non-aligned 
buffers and were subject to the temporary buffer conversion.

My understanding here is that having a temporary bounce buffer sucks,
as the performance and latency are affected. So, I see the value of
adding this constraint to the API, pushing the task of getting 
aligned buffers to the USB drivers, but you're right: that means a lot
of work, as all USB drivers should be reviewed.

Btw, I'm a lot more concerned about USB storage drivers. When I was
discussing about this issue at the #raspberrypi-devel IRC channel,
someone complained that, after switching from the RPi downstream Kernel
to upstream, his USB data storage got corrupted. Well, if the USB
storage drivers also assume that the buffer can be continuous,
that can corrupt data.

That's why I think that being verbose here is a good idea.

I'll rework on this patch to put more emphasis about this issue.

> > 
> > So we need to include the full story here.  
> 
> I personally don't care much about whose side is responsible for handling the 
> alignment constraints, but I want it to be documented before "fixing" any USB 
> driver.
> 



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 08/22] usb/anchors.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core functions. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../anchors.txt => driver-api/usb/anchors.rst} | 36 --
 Documentation/driver-api/usb/index.rst |  1 +
 2 files changed, 21 insertions(+), 16 deletions(-)
 rename Documentation/{usb/anchors.txt => driver-api/usb/anchors.rst} (75%)

diff --git a/Documentation/usb/anchors.txt 
b/Documentation/driver-api/usb/anchors.rst
similarity index 75%
rename from Documentation/usb/anchors.txt
rename to Documentation/driver-api/usb/anchors.rst
index fe6a99a32bbd..4b248e691bd6 100644
--- a/Documentation/usb/anchors.txt
+++ b/Documentation/driver-api/usb/anchors.rst
@@ -1,3 +1,6 @@
+USB Anchors
+~~~
+
 What is anchor?
 ===
 
@@ -13,7 +16,7 @@ Allocation and Initialisation
 =
 
 There's no API to allocate an anchor. It is simply declared
-as struct usb_anchor. init_usb_anchor() must be called to
+as struct usb_anchor. :c:func:`init_usb_anchor` must be called to
 initialise the data structure.
 
 Deallocation
@@ -26,52 +29,53 @@ Association and disassociation of URBs with anchors
 ===
 
 An association of URBs to an anchor is made by an explicit
-call to usb_anchor_urb(). The association is maintained until
+call to :c:func:`usb_anchor_urb`. The association is maintained until
 an URB is finished by (successful) completion. Thus disassociation
 is automatic. A function is provided to forcibly finish (kill)
 all URBs associated with an anchor.
-Furthermore, disassociation can be made with usb_unanchor_urb()
+Furthermore, disassociation can be made with :c:func:`usb_unanchor_urb`
 
 Operations on multitudes of URBs
 
 
-usb_kill_anchored_urbs()
-
+:c:func:`usb_kill_anchored_urbs`
+
 
 This function kills all URBs associated with an anchor. The URBs
 are called in the reverse temporal order they were submitted.
 This way no data can be reordered.
 
-usb_unlink_anchored_urbs()
---
+:c:func:`usb_unlink_anchored_urbs`
+--
+
 
 This function unlinks all URBs associated with an anchor. The URBs
 are processed in the reverse temporal order they were submitted.
-This is similar to usb_kill_anchored_urbs(), but it will not sleep.
+This is similar to :c:func:`usb_kill_anchored_urbs`, but it will not sleep.
 Therefore no guarantee is made that the URBs have been unlinked when
 the call returns. They may be unlinked later but will be unlinked in
 finite time.
 
-usb_scuttle_anchored_urbs()

+:c:func:`usb_scuttle_anchored_urbs`
+---
 
 All URBs of an anchor are unanchored en masse.
 
-usb_wait_anchor_empty_timeout()

+:c:func:`usb_wait_anchor_empty_timeout`
+---
 
 This function waits for all URBs associated with an anchor to finish
 or a timeout, whichever comes first. Its return value will tell you
 whether the timeout was reached.
 
-usb_anchor_empty()
---
+:c:func:`usb_anchor_empty`
+--
 
 Returns true if no URBs are associated with an anchor. Locking
 is the caller's responsibility.
 
-usb_get_from_anchor()
--
+:c:func:`usb_get_from_anchor`
+-
 
 Returns the oldest anchored URB of an anchor. The URB is unanchored
 and returned with a reference. As you may mix URBs to several
diff --git a/Documentation/driver-api/usb/index.rst 
b/Documentation/driver-api/usb/index.rst
index cf2fa2e8d236..5dfb04b2d730 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -6,6 +6,7 @@ Linux USB API
 
usb
gadget
+   anchors
writing_usb_driver
writing_musb_glue_layer
 
-- 
2.9.3

--
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 09/22] usb/bulk-streams.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core functions. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../bulk-streams.txt => driver-api/usb/bulk-streams.rst}| 13 +
 Documentation/driver-api/usb/index.rst  |  1 +
 2 files changed, 10 insertions(+), 4 deletions(-)
 rename Documentation/{usb/bulk-streams.txt => driver-api/usb/bulk-streams.rst} 
(94%)

diff --git a/Documentation/usb/bulk-streams.txt 
b/Documentation/driver-api/usb/bulk-streams.rst
similarity index 94%
rename from Documentation/usb/bulk-streams.txt
rename to Documentation/driver-api/usb/bulk-streams.rst
index ffc02021863e..99b515babdeb 100644
--- a/Documentation/usb/bulk-streams.txt
+++ b/Documentation/driver-api/usb/bulk-streams.rst
@@ -1,3 +1,6 @@
+USB bulk streams
+
+
 Background
 ==
 
@@ -25,7 +28,9 @@ time.
 Driver implications
 ===
 
-int usb_alloc_streams(struct usb_interface *interface,
+::
+
+  int usb_alloc_streams(struct usb_interface *interface,
struct usb_host_endpoint **eps, unsigned int num_eps,
unsigned int num_streams, gfp_t mem_flags);
 
@@ -53,7 +58,7 @@ controller driver, and may change in the future.
 
 
 Picking new Stream IDs to use
-
+=
 
 Stream ID 0 is reserved, and should not be used to communicate with devices.  
If
 usb_alloc_streams() returns with a value of N, you may use streams 1 though N.
@@ -68,9 +73,9 @@ Clean up
 
 
 If a driver wishes to stop using streams to communicate with the device, it
-should call
+should call::
 
-void usb_free_streams(struct usb_interface *interface,
+  void usb_free_streams(struct usb_interface *interface,
struct usb_host_endpoint **eps, unsigned int num_eps,
gfp_t mem_flags);
 
diff --git a/Documentation/driver-api/usb/index.rst 
b/Documentation/driver-api/usb/index.rst
index 5dfb04b2d730..6fe7611f7332 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -7,6 +7,7 @@ Linux USB API
usb
gadget
anchors
+   bulk-streams
writing_usb_driver
writing_musb_glue_layer
 
-- 
2.9.3

--
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 22/22] usb: document that URB transfer_buffer should be aligned

[Mauro Carvalho Chehab]

Several host controllers, commonly found on ARM, like dwc2,
require buffers that are CPU-word aligned for they to work.

Failing to do that will cause random troubles at the caller
drivers, causing them to fail.

Document it.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/URB.rst | 12 
 drivers/usb/core/message.c   | 15 +++
 include/linux/usb.h  | 12 
 3 files changed, 39 insertions(+)

diff --git a/Documentation/driver-api/usb/URB.rst 
b/Documentation/driver-api/usb/URB.rst
index 810ceb0e71bb..2f3db660e613 100644
--- a/Documentation/driver-api/usb/URB.rst
+++ b/Documentation/driver-api/usb/URB.rst
@@ -271,6 +271,18 @@ If you specify your own start frame, make sure it's 
several frames in advance
 of the current frame.  You might want this model if you're synchronizing
 ISO data with some other event stream.
 
+ .. warning::
+
+   Several host drivers have a 32-bits or 64-bits DMA transfer word size,
+   with usually matches the CPU word. Due to such restriction, you should
+   warrant that the @transfer_buffer is DWORD aligned, on 32 bits system, or
+   QDWORD aligned, on 64 bits system. You should also ensure that the
+   buffer has enough space for PAD bits.
+
+   This condition is satisfied if you pass a buffer directly allocated by
+   kmalloc(), but this may not be the case if the driver allocates a bigger
+   buffer and point to a random place inside it.
+
 
 How to start interrupt (INT) transfers?
 ===
diff --git a/drivers/usb/core/message.c b/drivers/usb/core/message.c
index 4c38ea41ae96..1662a4446475 100644
--- a/drivers/usb/core/message.c
+++ b/drivers/usb/core/message.c
@@ -128,6 +128,21 @@ static int usb_internal_control_msg(struct usb_device 
*usb_dev,
  * make sure your disconnect() method can wait for it to complete. Since you
  * don't have a handle on the URB used, you can't cancel the request.
  *
+ * .. note::
+ *
+ *   Several host drivers require that the @data buffer to be aligned
+ *   with the CPU word size (e. g. DWORD for 32 bits, QDWORD for 64 bits).
+ *   It is up to USB drivers should ensure that they'll only pass buffers
+ *   with such alignments.
+ *
+ *   Please also notice that, due to such restriction, the host driver
+ *   may also override PAD bytes at the end of the @data buffer, up to the
+ *   size of the CPU word.
+ *
+ *   Such word alignment condition is normally ensured if the buffer is
+ *   allocated with kmalloc(), but this may not be the case if the driver
+ *   allocates a bigger buffer and point to a random place inside it.
+ *
  * Return: If successful, the number of bytes transferred. Otherwise, a 
negative
  * error number.
  */
diff --git a/include/linux/usb.h b/include/linux/usb.h
index 7e68259360de..5739d4422343 100644
--- a/include/linux/usb.h
+++ b/include/linux/usb.h
@@ -1373,6 +1373,18 @@ typedef void (*usb_complete_t)(struct urb *);
  * capable, assign NULL to it, so that usbmon knows not to use the value.
  * The setup_packet must always be set, so it cannot be located in highmem.
  *
+ * .. warning::
+ *
+ *   Several host drivers have a 32-bits or 64-bits DMA transfer word size,
+ *   with usually matches the CPU word. Due to such restriction, you should
+ *   warrant that the @transfer_buffer is DWORD aligned, on 32 bits system, or
+ *   QDWORD aligned, on 64 bits system. You should also ensure that the
+ *   buffer has enough space for PAD bits.
+ *
+ *   This condition is satisfied if you pass a buffer directly allocated by
+ *   kmalloc(), but this may not be the case if the driver allocates a bigger
+ *   buffer and point to a random place inside it.
+ *
  * Initialization:
  *
  * All URBs submitted must initialize the dev, pipe, transfer_flags (may be
-- 
2.9.3

--
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 12/22] usb/dma.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core features. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../{usb/dma.txt => driver-api/usb/dma.rst}| 51 --
 Documentation/driver-api/usb/index.rst |  1 +
 2 files changed, 28 insertions(+), 24 deletions(-)
 rename Documentation/{usb/dma.txt => driver-api/usb/dma.rst} (79%)

diff --git a/Documentation/usb/dma.txt b/Documentation/driver-api/usb/dma.rst
similarity index 79%
rename from Documentation/usb/dma.txt
rename to Documentation/driver-api/usb/dma.rst
index 444651e70d95..59d5aee89e37 100644
--- a/Documentation/usb/dma.txt
+++ b/Documentation/driver-api/usb/dma.rst
@@ -1,16 +1,19 @@
+USB DMA
+~~~
+
 In Linux 2.5 kernels (and later), USB device drivers have additional control
 over how DMA may be used to perform I/O operations.  The APIs are detailed
 in the kernel usb programming guide (kerneldoc, from the source code).
 
-
-API OVERVIEW
+API overview
+
 
 The big picture is that USB drivers can continue to ignore most DMA issues,
 though they still must provide DMA-ready buffers (see
-Documentation/DMA-API-HOWTO.txt).  That's how they've worked through
-the 2.4 (and earlier) kernels.
+``Documentation/DMA-API-HOWTO.txt``).  That's how they've worked through
+the 2.4 (and earlier) kernels, or they can now be DMA-aware.
 
-OR:  they can now be DMA-aware.
+DMA-aware usb drivers:
 
 - New calls enable DMA-aware drivers, letting them allocate dma buffers and
   manage dma mappings for existing dma-ready buffers (see below).
@@ -20,15 +23,15 @@ OR:  they can now be DMA-aware.
   drivers must not use it.)
 
 - "usbcore" will map this DMA address, if a DMA-aware driver didn't do
-  it first and set URB_NO_TRANSFER_DMA_MAP.  HCDs
+  it first and set ``URB_NO_TRANSFER_DMA_MAP``.  HCDs
   don't manage dma mappings for URBs.
 
 - There's a new "generic DMA API", parts of which are usable by USB device
   drivers.  Never use dma_set_mask() on any USB interface or device; that
   would potentially break all devices sharing that bus.
 
-
-ELIMINATING COPIES
+Eliminating copies
+==
 
 It's good to avoid making CPUs copy data needlessly.  The costs can add up,
 and effects like cache-trashing can impose subtle penalties.
@@ -41,7 +44,7 @@ and effects like cache-trashing can impose subtle penalties.
   For those specific cases, USB has primitives to allocate less expensive
   memory.  They work like kmalloc and kfree versions that give you the right
   kind of addresses to store in urb->transfer_buffer and urb->transfer_dma.
-  You'd also set URB_NO_TRANSFER_DMA_MAP in urb->transfer_flags:
+  You'd also set ``URB_NO_TRANSFER_DMA_MAP`` in urb->transfer_flags::
 
void *usb_alloc_coherent (struct usb_device *dev, size_t size,
int mem_flags, dma_addr_t *dma);
@@ -49,15 +52,15 @@ and effects like cache-trashing can impose subtle penalties.
void usb_free_coherent (struct usb_device *dev, size_t size,
void *addr, dma_addr_t dma);
 
-  Most drivers should *NOT* be using these primitives; they don't need
+  Most drivers should **NOT** be using these primitives; they don't need
   to use this type of memory ("dma-coherent"), and memory returned from
-  kmalloc() will work just fine.
+  :c:func:`kmalloc` will work just fine.
 
   The memory buffer returned is "dma-coherent"; sometimes you might need to
   force a consistent memory access ordering by using memory barriers.  It's
   not using a streaming DMA mapping, so it's good for small transfers on
   systems where the I/O would otherwise thrash an IOMMU mapping.  (See
-  Documentation/DMA-API-HOWTO.txt for definitions of "coherent" and
+  ``Documentation/DMA-API-HOWTO.txt`` for definitions of "coherent" and
   "streaming" DMA mappings.)
 
   Asking for 1/Nth of a page (as well as asking for N pages) is reasonably
@@ -75,15 +78,15 @@ and effects like cache-trashing can impose subtle penalties.
   way to expose these capabilities ... and in any case, HIGHMEM is mostly a
   design wart specific to x86_32.  So your best bet is to ensure you never
   pass a highmem buffer into a USB driver.  That's easy; it's the default
-  behavior.  Just don't override it; e.g. with NETIF_F_HIGHDMA.
+  behavior.  Just don't override it; e.g. with ``NETIF_F_HIGHDMA``.
 
   This may force your callers to do some bounce buffering, copying from
   high memory to "normal" DMA memory.  If you can come up with a good way
   to fix this issue (for x86_32 machines with over 1 GByte of memory),
   feel free to submit patches.
 
-
-WORKING WITH EXISTING BUFFERS
+Working with existing buffers
+=
 
 Existing buffers aren't usable for DMA without first being mapped into the
 DMA address space of the device.  However, most buffers passed to your
@@ -92,7 +95,7 @@ of Documentation/DMA-API-HOWTO.txt, titled "What memory is 
DMA-able?")
 
 - When you're using scatterlists, you can map everything at once.  O

[PATCH v2 20/22] usb: gadget.h: be consistent at kernel doc macros

[Mauro Carvalho Chehab]

There's one value that use spaces instead of tabs to ident.
That causes the following warning:

./include/linux/usb/gadget.h:193: ERROR: Unexpected indentation.

Signed-off-by: Mauro Carvalho Chehab 
---
 include/linux/usb/gadget.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/linux/usb/gadget.h b/include/linux/usb/gadget.h
index e4516e9ded0f..fbc22a39e7bc 100644
--- a/include/linux/usb/gadget.h
+++ b/include/linux/usb/gadget.h
@@ -188,7 +188,7 @@ struct usb_ep_caps {
  * @caps:The structure describing types and directions supported by endoint.
  * @maxpacket:The maximum packet size used on this endpoint.  The initial
  * value can sometimes be reduced (hardware allowing), according to
- *  the endpoint descriptor used to configure the endpoint.
+ * the endpoint descriptor used to configure the endpoint.
  * @maxpacket_limit:The maximum packet size value which can be handled by this
  * endpoint. It's set once by UDC driver when endpoint is initialized, and
  * should not be changed. Should not be confused with maxpacket.
-- 
2.9.3

--
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/22] driver-api/basics.rst: add device table header

[Mauro Carvalho Chehab]

The structs there at device table are used by other documentation
at the Kernel. So, add it to the driver API.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/basics.rst | 6 ++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/driver-api/basics.rst 
b/Documentation/driver-api/basics.rst
index 935b9b8d456c..472e7a664d13 100644
--- a/Documentation/driver-api/basics.rst
+++ b/Documentation/driver-api/basics.rst
@@ -7,6 +7,12 @@ Driver Entry and Exit points
 .. kernel-doc:: include/linux/init.h
:internal:
 
+Driver device table
+---
+
+.. kernel-doc:: include/linux/mod_devicetable.h
+   :internal:
+
 Atomic and pointer manipulation
 ---
 
-- 
2.9.3

--
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 19/22] usb: composite.h: fix two warnings when building docs

[Mauro Carvalho Chehab]

By definition, we use /* private: */ tag when we won't be documenting
a parameter. However, those two parameters are documented:

./include/linux/usb/composite.h:510: warning: Excess struct/union/enum/typedef 
member 'setup_pending' description in 'usb_composite_dev'
./include/linux/usb/composite.h:510: warning: Excess struct/union/enum/typedef 
member 'os_desc_pending' description in 'usb_composite_dev'

So, we need to use /* public: */ to avoid a warning.

Signed-off-by: Mauro Carvalho Chehab 
---
 include/linux/usb/composite.h | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/include/linux/usb/composite.h b/include/linux/usb/composite.h
index 30a063e98c19..f665d2ceac20 100644
--- a/include/linux/usb/composite.h
+++ b/include/linux/usb/composite.h
@@ -504,8 +504,9 @@ struct usb_composite_dev {
/* protects deactivations and delayed_status counts*/
spinlock_t  lock;
 
-   unsignedsetup_pending:1;
-   unsignedos_desc_pending:1;
+   /* public: */
+   unsigned intsetup_pending:1;
+   unsigned intos_desc_pending:1;
 };
 
 extern int usb_string_id(struct usb_composite_dev *c);
-- 
2.9.3

--
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 18/22] usb: get rid of some ReST doc build errors

[Mauro Carvalho Chehab]

We need an space before a numbered list to avoid those warnings:

./drivers/usb/core/message.c:478: ERROR: Unexpected indentation.
./drivers/usb/core/message.c:479: WARNING: Block quote ends without a blank 
line; unexpected unindent.
./include/linux/usb/composite.h:455: ERROR: Unexpected indentation.
./include/linux/usb/composite.h:456: WARNING: Block quote ends without a blank 
line; unexpected unindent.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/usb/core/message.c| 1 +
 include/linux/usb/composite.h | 1 +
 2 files changed, 2 insertions(+)

diff --git a/drivers/usb/core/message.c b/drivers/usb/core/message.c
index 2184ef40a82a..4c38ea41ae96 100644
--- a/drivers/usb/core/message.c
+++ b/drivers/usb/core/message.c
@@ -474,6 +474,7 @@ EXPORT_SYMBOL_GPL(usb_sg_init);
  * significantly improve USB throughput.
  *
  * There are three kinds of completion for this function.
+ *
  * (1) success, where io->status is zero.  The number of io->bytes
  * transferred is as requested.
  * (2) error, where io->status is a negative errno value.  The number
diff --git a/include/linux/usb/composite.h b/include/linux/usb/composite.h
index 4616a49a1c2e..30a063e98c19 100644
--- a/include/linux/usb/composite.h
+++ b/include/linux/usb/composite.h
@@ -451,6 +451,7 @@ static inline struct usb_composite_driver *to_cdriver(
  * sure doing that won't hurt too much.
  *
  * One notion for how to handle Wireless USB devices involves:
+ *
  * (a) a second gadget here, discovery mechanism TBD, but likely
  * needing separate "register/unregister WUSB gadget" calls;
  * (b) updates to usb_gadget to include flags "is it wireless",
-- 
2.9.3

--
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 21/22] docs-rst: fix usb cross-references

[Mauro Carvalho Chehab]

As some USB documentation files got moved, adjust their
cross-references to their new place.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/ABI/stable/sysfs-bus-usb| 2 +-
 Documentation/driver-api/usb/URB.rst  | 2 ++
 Documentation/driver-api/usb/callbacks.rst| 4 ++--
 Documentation/driver-api/usb/error-codes.rst  | 2 ++
 Documentation/driver-api/usb/persist.rst  | 2 ++
 Documentation/driver-api/usb/power-management.rst | 2 +-
 Documentation/driver-api/usb/usb.rst  | 4 ++--
 Documentation/power/swsusp.txt| 2 +-
 drivers/staging/most/hdm-usb/hdm_usb.c| 2 +-
 drivers/usb/core/Kconfig  | 2 +-
 10 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/Documentation/ABI/stable/sysfs-bus-usb 
b/Documentation/ABI/stable/sysfs-bus-usb
index 831f15d9672f..b832eeff 100644
--- a/Documentation/ABI/stable/sysfs-bus-usb
+++ b/Documentation/ABI/stable/sysfs-bus-usb
@@ -9,7 +9,7 @@ Description:
hubs this facility is always enabled and their device
directories will not contain this file.
 
-   For more information, see Documentation/usb/persist.txt.
+   For more information, see 
Documentation/driver-api/usb/persist.rst.
 
 What:  /sys/bus/usb/devices/.../power/autosuspend
 Date:  March 2007
diff --git a/Documentation/driver-api/usb/URB.rst 
b/Documentation/driver-api/usb/URB.rst
index 2bcd06c2c5aa..810ceb0e71bb 100644
--- a/Documentation/driver-api/usb/URB.rst
+++ b/Documentation/driver-api/usb/URB.rst
@@ -1,3 +1,5 @@
+.. _usb-urb:
+
 USB Request Block (URB)
 ~~~
 
diff --git a/Documentation/driver-api/usb/callbacks.rst 
b/Documentation/driver-api/usb/callbacks.rst
index 93a8d53e27e7..2b80cf54bcc3 100644
--- a/Documentation/driver-api/usb/callbacks.rst
+++ b/Documentation/driver-api/usb/callbacks.rst
@@ -8,7 +8,7 @@ Usbcore will call into a driver through callbacks defined in 
the driver
 structure and through the completion handler of URBs a driver submits.
 Only the former are in the scope of this document. These two kinds of
 callbacks are completely independent of each other. Information on the
-completion callback can be found in Documentation/usb/URB.txt.
+completion callback can be found in :ref:`usb-urb`.
 
 The callbacks defined in the driver structure are:
 
@@ -53,7 +53,7 @@ The callbacks defined in the driver structure are:
 
 The ioctl interface (2) should be used only if you have a very good
 reason. Sysfs is preferred these days. The PM callbacks are covered
-separately in Documentation/usb/power-management.txt.
+separately in :ref:`usb-power-management`.
 
 Calling conventions
 ===
diff --git a/Documentation/driver-api/usb/error-codes.rst 
b/Documentation/driver-api/usb/error-codes.rst
index 9c11a0fd16cb..a3e84bfac776 100644
--- a/Documentation/driver-api/usb/error-codes.rst
+++ b/Documentation/driver-api/usb/error-codes.rst
@@ -1,3 +1,5 @@
+.. _usb-error-codes:
+
 USB Error codes
 ~~~
 
diff --git a/Documentation/driver-api/usb/persist.rst 
b/Documentation/driver-api/usb/persist.rst
index ea1b43f0559e..08cafc6292c1 100644
--- a/Documentation/driver-api/usb/persist.rst
+++ b/Documentation/driver-api/usb/persist.rst
@@ -1,3 +1,5 @@
+.. _usb-persist:
+
 USB device persistence during system suspend
 
 
diff --git a/Documentation/driver-api/usb/power-management.rst 
b/Documentation/driver-api/usb/power-management.rst
index c068257f6d27..79beb807996b 100644
--- a/Documentation/driver-api/usb/power-management.rst
+++ b/Documentation/driver-api/usb/power-management.rst
@@ -328,7 +328,7 @@ possible to work around the hibernation-forces-disconnect 
problem by
 using the USB Persist facility.)
 
 The ``reset_resume`` method is used by the USB Persist facility (see
-``Documentation/usb/persist.txt``) and it can also be used under certain
+:ref:`usb-persist`) and it can also be used under certain
 circumstances when ``CONFIG_USB_PERSIST`` is not enabled.  Currently, if a
 device is reset during a resume and the driver does not have a
 ``reset_resume`` method, the driver won't receive any notification about
diff --git a/Documentation/driver-api/usb/usb.rst 
b/Documentation/driver-api/usb/usb.rst
index 5ebaf669704c..6824089ef4c8 100644
--- a/Documentation/driver-api/usb/usb.rst
+++ b/Documentation/driver-api/usb/usb.rst
@@ -424,8 +424,8 @@ header.
 Unless noted otherwise, the ioctl requests described here will update
 the modification time on the usbfs file to which they are applied
 (unless they fail). A return of zero indicates success; otherwise, a
-standard USB error code is returned. (These are documented in
-``Documentation/usb/error-codes.txt`` in your kernel sources.)
+standard USB error code is returned (These are documented in
+:ref:`usb-error-codes`).
 
 Each of these files multiplexes access to several I/O streams, 

[PATCH v2 17/22] usb.rst: get rid of some Sphinx errors

[Mauro Carvalho Chehab]

Get rid of those warnings:

Documentation/driver-api/usb/usb.rst:615: ERROR: Unknown target name: 
"usb_type".
Documentation/driver-api/usb/usb.rst:615: ERROR: Unknown target name: 
"usb_dir".
Documentation/driver-api/usb/usb.rst:615: ERROR: Unknown target name: 
"usb_recip".
Documentation/driver-api/usb/usb.rst:679: ERROR: Unknown target name: 
"usbdevfs_urb_type".

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/usb.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/driver-api/usb/usb.rst 
b/Documentation/driver-api/usb/usb.rst
index d15ab8ae5239..5ebaf669704c 100644
--- a/Documentation/driver-api/usb/usb.rst
+++ b/Documentation/driver-api/usb/usb.rst
@@ -615,8 +615,8 @@ USBDEVFS_CONTROL
 The first eight bytes of this structure are the contents of the
 SETUP packet to be sent to the device; see the USB 2.0 specification
 for details. The bRequestType value is composed by combining a
-USB_TYPE_\* value, a USB_DIR_\* value, and a USB_RECIP_\*
-value (from **). If wLength is nonzero, it describes
+``USB_TYPE_*`` value, a ``USB_DIR_*`` value, and a ``USB_RECIP_*``
+value (from ``linux/usb.h``). If wLength is nonzero, it describes
 the length of the data buffer, which is either written to the device
 (USB_DIR_OUT) or read from the device (USB_DIR_IN).
 
@@ -678,7 +678,7 @@ the blocking is separate.
 
 These requests are packaged into a structure that resembles the URB used
 by kernel device drivers. (No POSIX Async I/O support here, sorry.) It
-identifies the endpoint type (USBDEVFS_URB_TYPE_\*), endpoint
+identifies the endpoint type (``USBDEVFS_URB_TYPE_*``), endpoint
 (number, masked with USB_DIR_IN as appropriate), buffer and length,
 and a user "context" value serving to uniquely identify each request.
 (It's usually a pointer to per-request data.) Flags can modify requests
-- 
2.9.3

--
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 16/22] usb/URB.txt: convert to ReST and update it

[Mauro Carvalho Chehab]

The URB doc describes the Kernel mechanism that do USB transfers.
While the functions are already described at urb.h, there are a
number of concepts and theory that are important for USB driver
developers.

Convert it to ReST and use C ref links to point to the places
at usb.h where each function and struct is located.

A few of those descriptions were incomplete. While here, update
to reflect the current API status.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../{usb/URB.txt => driver-api/usb/URB.rst}| 205 -
 Documentation/driver-api/usb/index.rst |   1 +
 Documentation/driver-api/usb/usb.rst   |   2 +
 3 files changed, 119 insertions(+), 89 deletions(-)
 rename Documentation/{usb/URB.txt => driver-api/usb/URB.rst} (52%)

diff --git a/Documentation/usb/URB.txt b/Documentation/driver-api/usb/URB.rst
similarity index 52%
rename from Documentation/usb/URB.txt
rename to Documentation/driver-api/usb/URB.rst
index 50da0d455444..2bcd06c2c5aa 100644
--- a/Documentation/usb/URB.txt
+++ b/Documentation/driver-api/usb/URB.rst
@@ -1,16 +1,22 @@
-Revised: 2000-Dec-05.
-Again:   2002-Jul-06
-Again:   2005-Sep-19
+USB Request Block (URB)
+~~~
 
-NOTE:
+:Revised: 2000-Dec-05
+:Again:   2002-Jul-06
+:Again:   2005-Sep-19
+:Again:   2017-Mar-29
 
-The USB subsystem now has a substantial section in "The Linux Kernel API"
-guide (in Documentation/DocBook), generated from the current source
-code.  This particular documentation file isn't particularly current or
-complete; don't rely on it except for a quick overview.
 
+.. note::
 
-1.1. Basic concept or 'What is an URB?'
+The USB subsystem now has a substantial section at :ref:`usb-hostside-api`
+section, generated from the current source code.
+This particular documentation file isn't complete and may not be
+updated to the last version; don't rely on it except for a quick
+overview.
+
+Basic concept or 'What is an URB?'
+==
 
 The basic idea of the new driver is message passing, the message itself is 
 called USB Request Block, or URB for short. 
@@ -19,10 +25,11 @@ called USB Request Block, or URB for short.
   and deliver the data and status back. 
 
 - Execution of an URB is inherently an asynchronous operation, i.e. the 
-  usb_submit_urb(urb) call returns immediately after it has successfully
+  :c:func:`usb_submit_urb` call returns immediately after it has successfully
   queued the requested action.
 
-- Transfers for one URB can be canceled with usb_unlink_urb(urb) at any time. 
+- Transfers for one URB can be canceled with :c:func:`usb_unlink_urb`
+  at any time.
 
 - Each URB has a completion handler, which is called after the action
   has been successfully completed or canceled. The URB also contains a
@@ -35,53 +42,55 @@ called USB Request Block, or URB for short.
   of data to (or from) devices when using periodic transfer modes.
 
 
-1.2. The URB structure
+The URB structure
+=
 
-Some of the fields in an URB are:
+Some of the fields in struct :c:type:`urb` are::
 
-struct urb
-{
-// (IN) device and pipe specify the endpoint queue
+  struct urb
+  {
+  // (IN) device and pipe specify the endpoint queue
struct usb_device *dev; // pointer to associated USB device
unsigned int pipe;  // endpoint information
 
-   unsigned int transfer_flags;// ISO_ASAP, SHORT_NOT_OK, etc.
+   unsigned int transfer_flags;// URB_ISO_ASAP, URB_SHORT_NOT_OK, etc.
 
-// (IN) all urbs need completion routines
+  // (IN) all urbs need completion routines
void *context;  // context for completion routine
-   void (*complete)(struct urb *); // pointer to completion routine
+   usb_complete_t complete;// pointer to completion routine
 
-// (OUT) status after each completion
+  // (OUT) status after each completion
int status; // returned status
 
-// (IN) buffer used for data transfers
+  // (IN) buffer used for data transfers
void *transfer_buffer;  // associated data buffer
-   int transfer_buffer_length; // data buffer length
+   u32 transfer_buffer_length; // data buffer length
int number_of_packets;  // size of iso_frame_desc
 
-// (OUT) sometimes only part of CTRL/BULK/INTR transfer_buffer is used
-   int actual_length;  // actual data buffer length
+  // (OUT) sometimes only part of CTRL/BULK/INTR transfer_buffer is used
+   u32 actual_length;  // actual data buffer length
 
-// (IN) setup stage for CTRL (pass a struct usb_ctrlrequest)
-   unsigned char* setup_packet;// setup packet (control only)
+  // (IN) setup stage for CTRL (pass a struct usb_ctrlrequest)
+   unsigned char *setup_packet;// setup packet (control only)
 
-// Only for PERIODIC transfers (ISO, INTERRUPT)
-// (IN/OUT) start_frame is set un

[PATCH v2 07/22] writing_musb_glue_layer.rst: Enrich its ReST representation

[Mauro Carvalho Chehab]

This file is actually quite complex, and required several
manual handwork:

- add a title for the document;
- use the right tags for monospaced fonts;
- use c references where needed;
- adjust cross-reference to writing_usb_driver.rst
- hightlight cross-referenced lines.

With regards to C code snippet line highlights, the better would be
to use :linenos: for the C code snippets that are referenced by
the line number. However, at least with Sphinx 1.4.9, enabling
it cause the line number to be misaligned with the code,
making it even more confusing. So, instead, let's use
:emphasize-lines: tag to mark the lines that are referenced
at the text.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../driver-api/usb/writing_musb_glue_layer.rst | 598 ++---
 1 file changed, 292 insertions(+), 306 deletions(-)

diff --git a/Documentation/driver-api/usb/writing_musb_glue_layer.rst 
b/Documentation/driver-api/usb/writing_musb_glue_layer.rst
index 52700c7031f9..e90e8fa95600 100644
--- a/Documentation/driver-api/usb/writing_musb_glue_layer.rst
+++ b/Documentation/driver-api/usb/writing_musb_glue_layer.rst
@@ -1,6 +1,6 @@
-==
-Writing an MUSB Glue Layer
-==
+=
+Writing a MUSB Glue Layer
+=
 
 :Author: Apelete Seketeli
 
@@ -21,10 +21,12 @@ design.
 As a self-taught exercise I have written an MUSB glue layer for the
 Ingenic JZ4740 SoC, modelled after the many MUSB glue layers in the
 kernel source tree. This layer can be found at
-drivers/usb/musb/jz4740.c. In this documentation I will walk through the
-basics of the jz4740.c glue layer, explaining the different pieces and
+``drivers/usb/musb/jz4740.c``. In this documentation I will walk through the
+basics of the ``jz4740.c`` glue layer, explaining the different pieces and
 what needs to be done in order to write your own device glue layer.
 
+.. _musb-basics:
+
 Linux MUSB Basics
 =
 
@@ -39,33 +41,30 @@ USB Device Drivers documentation (again, see Resources).
 
 Linux USB stack is a layered architecture in which the MUSB controller
 hardware sits at the lowest. The MUSB controller driver abstract the
-MUSB controller hardware to the Linux USB stack.
+MUSB controller hardware to the Linux USB stack::
 
-::
-
-  
-  |  | <--- drivers/usb/gadget
-  | Linux USB Core Stack | <--- drivers/usb/host
-  |  | <--- drivers/usb/core
-  
- ⬍
- --
- || <-- drivers/usb/musb/musb_gadget.c
- | MUSB Controller driver | <-- drivers/usb/musb/musb_host.c
- || <-- drivers/usb/musb/musb_core.c
- --
- ⬍
+ 
+ |  | <--- drivers/usb/gadget
+ | Linux USB Core Stack | <--- drivers/usb/host
+ |  | <--- drivers/usb/core
+ 
+⬍
+--
+|| <-- drivers/usb/musb/musb_gadget.c
+| MUSB Controller driver | <-- drivers/usb/musb/musb_host.c
+|| <-- drivers/usb/musb/musb_core.c
+--
+⬍
   -
   | MUSB Platform Specific Driver |
   |   | <-- drivers/usb/musb/jz4740.c
   |   aka "Glue Layer"|
   -
- ⬍
+⬍
   -
   |   MUSB Controller Hardware|
   -
 
-
 As outlined above, the glue layer is actually the platform specific code
 sitting in between the controller driver and the controller hardware.
 
@@ -78,37 +77,32 @@ about an embedded controller chip here, so no insertion or 
removal at
 run-time.
 
 All of this information is passed to the MUSB controller driver through
-a platform_driver structure defined in the glue layer as:
-
-::
+a :c:type:`platform_driver` structure defined in the glue layer as::
 
 static struct platform_driver jz4740_driver = {
-.probe  = jz4740_probe,
-.remove = jz4740_remove,
-.driver = {
-.name   = "musb-jz4740",
-},
+   .probe  = jz4740_probe,
+   .remove = jz4740_remove,
+   .driver = {
+   .name   = "musb-jz4740",
+   },
 };
 
-
 The probe and remove function pointers are called when a matching device
 is detected and, respectively, released. The name string describes the
 device supported by this glue layer. In the current case it matches a
-platform_device structure declared in a

[PATCH v2 01/22] tmplcvt: make the tool more robust

[Mauro Carvalho Chehab]

Currently, the script just assumes to be called at
Documentation/sphinx/. Change it to work on any directory,
and make it abort if something gets wrong.

Also, be sure that both parameters are specified.

That should avoid troubles like this:

$ Documentation/sphinx/tmplcvt Documentation/DocBook/writing_usb_driver.tmpl
sed: couldn't open file convert_template.sed: No such file or directory

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/sphinx/tmplcvt | 13 +++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/Documentation/sphinx/tmplcvt b/Documentation/sphinx/tmplcvt
index 909a73065e0a..31df8eb7feca 100755
--- a/Documentation/sphinx/tmplcvt
+++ b/Documentation/sphinx/tmplcvt
@@ -7,13 +7,22 @@
 # fix \_
 # title line?
 #
+set -eu
+
+if [ "$2" == "" ]; then
+   echo "$0  "
+   exit
+fi
+
+DIR=$(dirname $0)
 
 in=$1
 rst=$2
 tmp=$rst.tmp
 
 cp $in $tmp
-sed --in-place -f convert_template.sed $tmp
+sed --in-place -f $DIR/convert_template.sed $tmp
 pandoc -s -S -f docbook -t rst -o $rst $tmp
-sed --in-place -f post_convert.sed $rst
+sed --in-place -f $DIR/post_convert.sed $rst
 rm $tmp
+echo "book writen to $rst"
-- 
2.9.3

--
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/22] gadget.rst: Enrich its ReST representation and add kernel-doc tag

[Mauro Carvalho Chehab]

The pandoc conversion is not perfect. Do handwork in order to:

- add a title to this chapter;
- use the proper warning and note markups;
- use kernel-doc to include Kernel header and c files;
- remove legacy notes with regards to DocBook;
- some other minor adjustments to make it better to read in
  text mode and in html.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/gadget.rst | 127 +---
 1 file changed, 52 insertions(+), 75 deletions(-)

diff --git a/Documentation/driver-api/usb/gadget.rst 
b/Documentation/driver-api/usb/gadget.rst
index 52b299b1ca6d..3e8a3809c0b8 100644
--- a/Documentation/driver-api/usb/gadget.rst
+++ b/Documentation/driver-api/usb/gadget.rst
@@ -38,7 +38,7 @@ address a number of important problems, including:
resources.
 
 Most Linux developers will not be able to use this API, since they have
-USB "host" hardware in a PC, workstation, or server. Linux users with
+USB ``host`` hardware in a PC, workstation, or server. Linux users with
 embedded systems are more likely to have USB peripheral hardware. To
 distinguish drivers running inside such hardware from the more familiar
 Linux "USB device drivers", which are host side proxies for the real USB
@@ -64,7 +64,7 @@ Structure of Gadget Drivers
 
 A system running inside a USB peripheral normally has at least three
 layers inside the kernel to handle USB protocol processing, and may have
-additional layers in user space code. The "gadget" API is used by the
+additional layers in user space code. The ``gadget`` API is used by the
 middle layer to interact with the lowest level (which directly handles
 hardware).
 
@@ -143,13 +143,13 @@ In Linux, from the bottom up, these layers are:
 *Additional Layers*
 Other layers may exist. These could include kernel layers, such as
 network protocol stacks, as well as user mode applications building
-on standard POSIX system call APIs such as *open()*, *close()*,
-*read()* and *write()*. On newer systems, POSIX Async I/O calls may
+on standard POSIX system call APIs such as ``open()``, ``close()``,
+``read()`` and ``write()``. On newer systems, POSIX Async I/O calls may
 be an option. Such user mode code will not necessarily be subject to
 the GNU General Public License (GPL).
 
 OTG-capable systems will also need to include a standard Linux-USB host
-side stack, with *usbcore*, one or more *Host Controller Drivers*
+side stack, with ``usbcore``, one or more *Host Controller Drivers*
 (HCDs), *USB Device Drivers* to support the OTG "Targeted Peripheral
 List", and so forth. There will also be an *OTG Controller Driver*,
 which is visible to gadget and device driver developers only indirectly.
@@ -174,24 +174,20 @@ combined, to implement composite devices.
 Kernel Mode Gadget API
 ==
 
-Gadget drivers declare themselves through a *struct
-usb_gadget_driver*, which is responsible for most parts of enumeration
-for a *struct usb_gadget*. The response to a set_configuration usually
-involves enabling one or more of the *struct usb_ep* objects exposed by
-the gadget, and submitting one or more *struct usb_request* buffers to
+Gadget drivers declare themselves through a struct
+:c:type:`usb_gadget_driver`, which is responsible for most parts of enumeration
+for a struct :c:type:`usb_gadget`. The response to a set_configuration usually
+involves enabling one or more of the struct :c:type:`usb_ep` objects exposed by
+the gadget, and submitting one or more struct :c:type:`usb_request` buffers to
 transfer data. Understand those four data types, and their operations,
 and you will understand how this API works.
 
-**Note**
+.. Note::
 
-This documentation was prepared using the standard Linux kernel
-``docproc`` tool, which turns text and in-code comments into SGML
-DocBook and then into usable formats such as HTML or PDF. Other than
-the "Chapter 9" data types, most of the significant data types and
-functions are described here.
+Other than the "Chapter 9" data types, most of the significant data
+types and functions are described here.
 
-However, docproc does not understand all the C constructs that are
-used, so some relevant information is likely omitted from what you
+However, some relevant information is likely omitted from what you
 are reading. One example of such information is endpoint
 autoconfiguration. You'll have to read the header file, and use
 example source code (such as that for "Gadget Zero"), to fully
@@ -199,10 +195,10 @@ and you will understand how this API works.
 
 The part of the API implementing some basic driver capabilities is
 specific to the version of the Linux kernel that's in use. The 2.6
-kernel includes a *driver model* framework that has no analogue on
-earlier kernels; so those parts of the gadget API are not fully
-portable. (They are implemented on 2.4 kernels, but in a different
-  

[PATCH v2 13/22] error-codes.rst: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core features. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/error-codes.rst | 205 +++
 Documentation/driver-api/usb/index.rst   |   1 +
 Documentation/usb/error-codes.txt| 175 ---
 3 files changed, 206 insertions(+), 175 deletions(-)
 create mode 100644 Documentation/driver-api/usb/error-codes.rst
 delete mode 100644 Documentation/usb/error-codes.txt

diff --git a/Documentation/driver-api/usb/error-codes.rst 
b/Documentation/driver-api/usb/error-codes.rst
new file mode 100644
index ..9c11a0fd16cb
--- /dev/null
+++ b/Documentation/driver-api/usb/error-codes.rst
@@ -0,0 +1,205 @@
+USB Error codes
+~~~
+
+:Revised: 2004-Oct-21
+
+This is the documentation of (hopefully) all possible error codes (and
+their interpretation) that can be returned from usbcore.
+
+Some of them are returned by the Host Controller Drivers (HCDs), which
+device drivers only see through usbcore.  As a rule, all the HCDs should
+behave the same except for transfer speed dependent behaviors and the
+way certain faults are reported.
+
+
+Error codes returned by :c:func:`usb_submit_urb`
+
+
+Non-USB-specific:
+
+
+=== ===
+0  URB submission went fine
+
+``-ENOMEM``no memory for allocation of internal structures
+=== ===
+
+USB-specific:
+
+===
===
+``-EBUSY`` The URB is already active.
+
+``-ENODEV``specified USB-device or bus doesn't exist
+
+``-ENOENT``specified interface or endpoint does not exist or
+   is not enabled
+
+``-ENXIO`` host controller driver does not support queuing of
+   this type of urb.  (treat as a host controller bug.)
+
+``-EINVAL``a) Invalid transfer type specified (or not supported)
+   b) Invalid or unsupported periodic transfer interval
+   c) ISO: attempted to change transfer interval
+   d) ISO: ``number_of_packets`` is < 0
+   e) various other cases
+
+``-EXDEV`` ISO: ``URB_ISO_ASAP`` wasn't specified and all the
+   frames the URB would be scheduled in have already
+   expired.
+
+``-EFBIG`` Host controller driver can't schedule that many ISO
+   frames.
+
+``-EPIPE`` The pipe type specified in the URB doesn't match the
+   endpoint's actual type.
+
+``-EMSGSIZE``  (a) endpoint maxpacket size is zero; it is not usable
+   in the current interface altsetting.
+   (b) ISO packet is larger than the endpoint maxpacket.
+   (c) requested data transfer length is invalid: negative
+   or too large for the host controller.
+
+``-ENOSPC``This request would overcommit the usb bandwidth reserved
+   for periodic transfers (interrupt, isochronous).
+
+``-ESHUTDOWN`` The device or host controller has been disabled due to
+   some problem that could not be worked around.
+
+``-EPERM`` Submission failed because ``urb->reject`` was set.
+
+``-EHOSTUNREACH``  URB was rejected because the device is suspended.
+
+``-ENOEXEC``   A control URB doesn't contain a Setup packet.
+===
===
+
+Error codes returned by ``in urb->status`` or in ``iso_frame_desc[n].status`` 
(for ISO)
+===
+
+USB device drivers may only test urb status values in completion handlers.
+This is because otherwise there would be a race between HCDs updating
+these values on one CPU, and device drivers testing them on another CPU.
+
+A transfer's actual_length may be positive even when an error has been
+reported.  That's because transfers often involve several packets, so that
+one or more packets could finish before an error stops further endpoint I/O.
+
+For isochronous URBs, the urb status value is non-zero only if the URB is
+unlinked, the device is removed, the host controller is disabled, or the total
+transferred length is less than the requested length and the
+``URB_SHORT_NOT_OK`` flag is set.  Completion handlers for isochronous URBs
+should only see ``urb->status`` set to zero, ``-ENOENT``, ``-ECONNRESET``,
+``-ESHUTDOWN``, or ``-EREMOTEIO``. Individual frame descriptor status fields
+may report more status codes.
+
+
+===
=

[PATCH v2 04/22] usb.rst: Enrich its ReST representation

[Mauro Carvalho Chehab]

- use the proper warning and note markups;
- add references for parts of the document that will be
  cross-referenced on other USB docs;
- some minor adjustments to make it better to read in
  text mode and in html.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/usb.rst | 48 +---
 1 file changed, 17 insertions(+), 31 deletions(-)

diff --git a/Documentation/driver-api/usb/usb.rst 
b/Documentation/driver-api/usb/usb.rst
index b856abb3200e..7e820768ee4f 100644
--- a/Documentation/driver-api/usb/usb.rst
+++ b/Documentation/driver-api/usb/usb.rst
@@ -102,6 +102,8 @@ disconnect testing (while the device is active) with each 
different host
 controller driver, to make sure drivers don't have bugs of their own as
 well as to make sure they aren't relying on some HCD-specific behavior.
 
+.. _usb_chapter9:
+
 USB-Standard Types
 ==
 
@@ -112,6 +114,8 @@ USB, and in APIs including this host side API, gadget APIs, 
and usbfs.
 .. kernel-doc:: include/linux/usb/ch9.h
:internal:
 
+.. _usb_header:
+
 Host-Side Data Types and Macros
 ===
 
@@ -209,7 +213,7 @@ library that wraps it. Such libraries include
 `libusb `__ for C/C++, and
 `jUSB `__ for Java.
 
-**Note**
+.. note::
 
 This particular documentation is incomplete, especially with respect
 to the asynchronous mode. As of kernel 2.5.66 the code and this
@@ -319,9 +323,7 @@ files. For information about the current format of this 
file, see the
 sources.
 
 This file, in combination with the poll() system call, can also be used
-to detect when devices are added or removed:
-
-::
+to detect when devices are added or removed::
 
 int fd;
 struct pollfd pfd;
@@ -407,9 +409,7 @@ The ioctl() Requests
 
 
 To use these ioctls, you need to include the following headers in your
-userspace program:
-
-::
+userspace program::
 
 #include 
 #include 
@@ -458,9 +458,7 @@ USBDEVFS_CLAIMINTERFACE
 
 USBDEVFS_CONNECTINFO
 Says whether the device is lowspeed. The ioctl parameter points to a
-structure like this:
-
-::
+structure like this::
 
struct usbdevfs_connectinfo {
unsigned int   devnum;
@@ -477,9 +475,7 @@ USBDEVFS_CONNECTINFO
 USBDEVFS_GETDRIVER
 Returns the name of the kernel driver bound to a given interface (a
 string). Parameter is a pointer to this structure, which is
-modified:
-
-::
+modified::
 
struct usbdevfs_getdriver {
unsigned int  interface;
@@ -490,9 +486,7 @@ USBDEVFS_GETDRIVER
 
 USBDEVFS_IOCTL
 Passes a request from userspace through to a kernel driver that has
-an ioctl entry in the *struct usb_driver* it registered.
-
-::
+an ioctl entry in the *struct usb_driver* it registered::
 
struct usbdevfs_ioctl {
int ifno;
@@ -534,7 +528,7 @@ USBDEVFS_RELEASEINTERFACE
 the number of the interface (bInterfaceNumber from descriptor); File
 modification time is not updated by this request.
 
-   **Warning**
+.. warning::
 
*No security check is made to ensure that the task which made
the claim is the one which is releasing it. This means that user
@@ -574,9 +568,7 @@ a time.
 
 USBDEVFS_BULK
 Issues a bulk read or write request to the device. The ioctl
-parameter is a pointer to this structure:
-
-::
+parameter is a pointer to this structure::
 
struct usbdevfs_bulktransfer {
unsigned int  ep;
@@ -606,9 +598,7 @@ USBDEVFS_CLEAR_HALT
 
 USBDEVFS_CONTROL
 Issues a control request to the device. The ioctl parameter points
-to a structure like this:
-
-::
+to a structure like this::
 
struct usbdevfs_ctrltransfer {
__u8   bRequestType;
@@ -638,7 +628,7 @@ USBDEVFS_RESET
 the reset, this rebinds all device interfaces. File modification
 time is not updated by this request.
 
-   **Warning**
+.. warning::
 
*Avoid using this call* until some usbcore bugs get fixed, since
it does not fully synchronize device, interface, and driver (not
@@ -646,9 +636,7 @@ USBDEVFS_RESET
 
 USBDEVFS_SETINTERFACE
 Sets the alternate setting for an interface. The ioctl parameter is
-a pointer to a structure like this:
-
-::
+a pointer to a structure like this::
 
struct usbdevfs_setinterface {
unsigned int  interface;
@@ -669,7 +657,7 @@ USBDEVFS_SETCONFIGURATION
 configuration (bConfigurationValue from descriptor). File
 modification time is not updated by this request.
 
-   **Warning**
+.. warning::
 
*Avoid using this call* until some usbcore bugs get fixed, since
it does not fully synchronize device, interface, and driver (not
@@ -702,9 +690,7 @@ When usbfs returns these urbs, the status value is updated, 
and the
 buffer may have been modified. Exc

[PATCH v2 06/22] writing_usb_driver.rst: Enrich its ReST representation

[Mauro Carvalho Chehab]

The pandoc conversion is not perfect. Do handwork in order to:

- add a title to this chapter;
- adjust function and struct references;
- use monospaced fonts for C code names;
- some other minor adjustments to make it better to read in
  text mode and in html.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../driver-api/usb/writing_usb_driver.rst  | 182 ++---
 1 file changed, 82 insertions(+), 100 deletions(-)

diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst 
b/Documentation/driver-api/usb/writing_usb_driver.rst
index c18dbd74152b..69f077dcdb78 100644
--- a/Documentation/driver-api/usb/writing_usb_driver.rst
+++ b/Documentation/driver-api/usb/writing_usb_driver.rst
@@ -1,3 +1,5 @@
+.. _writing-usb-driver:
+
 ==
 Writing USB Device Drivers
 ==
@@ -48,25 +50,23 @@ The first thing a Linux USB driver needs to do is register 
itself with
 the Linux USB subsystem, giving it some information about which devices
 the driver supports and which functions to call when a device supported
 by the driver is inserted or removed from the system. All of this
-information is passed to the USB subsystem in the usb_driver structure.
-The skeleton driver declares a usb_driver as:
-
-::
+information is passed to the USB subsystem in the :c:type:`usb_driver`
+structure. The skeleton driver declares a :c:type:`usb_driver` as::
 
 static struct usb_driver skel_driver = {
-.name= "skeleton",
-.probe   = skel_probe,
-.disconnect  = skel_disconnect,
-.fops= &skel_fops,
-.minor   = USB_SKEL_MINOR_BASE,
-.id_table= skel_table,
+   .name= "skeleton",
+   .probe   = skel_probe,
+   .disconnect  = skel_disconnect,
+   .fops= &skel_fops,
+   .minor   = USB_SKEL_MINOR_BASE,
+   .id_table= skel_table,
 };
 
 
 The variable name is a string that describes the driver. It is used in
 informational messages printed to the system log. The probe and
 disconnect function pointers are called when a device that matches the
-information provided in the id_table variable is either seen or
+information provided in the ``id_table`` variable is either seen or
 removed.
 
 The fops and minor variables are optional. Most USB drivers hook into
@@ -76,78 +76,70 @@ subsystem, and any user-space interactions are provided 
through that
 interface. But for drivers that do not have a matching kernel subsystem,
 such as MP3 players or scanners, a method of interacting with user space
 is needed. The USB subsystem provides a way to register a minor device
-number and a set of file_operations function pointers that enable this
-user-space interaction. The skeleton driver needs this kind of
+number and a set of :c:type:`file_operations` function pointers that enable
+this user-space interaction. The skeleton driver needs this kind of
 interface, so it provides a minor starting number and a pointer to its
-file_operations functions.
+:c:type:`file_operations` functions.
 
-The USB driver is then registered with a call to usb_register, usually
-in the driver's init function, as shown here:
-
-::
+The USB driver is then registered with a call to :c:func:`usb_register`,
+usually in the driver's init function, as shown here::
 
 static int __init usb_skel_init(void)
 {
-int result;
+   int result;
 
-/* register this driver with the USB subsystem */
-result = usb_register(&skel_driver);
-if (result < 0) {
-err("usb_register failed for the "__FILE__ "driver."
-"Error number %d", result);
-return -1;
-}
+   /* register this driver with the USB subsystem */
+   result = usb_register(&skel_driver);
+   if (result < 0) {
+   err("usb_register failed for the "__FILE__ "driver."
+   "Error number %d", result);
+   return -1;
+   }
 
-return 0;
+   return 0;
 }
 module_init(usb_skel_init);
 
 
 When the driver is unloaded from the system, it needs to deregister
-itself with the USB subsystem. This is done with the usb_deregister
-function:
-
-::
+itself with the USB subsystem. This is done with the :c:func:`usb_deregister`
+function::
 
 static void __exit usb_skel_exit(void)
 {
-/* deregister this driver with the USB subsystem */
-usb_deregister(&skel_driver);
+   /* deregister this driver with the USB subsystem */
+   usb_deregister(&skel_driver);
 }
 module_exit(usb_skel_exit);
 
 
 To enable the linux-hotplug system to load the driver automatically when
-the device is plugged in, you need to create a MODULE_DEVICE_TABLE.
+the device is plugged in, you need to create a ``MODULE_DEVICE_TABLE``.
 The following 

[PATCH v2 10/22] usb/callbacks.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core functions. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../callbacks.txt => driver-api/usb/callbacks.rst} | 61 +++---
 Documentation/driver-api/usb/index.rst |  1 +
 2 files changed, 43 insertions(+), 19 deletions(-)
 rename Documentation/{usb/callbacks.txt => driver-api/usb/callbacks.rst} (78%)

diff --git a/Documentation/usb/callbacks.txt 
b/Documentation/driver-api/usb/callbacks.rst
similarity index 78%
rename from Documentation/usb/callbacks.txt
rename to Documentation/driver-api/usb/callbacks.rst
index 9e85846bdb98..93a8d53e27e7 100644
--- a/Documentation/usb/callbacks.txt
+++ b/Documentation/driver-api/usb/callbacks.rst
@@ -1,3 +1,6 @@
+USB core callbacks
+~~
+
 What callbacks will usbcore do?
 ===
 
@@ -11,30 +14,42 @@ The callbacks defined in the driver structure are:
 
 1. Hotplugging callbacks:
 
- * @probe: Called to see if the driver is willing to manage a particular
- * interface on a device.
- * @disconnect: Called when the interface is no longer accessible, usually
- * because its device has been (or is being) disconnected or the
- * driver module is being unloaded.
+ - @probe:
+   Called to see if the driver is willing to manage a particular
+   interface on a device.
+
+ - @disconnect:
+   Called when the interface is no longer accessible, usually
+   because its device has been (or is being) disconnected or the
+   driver module is being unloaded.
 
 2. Odd backdoor through usbfs:
 
- * @ioctl: Used for drivers that want to talk to userspace through
- * the "usbfs" filesystem.  This lets devices provide ways to
- * expose information to user space regardless of where they
- * do (or don't) show up otherwise in the filesystem.
+ - @ioctl:
+   Used for drivers that want to talk to userspace through
+   the "usbfs" filesystem.  This lets devices provide ways to
+   expose information to user space regardless of where they
+   do (or don't) show up otherwise in the filesystem.
 
 3. Power management (PM) callbacks:
 
- * @suspend: Called when the device is going to be suspended.
- * @resume: Called when the device is being resumed.
- * @reset_resume: Called when the suspended device has been reset instead
- * of being resumed.
+ - @suspend:
+   Called when the device is going to be suspended.
+
+ - @resume:
+   Called when the device is being resumed.
+
+ - @reset_resume:
+   Called when the suspended device has been reset instead
+   of being resumed.
 
 4. Device level operations:
 
- * @pre_reset: Called when the device is about to be reset.
- * @post_reset: Called after the device has been reset
+ - @pre_reset:
+   Called when the device is about to be reset.
+
+ - @post_reset:
+   Called after the device has been reset
 
 The ioctl interface (2) should be used only if you have a very good
 reason. Sysfs is preferred these days. The PM callbacks are covered
@@ -58,7 +73,9 @@ an interface. A driver's bond to an interface is exclusive.
 The probe() callback
 
 
-int (*probe) (struct usb_interface *intf,
+::
+
+  int (*probe) (struct usb_interface *intf,
const struct usb_device_id *id);
 
 Accept or decline an interface. If you accept the device return 0,
@@ -75,7 +92,9 @@ initialisation that doesn't take too long is a good idea here.
 The disconnect() callback
 -
 
-void (*disconnect) (struct usb_interface *intf);
+::
+
+  void (*disconnect) (struct usb_interface *intf);
 
 This callback is a signal to break any connection with an interface.
 You are not allowed any IO to a device after returning from this
@@ -93,7 +112,9 @@ Device level callbacks
 pre_reset
 -
 
-int (*pre_reset)(struct usb_interface *intf);
+::
+
+  int (*pre_reset)(struct usb_interface *intf);
 
 A driver or user space is triggering a reset on the device which
 contains the interface passed as an argument. Cease IO, wait for all
@@ -107,7 +128,9 @@ are in atomic context.
 post_reset
 --
 
-int (*post_reset)(struct usb_interface *intf);
+::
+
+  int (*post_reset)(struct usb_interface *intf);
 
 The reset has completed.  Restore any saved device state and begin
 using the device again.
diff --git a/Documentation/driver-api/usb/index.rst 
b/Documentation/driver-api/usb/index.rst
index 6fe7611f7332..441c5dacdf27 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -8,6 +8,7 @@ Linux USB API
gadget
anchors
bulk-streams
+   callbacks
writing_usb_driver
writing_musb_glue_layer
 
-- 
2.9.3

--
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 15/22] usb/persist.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core features. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/index.rst |  1 +
 .../persist.txt => driver-api/usb/persist.rst} | 22 +-
 2 files changed, 14 insertions(+), 9 deletions(-)
 rename Documentation/{usb/persist.txt => driver-api/usb/persist.rst} (94%)

diff --git a/Documentation/driver-api/usb/index.rst 
b/Documentation/driver-api/usb/index.rst
index 43f0a8b72b11..3f08cb5d5feb 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -12,6 +12,7 @@ Linux USB API
dma
power-management
hotplug
+   persist
error-codes
writing_usb_driver
writing_musb_glue_layer
diff --git a/Documentation/usb/persist.txt 
b/Documentation/driver-api/usb/persist.rst
similarity index 94%
rename from Documentation/usb/persist.txt
rename to Documentation/driver-api/usb/persist.rst
index 35d70eda9ad6..ea1b43f0559e 100644
--- a/Documentation/usb/persist.txt
+++ b/Documentation/driver-api/usb/persist.rst
@@ -1,11 +1,12 @@
-   USB device persistence during system suspend
+USB device persistence during system suspend
+
 
-  Alan Stern 
+:Author: Alan Stern 
+:Date: September 2, 2006 (Updated February 25, 2008)
 
-   September 2, 2006 (Updated February 25, 2008)
 
-
-   What is the problem?
+What is the problem?
+
 
 According to the USB specification, when a USB bus is suspended the
 bus must continue to supply suspend current (around 1-5 mA).  This
@@ -63,7 +64,8 @@ suspended -- but it will crash as soon as it wakes up, which 
isn't
 much better.)
 
 
-   What is the solution?
+What is the solution?
+=
 
 The kernel includes a feature called USB-persist.  It tries to work
 around these issues by allowing the core USB device data structures to
@@ -99,7 +101,7 @@ now a good and happy place.
 
 Note that the "USB-persist" feature will be applied only to those
 devices for which it is enabled.  You can enable the feature by doing
-(as root):
+(as root)::
 
echo 1 >/sys/bus/usb/devices/.../power/persist
 
@@ -110,7 +112,8 @@ doesn't even exist, so you only have to worry about setting 
it for
 devices where it really matters.
 
 
-   Is this the best solution?
+Is this the best solution?
+==
 
 Perhaps not.  Arguably, keeping track of mounted filesystems and
 memory mappings across device disconnects should be handled by a
@@ -130,7 +133,8 @@ just mass-storage devices.  It might turn out to be equally 
useful for
 other device types, such as network interfaces.
 
 
-   WARNING: USB-persist can be dangerous!!
+WARNING: USB-persist can be dangerous!!
+===
 
 When recovering an interrupted power session the kernel does its best
 to make sure the USB device hasn't been changed; that is, the same
-- 
2.9.3

--
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/22] usb/power-management.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core functions. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/index.rst |   1 +
 .../usb/power-management.rst}  | 404 +++--
 2 files changed, 214 insertions(+), 191 deletions(-)
 rename Documentation/{usb/power-management.txt => 
driver-api/usb/power-management.rst} (69%)

diff --git a/Documentation/driver-api/usb/index.rst 
b/Documentation/driver-api/usb/index.rst
index 441c5dacdf27..23c76c17fc19 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -9,6 +9,7 @@ Linux USB API
anchors
bulk-streams
callbacks
+   power-management
writing_usb_driver
writing_musb_glue_layer
 
diff --git a/Documentation/usb/power-management.txt 
b/Documentation/driver-api/usb/power-management.rst
similarity index 69%
rename from Documentation/usb/power-management.txt
rename to Documentation/driver-api/usb/power-management.rst
index 00e706997130..c068257f6d27 100644
--- a/Documentation/usb/power-management.txt
+++ b/Documentation/driver-api/usb/power-management.rst
@@ -1,10 +1,12 @@
-   Power Management for USB
+.. _usb-power-management:
 
-Alan Stern 
-
-  Last-updated: February 2014
+Power Management for USB
+
 
+:Author: Alan Stern 
+:Date: Last-updated: February 2014
 
+..
Contents:
-
* What is Power Management?
@@ -25,14 +27,14 @@
* Suggested Userspace Port Power Policy
 
 
-   What is Power Management?
-   -
+What is Power Management?
+-
 
 Power Management (PM) is the practice of saving energy by suspending
 parts of a computer system when they aren't being used.  While a
-component is "suspended" it is in a nonfunctional low-power state; it
+component is ``suspended`` it is in a nonfunctional low-power state; it
 might even be turned off completely.  A suspended component can be
-"resumed" (returned to a functional full-power state) when the kernel
+``resumed`` (returned to a functional full-power state) when the kernel
 needs to use it.  (There also are forms of PM in which components are
 placed in a less functional but still usable state instead of being
 suspended; an example would be reducing the CPU's clock rate.  This
@@ -44,22 +46,25 @@ device is turned off while the system as a whole remains 
running, we
 call it a "dynamic suspend" (also known as a "runtime suspend" or
 "selective suspend").  This document concentrates mostly on how
 dynamic PM is implemented in the USB subsystem, although system PM is
-covered to some extent (see Documentation/power/*.txt for more
+covered to some extent (see ``Documentation/power/*.txt`` for more
 information about system PM).
 
-System PM support is present only if the kernel was built with CONFIG_SUSPEND
-or CONFIG_HIBERNATION enabled.  Dynamic PM support for USB is present whenever
-the kernel was built with CONFIG_PM enabled.
+System PM support is present only if the kernel was built with
+``CONFIG_SUSPEND`` or ``CONFIG_HIBERNATION`` enabled.  Dynamic PM support
+
+for USB is present whenever
+the kernel was built with ``CONFIG_PM`` enabled.
 
 [Historically, dynamic PM support for USB was present only if the
-kernel had been built with CONFIG_USB_SUSPEND enabled (which depended on
-CONFIG_PM_RUNTIME).  Starting with the 3.10 kernel release, dynamic PM support
-for USB was present whenever the kernel was built with CONFIG_PM_RUNTIME
-enabled.  The CONFIG_USB_SUSPEND option had been eliminated.]
+kernel had been built with ``CONFIG_USB_SUSPEND`` enabled (which depended on
+``CONFIG_PM_RUNTIME``).  Starting with the 3.10 kernel release, dynamic PM
+support for USB was present whenever the kernel was built with
+``CONFIG_PM_RUNTIME`` enabled.  The ``CONFIG_USB_SUSPEND`` option had been
+eliminated.]
 
 
-   What is Remote Wakeup?
-   --
+What is Remote Wakeup?
+--
 
 When a device has been suspended, it generally doesn't resume until
 the computer tells it to.  Likewise, if the entire computer has been
@@ -76,8 +81,8 @@ event.  Examples include a suspended keyboard resuming when a 
key is
 pressed, or a suspended USB hub resuming when a device is plugged in.
 
 
-   When is a USB device idle?
-   --
+When is a USB device idle?
+--
 
 A device is idle whenever the kernel thinks it's not busy doing
 anything important and thus is a candidate for being suspended.  The
@@ -92,11 +97,11 @@ If a USB device has no driver, its usbfs file isn't open, 
and it isn't
 being accessed through sysfs, then it definitely is idle.
 
 
-   Forms of dynamic PM
-   ---
+Forms of dynamic PM
+---
 
 Dynamic suspends occur when the kernel decides to suspend an idle
-device.  This is c

[PATCH v2 14/22] usb/hotplug.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core features. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../hotplug.txt => driver-api/usb/hotplug.rst} | 66 --
 Documentation/driver-api/usb/index.rst |  1 +
 2 files changed, 37 insertions(+), 30 deletions(-)
 rename Documentation/{usb/hotplug.txt => driver-api/usb/hotplug.rst} (76%)

diff --git a/Documentation/usb/hotplug.txt 
b/Documentation/driver-api/usb/hotplug.rst
similarity index 76%
rename from Documentation/usb/hotplug.txt
rename to Documentation/driver-api/usb/hotplug.rst
index 5b243f315b2c..79663e653ca1 100644
--- a/Documentation/usb/hotplug.txt
+++ b/Documentation/driver-api/usb/hotplug.rst
@@ -1,4 +1,9 @@
-LINUX HOTPLUGGING
+USB hotplugging
+~~~
+
+Linux Hotplugging
+=
+
 
 In hotpluggable busses like USB (and Cardbus PCI), end-users plug devices
 into the bus with power on.  In most cases, users expect the devices to become
@@ -30,11 +35,11 @@ Because some of those actions rely on information about 
drivers (metadata)
 that is currently available only when the drivers are dynamically linked,
 you get the best hotplugging when you configure a highly modular system.
 
+Kernel Hotplug Helper (``/sbin/hotplug``)
+=
 
-KERNEL HOTPLUG HELPER (/sbin/hotplug)
-
-There is a kernel parameter: /proc/sys/kernel/hotplug, which normally
-holds the pathname "/sbin/hotplug".  That parameter names a program
+There is a kernel parameter: ``/proc/sys/kernel/hotplug``, which normally
+holds the pathname ``/sbin/hotplug``.  That parameter names a program
 which the kernel may invoke at various times.
 
 The /sbin/hotplug program can be invoked by any subsystem as part of its
@@ -51,26 +56,26 @@ Hotplug software and other resources is available at:
 Mailing list information is also available at that site.
 
 
---
+USB Policy Agent
+
 
-
-USB POLICY AGENT
-
-The USB subsystem currently invokes /sbin/hotplug when USB devices
+The USB subsystem currently invokes ``/sbin/hotplug`` when USB devices
 are added or removed from system.  The invocation is done by the kernel
 hub workqueue [hub_wq], or else as part of root hub initialization
 (done by init, modprobe, kapmd, etc).  Its single command line parameter
 is the string "usb", and it passes these environment variables:
 
-ACTION ... "add", "remove"
-PRODUCT ... USB vendor, product, and version codes (hex)
-TYPE ... device class codes (decimal)
-INTERFACE ... interface 0 class codes (decimal)
+== 
+ACTION ``add``, ``remove``
+PRODUCTUSB vendor, product, and version codes (hex)
+TYPE   device class codes (decimal)
+INTERFACE  interface 0 class codes (decimal)
+== 
 
 If "usbdevfs" is configured, DEVICE and DEVFS are also passed.  DEVICE is
 the pathname of the device, and is useful for devices with multiple and/or
 alternate interfaces that complicate driver selection.  By design, USB
-hotplugging is independent of "usbdevfs":  you can do most essential parts
+hotplugging is independent of ``usbdevfs``:  you can do most essential parts
 of USB device setup without using that filesystem, and without running a
 user mode daemon to detect changes in system configuration.
 
@@ -79,19 +84,20 @@ modules, and can invoke driver-specific setup scripts.  The 
newest ones
 leverage USB module-init-tools support.  Later agents might unload drivers.
 
 
-USB MODUTILS SUPPORT
+USB Modutils Support
+
 
-Current versions of module-init-tools will create a "modules.usbmap" file
-which contains the entries from each driver's MODULE_DEVICE_TABLE.  Such
+Current versions of module-init-tools will create a ``modules.usbmap`` file
+which contains the entries from each driver's ``MODULE_DEVICE_TABLE``.  Such
 files can be used by various user mode policy agents to make sure all the
 right driver modules get loaded, either at boot time or later.
 
-See  for full information about such table entries; or look
+See ``linux/usb.h`` for full information about such table entries; or look
 at existing drivers.  Each table entry describes one or more criteria to
 be used when matching a driver to a device or class of devices.  The
 specific criteria are identified by bits set in "match_flags", paired
 with field values.  You can construct the criteria directly, or with
-macros such as these, and use driver_info to store more information.
+macros such as these, and use driver_info to store more information::
 
 USB_DEVICE (vendorId, productId)
... matching devices with specified vendor and product ids
@@ -103,7 +109,7 @@ macros such as these, and use driver_info to store more 
information.
... matching specified device class info
 
 A short example, for a driver that supports 

Re: [PATCH 22/22] usb: document that URB transfer_buffer should be aligned

[Mauro Carvalho Chehab]

Em Thu, 30 Mar 2017 12:38:42 +0300
Laurent Pinchart  escreveu:

> Hi Mauro,
> 
> On Wednesday 29 Mar 2017 22:06:33 Mauro Carvalho Chehab wrote:
> > Em Thu, 30 Mar 2017 01:15:27 +0300 Laurent Pinchart escreveu:  
> > > On Wednesday 29 Mar 2017 15:54:21 Mauro Carvalho Chehab wrote:  
> > > > Several host controllers, commonly found on ARM, like dwc2,
> > > > require buffers that are CPU-word aligned for they to work.
> > > > 
> > > > Failing to do that will cause random troubles at the caller
> > > > drivers, causing them to fail.
> > > > 
> > > > Document it.
> > > > 
> > > > Signed-off-by: Mauro Carvalho Chehab 
> > > > ---
> > > > 
> > > >  Documentation/driver-api/usb/URB.rst | 18 ++
> > > >  drivers/usb/core/message.c   | 15 +++
> > > >  include/linux/usb.h  | 18 ++
> > > >  3 files changed, 51 insertions(+)
> > > > 
> > > > diff --git a/Documentation/driver-api/usb/URB.rst
> > > > b/Documentation/driver-api/usb/URB.rst index d9ea6a3996e7..b83b557e9891
> > > > 100644
> > > > --- a/Documentation/driver-api/usb/URB.rst
> > > > +++ b/Documentation/driver-api/usb/URB.rst
> > > > @@ -274,6 +274,24 @@ If you specify your own start frame, make sure it's
> > > > several frames in advance of the current frame.  You might want this
> > > > model
> > > > if you're synchronizing ISO data with some other event stream.
> > > > 
> > > > +.. note::
> > > > +
> > > > +   Several host drivers require that the ``transfer_buffer`` to be
> > > > aligned
> > > > +   with the CPU word size (e. g. DWORD for 32 bits, QDWORD for 64
> > > > bits).  
> > > 
> > > Is it the CPU word size or the DMA transfer size ? I assume the latter,
> > > and I wouldn't be surprised if the alignment requirement was 32-bit on at
> > > least some of the 64-bit platforms.  
> > 
> > Yeah, it is actually the DMA transfer size. Yet, worse case scenario is that
> > the DMA transfer size to be 64 bits on 64 bits CPU.
> >   
> > > > +   It is up to USB drivers should ensure that they'll only pass buffers
> > > > +   with such alignments.
> > > > +
> > > > +   Please also notice that, due to such restriction, the host driver  
> > > 
> > > s/notice/note/ (and below as well) ?  
> > 
> > OK.
> >   
> > > > +   may also override PAD bytes at the end of the ``transfer_buffer``,
> > > > up to the
> > > > +   size of the CPU word.  
> > > 
> > > "May" is quite weak here. If some host controller drivers require buffers
> > > to be aligned, then it's an API requirement, and all buffers must be
> > > aligned. I'm not even sure I would mention that some host drivers require
> > > it, I think we should just state that the API requires buffers to be
> > > aligned.  
> > 
> > What I'm trying to say here is that, on a 32-bits system, if the driver do
> > a USB_DIR_IN transfer using some code similar to:
> > 
> > size = 4;
> > buffer = kmalloc(size, GFP_KERNEL);
> > 
> > usb_control_msg(udev, pipe, req, type, val, idx, buffer + 2, 2,   
> timeout);
> > usb_control_msg(udev, pipe, req, type, val, idx, buffer, size,   
> timeout);
> > 
> > Drivers like dwc2 will mess with the buffer.
> > 
> > The first transfer will actually work, due to a workaround inside the
> > driver that will create a temporary DWORD-aligned buffer, avoiding it
> > to go past the buffer.
> > 
> > However, the second transfer will destroy the data received from the
> > first usb_control_msg(), as it will write 4 bytes at the buffer.
> > 
> > Not all drivers would do that, though.
> > 
> > Please notice that, as kmalloc will always return a CPU-aligned buffer,
> > if the client do something like:
> > 
> > size = 2;
> > buffer = kmalloc(size, GFP_KERNEL);
> > 
> > usb_control_msg(udev, pipe, req, type, val, idx, buffer, 2, timeout);
> > 
> > What happens there is that the DMA engine will still write 4 bytes at
> > the buffer, but the 2 bytes that go past the end of buffer will be
> > written on a memory that will never be used.  
> 
> I understand that, but stating that host controller drivers "may" do this 
> won't help much. If they *may*, all USB device drivers *must* align buffers 
> correctly. That's the part that needs to be documented. Let's not confuse 
> developers by only stating that something may happened, let's be clear and 
> tell what they must do.

Ok, rewrote the entire text. Please see if the new version
works better.

> 
> > > > +   Please notice that ancillary routines that transfer URBs, like
> > > > +   usb_control_msg() also have such restriction.
> > > > +
> > > > +   Such word alignment condition is normally ensured if the buffer is
> > > > +   allocated with kmalloc(), but this may not be the case if the driver
> > > > +   allocates a bigger buffer and point to a random place inside it.
> > > > +
> > > > 
> > > >  How to start interrupt (INT) transfers?
> > > >  ===
> > > > 
> > > > diff --git a/drivers/usb/core/message.c b/drivers/usb/core/messa

Re: [PATCH v2 01/22] tmplcvt: make the tool more robust

[Mauro Carvalho Chehab]

Em Thu, 30 Mar 2017 07:45:35 -0300
Mauro Carvalho Chehab  escreveu:

> Currently, the script just assumes to be called at
> Documentation/sphinx/. Change it to work on any directory,
> and make it abort if something gets wrong.
> 
> Also, be sure that both parameters are specified.
> 
> That should avoid troubles like this:
> 
> $ Documentation/sphinx/tmplcvt Documentation/DocBook/writing_usb_driver.tmpl
> sed: couldn't open file convert_template.sed: No such file or directory
> 
> Signed-off-by: Mauro Carvalho Chehab 

Forgot to mention. The entire USB book, after this patch series,
generated with Sphinx 1.4.9, can be seen, in HTML, at:

http://www.infradead.org/~mchehab/kernel_docs/driver-api/usb/index.html

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 22/22] usb: document that URB transfer_buffer should be aligned

[David Laight]

From: Mauro Carvalho Chehab
> Sent: 30 March 2017 11:28
...
> While debugging this issue, I saw *a lot* of network-generated URB
> traffic from RPi3 Ethernet port drivers that were using non-aligned
> buffers and were subject to the temporary buffer conversion.

Buffers from the network stack will almost always be 4n+2 aligned.
Receive data being fed into the network stack really needs to be
4n=2 aligned.

The USB stack almost certainly has to live with that.

If the USB ethernet device doesn't have two bytes of 'pad' before
the frame data (destination MAC address) then you have to solve
the problem within the USB stack.

For transmits it might be possible to send an initial 2 byte fragment
from a separate buffer - but only if arbitrary fragment sizes are
allowed.
A normal USB3 controller should allow this - but you have to be very
careful about what happens at the end of the ring.

David


--
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/22] docs-rst: convert usb docbooks to ReST

[Markus Heiser]

Am 30.03.2017 um 12:12 schrieb Mauro Carvalho Chehab :
>>> At this point I'd just go with what Mauro has. It's here now, as
>>> patches. We've seen from the GPU documentation that polishing the
>>> one-time initial conversion is, after a point, wasted effort. Having the
>>> documentation in rst attracts more attention and contributions, and any
>>> remaining issues will get ironed out in rst.  
>> 
>> I totally agree with you (I have never said something different)
>> 
>>> This is also one reason I'm in favor of just bulk converting the rest of
>>> the .tmpl files using Documentation/sphinx/tmplcvt, get rid of DocBook
>>> and be done with it, and have the crowds focus on rst.  
>> 
>> I also agree with that. The tmplcvt script is good enough for this task,
>> the dbxml2rst tool is more elaborate.
> 
> I like the idea of a bulk conversion. My personal preference here is to
> use the tmplcvt for such task, at least for simple books like the ones
> I converted from USB.
> 
> The advantage is that it places everything on a single rst file, with,
> IMHO, works best for books that aren't too complex.
> Of course, it doesn't hurt to compare the end result with dbxml2rst
> and see if something could be improved.

If it helps ... dbxml2rst also supports single file conversion  ... I updated:

  
https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated

There you find a folder for each DocBook conversion with only one rst file 
(index.rst)
in .. If you like, use it for comparison.

-- 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 02/22] docs-rst: convert usb docbooks to ReST

[Markus Heiser]

Am 30.03.2017 um 13:17 schrieb Markus Heiser :
> 
> If it helps ... dbxml2rst also supports single file conversion  ... I updated:
> 
>  
> https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated
> 
> There you find a folder for each DocBook conversion with only one rst file 
> (index.rst)
> in .. If you like, use it for comparison.

Forget to mentioning one of the main benefits: 

The conversion with dbxml2rst produce tables with directive ".. flat-table::"
instead of building ASCII tables (like pandoc does).

-- 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 v2 01/22] tmplcvt: make the tool more robust

[Jani Nikula]

On Thu, 30 Mar 2017, Mauro Carvalho Chehab  wrote:
> Currently, the script just assumes to be called at
> Documentation/sphinx/. Change it to work on any directory,
> and make it abort if something gets wrong.
>
> Also, be sure that both parameters are specified.
>
> That should avoid troubles like this:
>
> $ Documentation/sphinx/tmplcvt Documentation/DocBook/writing_usb_driver.tmpl
> sed: couldn't open file convert_template.sed: No such file or directory
>
> Signed-off-by: Mauro Carvalho Chehab 
> ---
>  Documentation/sphinx/tmplcvt | 13 +++--
>  1 file changed, 11 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/sphinx/tmplcvt b/Documentation/sphinx/tmplcvt
> index 909a73065e0a..31df8eb7feca 100755
> --- a/Documentation/sphinx/tmplcvt
> +++ b/Documentation/sphinx/tmplcvt
> @@ -7,13 +7,22 @@
>  # fix \_
>  # title line?
>  #
> +set -eu
> +
> +if [ "$2" == "" ]; then

if [ "$#" != "2" ]; then

otherwise with set -u you'll get unbound variable error if you don't
provide $2.

BR,
Jani.

> + echo "$0  "
> + exit
> +fi
> +
> +DIR=$(dirname $0)
>  
>  in=$1
>  rst=$2
>  tmp=$rst.tmp
>  
>  cp $in $tmp
> -sed --in-place -f convert_template.sed $tmp
> +sed --in-place -f $DIR/convert_template.sed $tmp
>  pandoc -s -S -f docbook -t rst -o $rst $tmp
> -sed --in-place -f post_convert.sed $rst
> +sed --in-place -f $DIR/post_convert.sed $rst
>  rm $tmp
> +echo "book writen to $rst"

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

Re: [PATCH 22/22] usb: document that URB transfer_buffer should be aligned

[Laurent Pinchart]

Hi Mauro,

On Thursday 30 Mar 2017 07:28:00 Mauro Carvalho Chehab wrote:
> Em Thu, 30 Mar 2017 12:34:32 +0300 Laurent Pinchart escreveu:
> > On Thursday 30 Mar 2017 10:11:31 Oliver Neukum wrote:
> >> Am Donnerstag, den 30.03.2017, 01:15 +0300 schrieb Laurent Pinchart:
>  +   may also override PAD bytes at the end of the
>  ``transfer_buffer``, up to the
>  +   size of the CPU word.
> >>> 
> >>> "May" is quite weak here. If some host controller drivers require
> >>> buffers to be aligned, then it's an API requirement, and all buffers
> >>> must be aligned. I'm not even sure I would mention that some host
> >>> drivers require it, I think we should just state that the API requires
> >>> buffers to be aligned.
> >> 
> >> That effectively changes the API. Many network drivers are written with
> >> the assumption that any contiguous buffer is valid. In fact you could
> >> argue that those drivers are buggy and must use bounce buffers in those
> >> cases.
> 
> Blaming the dwc2 driver was my first approach, but such patch got nacked ;)
> 
> Btw, the dwc2 driver has a routine that creates a temporary buffer if the
> buffer pointer is not DWORD aligned. My first approach were to add
> a logic there to also use the temporary buffer if the buffer size is
> not DWORD aligned:
>   https://patchwork.linuxtv.org/patch/40093/
> 
> While debugging this issue, I saw *a lot* of network-generated URB
> traffic from RPi3 Ethernet port drivers that were using non-aligned
> buffers and were subject to the temporary buffer conversion.
> 
> My understanding here is that having a temporary bounce buffer sucks,
> as the performance and latency are affected. So, I see the value of
> adding this constraint to the API, pushing the task of getting
> aligned buffers to the USB drivers,

This could however degrade performances when the HCD can handle unaligned 
buffers.

> but you're right: that means a lot of work, as all USB drivers should be
> reviewed.

If we decide in the end to push the constraint on the USB device driver side, 
then the dwc2 HCD driver should return an error when the buffer isn't 
correctly aligned.

> Btw, I'm a lot more concerned about USB storage drivers. When I was
> discussing about this issue at the #raspberrypi-devel IRC channel,
> someone complained that, after switching from the RPi downstream Kernel
> to upstream, his USB data storage got corrupted. Well, if the USB
> storage drivers also assume that the buffer can be continuous,
> that can corrupt data.
> 
> That's why I think that being verbose here is a good idea.
> 
> I'll rework on this patch to put more emphasis about this issue.
> 
> >> So we need to include the full story here.
> > 
> > I personally don't care much about whose side is responsible for handling
> > the alignment constraints, but I want it to be documented before "fixing"
> > any USB driver.

-- 
Regards,

Laurent Pinchart

--
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/22] docs-rst: convert usb docbooks to ReST

[Mauro Carvalho Chehab]

Em Thu, 30 Mar 2017 13:17:16 +0200
Markus Heiser  escreveu:

> Am 30.03.2017 um 12:12 schrieb Mauro Carvalho Chehab 
> :
> >>> At this point I'd just go with what Mauro has. It's here now, as
> >>> patches. We've seen from the GPU documentation that polishing the
> >>> one-time initial conversion is, after a point, wasted effort. Having the
> >>> documentation in rst attracts more attention and contributions, and any
> >>> remaining issues will get ironed out in rst.
> >> 
> >> I totally agree with you (I have never said something different)
> >>   
> >>> This is also one reason I'm in favor of just bulk converting the rest of
> >>> the .tmpl files using Documentation/sphinx/tmplcvt, get rid of DocBook
> >>> and be done with it, and have the crowds focus on rst.
> >> 
> >> I also agree with that. The tmplcvt script is good enough for this task,
> >> the dbxml2rst tool is more elaborate.  
> > 
> > I like the idea of a bulk conversion. My personal preference here is to
> > use the tmplcvt for such task, at least for simple books like the ones
> > I converted from USB.
> > 
> > The advantage is that it places everything on a single rst file, with,
> > IMHO, works best for books that aren't too complex.
> > Of course, it doesn't hurt to compare the end result with dbxml2rst
> > and see if something could be improved.  
> 
> If it helps ... dbxml2rst also supports single file conversion  ... I updated:
> 
>   
> https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated

Ok, I double-checked the results from dbxml2rst with pandoc (via
the script). Those are the differences after running the following commands:

$ wget 
https://raw.githubusercontent.com/return42/sphkerneldoc/master/Documentation/books_migrated/writing_usb_driver/index.rst
$ Documentation/sphinx/tmplcvt 
Documentation/DocBook/writing_usb_driver.tmpl writing_usb_driver.rst
$ diff -uprBw writing_usb_driver.rst index.rst 

1) Author data:

-:Author: Greg Kroah-Hartman
+:author:Kroah-Hartman Greg
+:address:   g...@kroah.com

dbxml2rst inverted the author's name.  It also added author's e-mail.

IMHO, it is better to not have email address there, as it could be
outdated, but this is just my personal preference.

2) dbxml2rst added a copyright information:

+**Copyright** 2001-2002 : Greg Kroah-Hartman

This is a good thing.

3) dbxml2rst added a GPL information.

IMHO, we should add just one GPL information, per hole book
(and not per converted file).

4) dbxml2rst created some references that won't be unique:

+.. _intro:

That's a bad thing, as I bet most converted documents will have "intro"
sections.

5) dbxml2rst use ".. code-block:: c" instead of "::"

I prefer using "::"

6) dbxml2rst appends a commentary at the end:

+.. 
--
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/dbxml2rst). The origin XML comes
+.. from the linux kernel:
+..
+..   http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git
+.. 
--

7) dbxml2rst did a worse job with URB conversions:

-USB Home Page: http://www.usb.org
+USB Home Page: `http://www.usb.org `__

So, in summary, at least for this document, the only thing good with
dbxml2rst was that it filled the copyright info.

Maybe for more complex documents, it would do a better job.

Yet, in order to standardize it everywhere, I guess the best would be to
produce copyright data like:

.. include:: 

:Copyright: |copy| 2001-2002 : Greg Kroah-Hartman

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 22/22] usb: document that URB transfer_buffer should be aligned

[Mauro Carvalho Chehab]

Em Thu, 30 Mar 2017 15:05:30 +0300
Laurent Pinchart  escreveu:

> Hi Mauro,
> 
> On Thursday 30 Mar 2017 07:28:00 Mauro Carvalho Chehab wrote:
> > Em Thu, 30 Mar 2017 12:34:32 +0300 Laurent Pinchart escreveu:  
> > > On Thursday 30 Mar 2017 10:11:31 Oliver Neukum wrote:  
> > >> Am Donnerstag, den 30.03.2017, 01:15 +0300 schrieb Laurent Pinchart:  
> >  +   may also override PAD bytes at the end of the
> >  ``transfer_buffer``, up to the
> >  +   size of the CPU word.  
> > >>> 
> > >>> "May" is quite weak here. If some host controller drivers require
> > >>> buffers to be aligned, then it's an API requirement, and all buffers
> > >>> must be aligned. I'm not even sure I would mention that some host
> > >>> drivers require it, I think we should just state that the API requires
> > >>> buffers to be aligned.  
> > >> 
> > >> That effectively changes the API. Many network drivers are written with
> > >> the assumption that any contiguous buffer is valid. In fact you could
> > >> argue that those drivers are buggy and must use bounce buffers in those
> > >> cases.  
> > 
> > Blaming the dwc2 driver was my first approach, but such patch got nacked ;)
> > 
> > Btw, the dwc2 driver has a routine that creates a temporary buffer if the
> > buffer pointer is not DWORD aligned. My first approach were to add
> > a logic there to also use the temporary buffer if the buffer size is
> > not DWORD aligned:
> > https://patchwork.linuxtv.org/patch/40093/
> > 
> > While debugging this issue, I saw *a lot* of network-generated URB
> > traffic from RPi3 Ethernet port drivers that were using non-aligned
> > buffers and were subject to the temporary buffer conversion.
> > 
> > My understanding here is that having a temporary bounce buffer sucks,
> > as the performance and latency are affected. So, I see the value of
> > adding this constraint to the API, pushing the task of getting
> > aligned buffers to the USB drivers,  
> 
> This could however degrade performances when the HCD can handle unaligned 
> buffers.

No, it won't degrade performance out there, except if the driver
would need to do double buffering due to such constraint. 

It will just waste memory.

> 
> > but you're right: that means a lot of work, as all USB drivers should be
> > reviewed.  
> 
> If we decide in the end to push the constraint on the USB device driver side, 
> then the dwc2 HCD driver should return an error when the buffer isn't 
> correctly aligned.

Yeah, with such constraint, either the HCD drivers or the USB core
should complain.

There is another option: to add a field, filled by te USB driver,
telling the core that the buffer is aligned, e. g. drivers would
be doing something like:

urb->transfer_buffer_align = 4;

Something similar could be filled by the HCD driver:

hc_driver->transfer_buffer_align = 4;

The core will then check if the alignment required by the HCD driver
is compatible with the buffer alignment ensured by the USB driver.
If it doesn't, then the core would create a temporary buffer for the
transfers.

No idea about how easy/hard would be to implement something like
that.

In such case, it could make sense to generate a warning that
the driver should be fixed, or that the performance would
decrease due to double-buffering.

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 22/22] usb: document that URB transfer_buffer should be aligned

[Oliver Neukum]

Am Donnerstag, den 30.03.2017, 07:28 -0300 schrieb Mauro Carvalho
Chehab:
> Em Thu, 30 Mar 2017 12:34:32 +0300
> Laurent Pinchart  escreveu:
> 
> > 

Hi,

> > > That effectively changes the API. Many network drivers are written with
> > > the assumption that any contiguous buffer is valid. In fact you could
> > > argue that those drivers are buggy and must use bounce buffers in those
> > > cases.
> 
> Blaming the dwc2 driver was my first approach, but such patch got nacked ;)

That I am afraid was a mistake in a certain sense. This belongs into
usbcore. It does not belong into controller drivers or device drivers.

> Btw, the dwc2 driver has a routine that creates a temporary buffer if the
> buffer pointer is not DWORD aligned. My first approach were to add
> a logic there to also use the temporary buffer if the buffer size is
> not DWORD aligned:
>   https://patchwork.linuxtv.org/patch/40093/
> 
> While debugging this issue, I saw *a lot* of network-generated URB
> traffic from RPi3 Ethernet port drivers that were using non-aligned 
> buffers and were subject to the temporary buffer conversion.
> 
> My understanding here is that having a temporary bounce buffer sucks,
> as the performance and latency are affected. So, I see the value of

If you need it, you need it. Doing this in the device driver isn't any
less problematic in terms of performance. The only thing we can do
is do it in a central place to avoid code duplication.

> adding this constraint to the API, pushing the task of getting 
> aligned buffers to the USB drivers, but you're right: that means a lot
> of work, as all USB drivers should be reviewed.

And it is wrong. To be blunt: The important drivers are EHCI and XHCI.
We must not degrade performance with them for the sake of controllers
with less capabilities.

> Btw, I'm a lot more concerned about USB storage drivers. When I was
> discussing about this issue at the #raspberrypi-devel IRC channel,
> someone complained that, after switching from the RPi downstream Kernel
> to upstream, his USB data storage got corrupted. Well, if the USB
> storage drivers also assume that the buffer can be continuous,
> that can corrupt data.
> 
> That's why I think that being verbose here is a good idea.

They do assume that.

> I'll rework on this patch to put more emphasis about this issue.

For now that is the best. But even in the medium term this sucks.
At a minimum controller drivers need to export what they can do.

Regards
Oliver

--
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 tip/master 2/3] kprobes: Allocate kretprobe instance if its free list is empty

[Masami Hiramatsu]

On Thu, 30 Mar 2017 08:53:32 +0200
Ingo Molnar  wrote:

> 
> * Masami Hiramatsu  wrote:
> 
> > > So this is something I missed while the original code was merged, but the 
> > > concept 
> > > looks a bit weird: why do we do any "allocation" while a handler is 
> > > executing?
> > > 
> > > That's fundamentally fragile. What's the maximum number of parallel 
> > > 'kretprobe_instance' required per kretprobe - one per CPU?
> > 
> > It depends on the place where we put the probe. If the probed function will 
> > be
> > blocked (yield to other tasks), then we need a same number of threads on
> > the system which can invoke the function. So, ultimately, it is same
> > as function_graph tracer, we need it for each thread.
> 
> So then put it into task_struct (assuming there's no 
> kretprobe-inside-kretprobe 
> nesting allowed).

No, that is possible to put several kretprobes on same thread, e.g.
the func1() is called from func2(), user can put kretprobes for each
function at same time.
So the possible solution is to allocate new return-stack for each task_struct,
and that is what the function-graph tracer did.

Anyway, I'm considering to integrate kretprobe_instance with the ret_stack.
It will increase memory usage for kretprobes, but can provide safer way
to allocate kretprobe_instance.

> There's just no way in hell we should be calling any complex 
> kernel function from kernel probes!

OK, so let's drop this, since it may easily cause deadlock... 


> I mean, think about it, a kretprobe can be installed in a lot of places, and 
> now 
> we want to call get_free_pages() from it?? This would add a massive amount of 
> fragility.

I thought it was safe because GFP_ATOMIC is safe at interrupt handler.

> Instrumentation must be _simple_, every patch that adds more complexity to 
> the 
> most fundamental code path of it should raise a red flag ...
> 
> So let's make this more robust, ok?

Yeah, in that case, I think Alban's patch is enough at this point since
it gives user to tune their kretprobe events not to be missed.

Thank you,

> 
> Thanks,
> 
>   Ingo


-- 
Masami Hiramatsu 
--
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 tip/master 2/3] kprobes: Allocate kretprobe instance if its free list is empty

[Alban Crequy]

On Thu, Mar 30, 2017 at 8:53 AM, Ingo Molnar  wrote:
>
> * Masami Hiramatsu  wrote:
>
>> > So this is something I missed while the original code was merged, but the 
>> > concept
>> > looks a bit weird: why do we do any "allocation" while a handler is 
>> > executing?
>> >
>> > That's fundamentally fragile. What's the maximum number of parallel
>> > 'kretprobe_instance' required per kretprobe - one per CPU?
>>
>> It depends on the place where we put the probe. If the probed function will 
>> be
>> blocked (yield to other tasks), then we need a same number of threads on
>> the system which can invoke the function. So, ultimately, it is same
>> as function_graph tracer, we need it for each thread.
>
> So then put it into task_struct (assuming there's no 
> kretprobe-inside-kretprobe
> nesting allowed). There's just no way in hell we should be calling any complex
> kernel function from kernel probes!

Some kprobes are called from an interruption context. We have a kprobe
on tcp_set_state() and this is sometimes called when the network card
receives a packet.

> I mean, think about it, a kretprobe can be installed in a lot of places, and 
> now
> we want to call get_free_pages() from it?? This would add a massive amount of
> fragility.
>
> Instrumentation must be _simple_, every patch that adds more complexity to the
> most fundamental code path of it should raise a red flag ...
>
> So let's make this more robust, ok?
>
> Thanks,
>
> Ingo

Thanks,
Alban
--
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 v5 6/9] coresight: add support for CPU debug module

[Leo Yan]

On Thu, Mar 30, 2017 at 10:00:30AM +0100, Suzuki K Poulose wrote:

[...]

> Leo,
> 
> Also, it would be good to restore the PRCR register back to the original state
> after we read the registers (if we changed them). I am exploring ways to make
> use of this feature on demand (e.g, tie it to sysrq-t or sysrq-l) and not just
> at panic time. So it would be good to have the state restored to not affect 
> the
> normal functioning even after dumping the registers.

Got it. Will take care for this.

Thanks,
Leo Yan

> PS: I have a small hack to hook this into a sysrq-x at runtime, but on a 
> second thought
> it is better not to consume the key and rather tie it to something which 
> already exist,
> as mentioned above.
> 
> Thanks
> Suzuki
--
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 22/22] usb: document that URB transfer_buffer should be aligned

[Alan Stern]

On Thu, 30 Mar 2017, Oliver Neukum wrote:

> > Btw, I'm a lot more concerned about USB storage drivers. When I was
> > discussing about this issue at the #raspberrypi-devel IRC channel,
> > someone complained that, after switching from the RPi downstream Kernel
> > to upstream, his USB data storage got corrupted. Well, if the USB
> > storage drivers also assume that the buffer can be continuous,
> > that can corrupt data.

> 
> They do assume that.

Wait a minute.  Where does that assumption occur?

And exactly what is the assumption?  Mauro wrote "the buffer can be 
continuous", but that is certainly not what he meant.

Alan Stern

--
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 22/22] usb: document that URB transfer_buffer should be aligned

[Mauro Carvalho Chehab]

Em Thu, 30 Mar 2017 10:26:32 -0400 (EDT)
Alan Stern  escreveu:

> On Thu, 30 Mar 2017, Oliver Neukum wrote:
> 
> > > Btw, I'm a lot more concerned about USB storage drivers. When I was
> > > discussing about this issue at the #raspberrypi-devel IRC channel,
> > > someone complained that, after switching from the RPi downstream Kernel
> > > to upstream, his USB data storage got corrupted. Well, if the USB
> > > storage drivers also assume that the buffer can be continuous,
> > > that can corrupt data.  
> 
> > 
> > They do assume that.  
> 
> Wait a minute.  Where does that assumption occur?
> 
> And exactly what is the assumption?  Mauro wrote "the buffer can be 
> continuous", but that is certainly not what he meant.

What I meant to say is that drivers like the uvcdriver (and maybe network and
usb-storage drivers) may allocate a big buffer and get data there on some
random order, e. g.: 

int get_from_buf_pos(char *buf, int pos, int size)
{
/* or an equivalent call to usb_submit_urb() */
usb_control_msg(..., buf + pos, size, ...);
}

some_function ()
{
...

chr *buf = kzalloc(4, GFP_KERNEL);

/* 
 * Access the bytes at the array on a random order, with random size,
 * Like:
 */
get_from_buf_pos(buf, 2, 2);/* should read 0x56, 0x78 */
get_from_buf_pos(buf, 0, 2);/* should read 0x12, 0x34 */

/*
 * the expected value for the buffer would be:
 *  { 0x12, 0x34, 0x56, 0x78 }
 */

E. g. they assume that the transfer URB can work with any arbitrary
pointer and size, without needing of pre-align them.

This doesn't work with HCD drivers like dwc2, as each USB_IN operation will
actually write 4 bytes to the buffer.

So, what happens, instead, is that each data transfer will get four
bytes. Due to a hack inside dwc2, with checks if the transfer_buffer
is DWORD aligned. So, the first transfer will do what's expected: it will
read 4 bytes to a temporary buffer, allocated inside the driver,
copying just two bytes to buf. So, after the first read, the
buffer content will be:

buf = { 0x00, x00, 0x56, 0x78 }

But, on the second read, it won't be using any temporary
buffer. So, instead of reading a 16-bits word (0x5678),
it will actually read 32 bits, with 16-bits with some random value,
causing a buffer overflow. E. g. buffer content will now be:

buf = { 0x12, x34, 0xde, 0xad }

In other words, the second transfer corrupted the data from the
first transfer.

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 v5 6/9] coresight: add support for CPU debug module

[Mathieu Poirier]

On 29 March 2017 at 19:59, Leo Yan  wrote:
> On Wed, Mar 29, 2017 at 10:55:35AM -0600, Mathieu Poirier wrote:
>
> [...]
>
>> > So this is why add "idle_constraint" as a central place to control
>> > power domain for CPU debug purpose and I also think this is more
>> > friendly for hardware design, e.g. some platforms can enable partial
>> > low power states to save power and avoid overheat after using this
>> > driver.
>> >
>> > How about you think for this?
>>
>> Like Sudeep pointed out we should concentrate on doing the right thing,
>> that is work with EDPRSR.PU, EDPRCR.COREPURQ and EDPRCR.CORENPDRQ.
>
> Agree, and I think we have aligned for this.
>
>> Anything outside of that becomes platform specific and can't be handled in
>> this driver.
>
> Sorry I argue a bit for this just want to make things more clear and
> if can have better method.
>
> Though the issue is platform specific, but the code is to seek common
> method to handle them. So the driver has no any platform specific code.

Seeking a common way to handle platform specific problems doesn't
scale and will never be encompassing.  There will always be a quirk
somewhere to deal with, hence the idea of keeping things separate.

>
> I read again for Suziki's suggestion: "4) Should document the fact that,
> on some platforms, the user may have to disable CPUidle explicitly to
> get the driver working. But let us not make it the default. The user
> with a not so ideal platform could add "nohlt" and get it working."

Suzuki and I are expressing the same view using different words.

>
> So I'm not strong to resist and if this is alignment yet, I should
> document well for this but doesn't handle it in driver (keep driver
> simple).
>
> Thanks,
> Leo Yan
--
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 v5 6/9] coresight: add support for CPU debug module

[Sudeep Holla]

On 29/03/17 15:56, Mike Leach wrote:

[...]
> 
> No - EDPRCR_COREPURQ and EDPRCR_CORENPDRQ have different semantics and 
> purposes
> 
> EDPRCR_COREPURQ is in the debug power domain an is tied to an external
> debug request that should be an input to the external (to the PE)
> system power controller.
> The requirement is that the system power controller powers up the core
> domain and does not power it down while it remains asserted.
> 
> EDPRCR_CORENPDRQ is in the core power domain and thus to the specific
> core only. This ensures that any power control software running on
> that core should emulate a power down if this is set to one.
> 
> We cannot know the power control design of the system, so the safe
> solution is to set both bits.
> 

+1

I agree that's the safe bet.

-- 
Regards,
Sudeep
--
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 22/22] usb: document that URB transfer_buffer should be aligned

[Alan Stern]

On Thu, 30 Mar 2017, Mauro Carvalho Chehab wrote:

> Em Thu, 30 Mar 2017 10:26:32 -0400 (EDT)
> Alan Stern  escreveu:
> 
> > On Thu, 30 Mar 2017, Oliver Neukum wrote:
> > 
> > > > Btw, I'm a lot more concerned about USB storage drivers. When I was
> > > > discussing about this issue at the #raspberrypi-devel IRC channel,
> > > > someone complained that, after switching from the RPi downstream Kernel
> > > > to upstream, his USB data storage got corrupted. Well, if the USB
> > > > storage drivers also assume that the buffer can be continuous,
> > > > that can corrupt data.  
> > 
> > > 
> > > They do assume that.  
> > 
> > Wait a minute.  Where does that assumption occur?
> > 
> > And exactly what is the assumption?  Mauro wrote "the buffer can be 
> > continuous", but that is certainly not what he meant.
> 
> What I meant to say is that drivers like the uvcdriver (and maybe network and
> usb-storage drivers) may allocate a big buffer and get data there on some
> random order, e. g.: 
> 
> int get_from_buf_pos(char *buf, int pos, int size)
> {
>   /* or an equivalent call to usb_submit_urb() */
>   usb_control_msg(..., buf + pos, size, ...);
> }
> 
> some_function ()
> {
>   ...
> 
>   chr *buf = kzalloc(4, GFP_KERNEL);
> 
>   /* 
>* Access the bytes at the array on a random order, with random size,
>* Like:
>*/
>   get_from_buf_pos(buf, 2, 2);/* should read 0x56, 0x78 */
>   get_from_buf_pos(buf, 0, 2);/* should read 0x12, 0x34 */
> 
>   /*
>* the expected value for the buffer would be:
>*  { 0x12, 0x34, 0x56, 0x78 }
>*/
> 
> E. g. they assume that the transfer URB can work with any arbitrary
> pointer and size, without needing of pre-align them.
> 
> This doesn't work with HCD drivers like dwc2, as each USB_IN operation will
> actually write 4 bytes to the buffer.
> 
> So, what happens, instead, is that each data transfer will get four
> bytes. Due to a hack inside dwc2, with checks if the transfer_buffer
> is DWORD aligned. So, the first transfer will do what's expected: it will
> read 4 bytes to a temporary buffer, allocated inside the driver,
> copying just two bytes to buf. So, after the first read, the
> buffer content will be:
> 
>   buf = { 0x00, x00, 0x56, 0x78 }
> 
> But, on the second read, it won't be using any temporary
> buffer. So, instead of reading a 16-bits word (0x5678),
> it will actually read 32 bits, with 16-bits with some random value,
> causing a buffer overflow. E. g. buffer content will now be:
> 
>   buf = { 0x12, x34, 0xde, 0xad }
> 
> In other words, the second transfer corrupted the data from the
> first transfer.

I'm pretty sure that usb-storage does not do this, at least, not when 
operating in its normal Bulk-Only-Transport mode.  It never tries to 
read the results of an earlier transfer after carrying out a later 
transfer to any part of the same buffer.

Alan Stern

--
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 v5 6/9] coresight: add support for CPU debug module

[Sudeep Holla]

On 25/03/17 18:23, Leo Yan wrote:
> Coresight includes debug module and usually the module connects with CPU
> debug logic. ARMv8 architecture reference manual (ARM DDI 0487A.k) has
> description for related info in "Part H: External Debug".
> 
> Chapter H7 "The Sample-based Profiling Extension" introduces several
> sampling registers, e.g. we can check program counter value with
> combined CPU exception level, secure state, etc. So this is helpful for
> analysis CPU lockup scenarios, e.g. if one CPU has run into infinite
> loop with IRQ disabled. In this case the CPU cannot switch context and
> handle any interrupt (including IPIs), as the result it cannot handle
> SMP call for stack dump.
> 
> This patch is to enable coresight debug module, so firstly this driver
> is to bind apb clock for debug module and this is to ensure the debug
> module can be accessed from program or external debugger. And the driver
> uses sample-based registers for debug purpose, e.g. when system triggers
> panic, the driver will dump program counter and combined context
> registers (EDCIDSR, EDVIDSR); by parsing context registers so can
> quickly get to know CPU secure state, exception level, etc.
> 
> Some of the debug module registers are located in CPU power domain, so
> this requires the CPU power domain stays on when access related debug
> registers, but the power management for CPU power domain is quite
> dependent on SoC integration for power management. For the platforms
> which with sane power controller implementations, this driver follows
> the method to set EDPRCR to try to pull the CPU out of low power state
> and then set 'no power down request' bit so the CPU has no chance to
> lose power.
> 
> If the SoC has not followed up this design well for power management
> controller, the driver introduces module parameter "idle_constraint".
> Setting this parameter for latency requirement in microseconds, finally
> we can constrain all or partial idle states to ensure the CPU power
> domain is enabled, this is a backup method to access coresight CPU
> debug component safely.
> 
> Signed-off-by: Leo Yan 
> ---
>  drivers/hwtracing/coresight/Kconfig   |  11 +
>  drivers/hwtracing/coresight/Makefile  |   1 +
>  drivers/hwtracing/coresight/coresight-cpu-debug.c | 704 
> ++
>  3 files changed, 716 insertions(+)
>  create mode 100644 drivers/hwtracing/coresight/coresight-cpu-debug.c
> 
> diff --git a/drivers/hwtracing/coresight/Kconfig 
> b/drivers/hwtracing/coresight/Kconfig
> index 130cb21..18d7931 100644
> --- a/drivers/hwtracing/coresight/Kconfig
> +++ b/drivers/hwtracing/coresight/Kconfig
> @@ -89,4 +89,15 @@ config CORESIGHT_STM
> logging useful software events or data coming from various entities
> in the system, possibly running different OSs
>  
> +config CORESIGHT_CPU_DEBUG
> + tristate "CoreSight CPU Debug driver"
> + depends on ARM || ARM64
> + depends on DEBUG_FS
> + help
> +   This driver provides support for coresight debugging module. This
> +   is primarily used to dump sample-based profiling registers when
> +   system triggers panic, the driver will parse context registers so
> +   can quickly get to know program counter (PC), secure state,
> +   exception level, etc.
> +
>  endif
> diff --git a/drivers/hwtracing/coresight/Makefile 
> b/drivers/hwtracing/coresight/Makefile
> index af480d9..433d590 100644
> --- a/drivers/hwtracing/coresight/Makefile
> +++ b/drivers/hwtracing/coresight/Makefile
> @@ -16,3 +16,4 @@ obj-$(CONFIG_CORESIGHT_SOURCE_ETM4X) += coresight-etm4x.o \
>   coresight-etm4x-sysfs.o
>  obj-$(CONFIG_CORESIGHT_QCOM_REPLICATOR) += coresight-replicator-qcom.o
>  obj-$(CONFIG_CORESIGHT_STM) += coresight-stm.o
> +obj-$(CONFIG_CORESIGHT_CPU_DEBUG) += coresight-cpu-debug.o
> diff --git a/drivers/hwtracing/coresight/coresight-cpu-debug.c 
> b/drivers/hwtracing/coresight/coresight-cpu-debug.c
> new file mode 100644
> index 000..fbec1d1
> --- /dev/null
> +++ b/drivers/hwtracing/coresight/coresight-cpu-debug.c
> @@ -0,0 +1,704 @@
> +/*
> + * Copyright (c) 2017 Linaro Limited. All rights reserved.
> + *
> + * Author: Leo Yan 
> + *
> + * This program is free software; you can redistribute it and/or modify it
> + * under the terms of the GNU General Public License version 2 as published 
> by
> + * the Free Software Foundation.
> + *
> + * This program is distributed in the hope that it will be useful, but 
> WITHOUT
> + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
> + * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
> + * more details.
> + *
> + * You should have received a copy of the GNU General Public License along 
> with
> + * this program.  If not, see .
> + *
> + */
> +#include 
> +#include 
> +#include 
> +#include 
> +#include 
> +#include 
> +#include 
> +#include 
> +#include 

Re: [PATCH v5 6/9] coresight: add support for CPU debug module

[Sudeep Holla]

On 30/03/17 16:46, Mathieu Poirier wrote:
> On 29 March 2017 at 19:59, Leo Yan  wrote:
>> On Wed, Mar 29, 2017 at 10:55:35AM -0600, Mathieu Poirier wrote:
>>
>> [...]
>>
 So this is why add "idle_constraint" as a central place to control
 power domain for CPU debug purpose and I also think this is more
 friendly for hardware design, e.g. some platforms can enable partial
 low power states to save power and avoid overheat after using this
 driver.

 How about you think for this?
>>>
>>> Like Sudeep pointed out we should concentrate on doing the right thing,
>>> that is work with EDPRSR.PU, EDPRCR.COREPURQ and EDPRCR.CORENPDRQ.
>>
>> Agree, and I think we have aligned for this.
>>
>>> Anything outside of that becomes platform specific and can't be handled in
>>> this driver.
>>
>> Sorry I argue a bit for this just want to make things more clear and
>> if can have better method.
>>
>> Though the issue is platform specific, but the code is to seek common
>> method to handle them. So the driver has no any platform specific code.
> 
> Seeking a common way to handle platform specific problems doesn't
> scale and will never be encompassing.  There will always be a quirk
> somewhere to deal with, hence the idea of keeping things separate.
> 

I completely agree and just responded to the original patch.

>>
>> I read again for Suziki's suggestion: "4) Should document the fact that,
>> on some platforms, the user may have to disable CPUidle explicitly to
>> get the driver working. But let us not make it the default. The user
>> with a not so ideal platform could add "nohlt" and get it working."
> 
> Suzuki and I are expressing the same view using different words.
> 

+1, as I just mentioned on the patch, we can warn user to take action
when this feature gets enabled to get desired result and *nothing more*
than that. Please drop all these pm_qos stuff.

-- 
Regards,
Sudeep
--
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 2/2] perf: xgene: Add support for SoC PMU of next generation of X-Gene

[Hoan Tran]

Hi Mark,


On Tue, Mar 14, 2017 at 12:57 PM, Mark Rutland  wrote:
> On Tue, Mar 14, 2017 at 11:06:52AM -0700, Hoan Tran wrote:
>> This patch adds support for SoC-wide (AKA uncore) Performance Monitoring
>> Unit in the next generation of X-Gene SoC.
>>
>> Signed-off-by: Hoan Tran 
>> ---
>>  drivers/perf/xgene_pmu.c | 645 
>> ++-
>>  1 file changed, 575 insertions(+), 70 deletions(-)
>
> That's a very large number of additions, and a very short commit
> message.
>
> Please expand the commit message, outlining the differences in this new
> version of the PMU HW, and the structural changes made to the driver to
> accommodate this.
>
> Additionally, I think that this amount of change should be split into
> separate patches. More on that below.
>
> [...]
>
>>  static inline void xgene_pmu_mask_int(struct xgene_pmu *xgene_pmu)
>>  {
>> - writel(PCPPMU_INTENMASK, xgene_pmu->pcppmu_csr + PCPPMU_INTMASK_REG);
>> + if (xgene_pmu->version == PCP_PMU_V3) {
>> + writel(PCPPMU_V3_INTENMASK,
>> +xgene_pmu->pcppmu_csr + PCPPMU_INTMASK_REG);
>> + } else {
>> + writel(PCPPMU_INTENMASK,
>> +xgene_pmu->pcppmu_csr + PCPPMU_INTMASK_REG);
>> + }
>>  }
>
> Having all these version checks in the leaf functions is horrible,
> especially given that in cases like xgene_pmu_read_counter(), the v3
> behaviour is *substantially* different to the v1/v2 behaviour.
>
> Please use function pointers in the xgene_pmu/xgene_pmu_dev structures
> instead. That way you can clearly separate the v3 code and the v1/v2
> code, and only need to distinguish the two at init time.
>
> Please move the existing code over to function pointers with preparatory
> patches, with the v3 code introduced afterwards.
>
> That applies to almost all cases where you check xgene_pmu->version,
> excluding those that happen during probing.
>
>> -static inline u32 xgene_pmu_read_counter(struct xgene_pmu_dev *pmu_dev, int 
>> idx)
>> +static inline u64 xgene_pmu_read_counter(struct xgene_pmu_dev *pmu_dev, int 
>> idx)
>>  {
>> - return readl(pmu_dev->inf->csr + PMU_PMEVCNTR0 + (4 * idx));
>> + u32 cnt_lo, cnt_hi, cnt_hi2;
>> +
>> + if (pmu_dev->parent->version == PCP_PMU_V3) {
>> + /*
>> +  * v3 has 64-bit counter registers composed by 2 32-bit 
>> registers
>> +  * This can be a problem if the counter increases and carries
>> +  * out of bit [31] between 2 reads. The extra reads would help
>> +  * to prevent this issue.
>> +  */
>> + while (1) {
>> + cnt_hi = readl(pmu_dev->inf->csr + PMU_PMEVCNTR0 + 4 + 
>> (8 * idx));
>> + cnt_lo = readl(pmu_dev->inf->csr + PMU_PMEVCNTR0 + (8 
>> * idx));
>> + cnt_hi2 = readl(pmu_dev->inf->csr + PMU_PMEVCNTR0 + 4 
>> + (8 * idx));
>> + if (cnt_hi == cnt_hi2)
>> + return (((u64)cnt_hi << 32) | cnt_lo);
>> + }
>> + }
>> +
>> + return ((u64)readl(pmu_dev->inf->csr + PMU_PMEVCNTR0 + (4 * idx)));
>>  }
>
> It would be far simpler and easier to follow, if we did something like:
>
> static inline u64 xgene_pmu_read_counter32(struct xgene_pmu_dev *pmu_dev, int 
> idx)
> {
> return readl(pmu_dev->inf->csr + PMU_PMEVCNTR0 + (4 * idx));
> }
>
> static inline u64 xgene_pmu_read_counter64(struct xgene_pmu_dev *pmu_dev, int 
> idx)
> {
> u32 lo, hi;
>
> do {
> hi = xgene_pmu_read_counter32(dev, 2 * idx);
> lo = xgene_pmu_read_counter32(dev, 2 * idx + 1);
> } while (hi = xgene_pmu_read_counter32(dev, 2 * idx));
>
> return ((u64)hi << 32) | lo;
> }
>
> ... with the prototypes the same, we can assign the pointer to the
> relevant pmu structure.
>
> [...]
>
>> @@ -595,7 +1008,7 @@ static void xgene_perf_event_set_period(struct 
>> perf_event *event)
>>   struct xgene_pmu_dev *pmu_dev = to_pmu_dev(event->pmu);
>>   struct hw_perf_event *hw = &event->hw;
>>   /*
>> -  * The X-Gene PMU counters have a period of 2^32. To account for the
>> +  * The X-Gene PMU counters have a period of 2^32 or more. To account 
>> for the
>>* possiblity of extreme interrupt latency we program for a period of
>>* half that. Hopefully we can handle the interrupt before another 2^31
>>* events occur and the counter overtakes its previous value.
>> @@ -603,7 +1016,7 @@ static void xgene_perf_event_set_period(struct 
>> perf_event *event)
>>   u64 val = 1ULL << 31;
>>
>>   local64_set(&hw->prev_count, val);
>> - xgene_pmu_write_counter(pmu_dev, hw->idx, (u32) val);
>> + xgene_pmu_write_counter(pmu_dev, hw->idx, val);
>>  }
>
> Surely we should update the val to give us a 2^63 default period, then?
>
> AFAICT, we still set it to 1ULL << 31 above.

This is the start value for the counter to prevent the overflow

[PATCH 2/9] scripts/kernel-doc: fix handling of parameters with parenthesis

[Mauro Carvalho Chehab]

lib/crc32c defines one parameter as:
const u32 (*tab)[256]

Better handle parenthesis, to avoid those warnings:

./lib/crc32.c:149: warning: No description found for parameter 'tab)[256]'
./lib/crc32.c:149: warning: Excess function parameter 'tab' description in 
'crc32_le_generic'
./lib/crc32.c:294: warning: No description found for parameter 'tab)[256]'
./lib/crc32.c:294: warning: Excess function parameter 'tab' description in 
'crc32_be_generic'

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

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index a4e5cc3b38e8..a26a5f2dce39 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -2402,8 +2402,7 @@ sub push_parameter($$$) {
}
 
$anon_struct_union = 0;
-   my $param_name = $param;
-   $param_name =~ s/\[.*//;
+   $param =~ s/[\[\)].*//;
 
if ($type eq "" && $param =~ /\.\.\.$/)
{
@@ -2434,9 +2433,9 @@ sub push_parameter($$$) {
# but inline preprocessor statements);
# also ignore unnamed structs/unions;
if (!$anon_struct_union) {
-   if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {
+   if (!defined $parameterdescs{$param} && $param !~ /^#/) {
 
-   $parameterdescs{$param_name} = $undescribed;
+   $parameterdescs{$param} = $undescribed;
 
if (($type eq 'function') || ($type eq 'enum')) {
print STDERR "${file}:$.: warning: Function parameter ".
-- 
2.9.3


--
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 5/9] kernel-api.tmpl: convert it to ReST

[Mauro Carvalho Chehab]

Brainless conversion of genericirq.tmpl book to ReST, via
Documentation/sphinx/tmplcvt

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/DocBook/Makefile|   2 +-
 Documentation/DocBook/kernel-api.tmpl | 331 ---
 Documentation/core-api/index.rst  |   1 +
 Documentation/core-api/kernel-api.rst | 419 ++
 4 files changed, 421 insertions(+), 332 deletions(-)
 delete mode 100644 Documentation/DocBook/kernel-api.tmpl
 create mode 100644 Documentation/core-api/kernel-api.rst

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index e0c13655f770..13056d40e11b 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -9,7 +9,7 @@
 DOCBOOKS := z8530book.xml  \
kernel-hacking.xml kernel-locking.xml \
networking.xml \
-   kernel-api.xml filesystems.xml lsm.xml kgdb.xml \
+   filesystems.xml lsm.xml kgdb.xml \
libata.xml mtdnand.xml librs.xml rapidio.xml \
s390-drivers.xml scsi.xml \
sh.xml w1.xml
diff --git a/Documentation/DocBook/kernel-api.tmpl 
b/Documentation/DocBook/kernel-api.tmpl
deleted file mode 100644
index ecfd0ea40661..
--- a/Documentation/DocBook/kernel-api.tmpl
+++ /dev/null
@@ -1,331 +0,0 @@
-
-http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; []>
-
-
- 
-  The Linux Kernel API
-  
-  
-   
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License as published by the Free Software Foundation; either
- version 2 of the License, or (at your option) any later
- version.
-   
-  
-   
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
-   
-  
-   
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
-   
-  
-   
- For more details see the file COPYING in the source
- distribution of Linux.
-   
-  
- 
-
-
-
-  
- Data Types
- Doubly Linked Lists
-!Iinclude/linux/list.h
- 
-  
-
-  
- Basic C Library Functions
-
- 
-   When writing drivers, you cannot in general use routines which are
-   from the C Library.  Some of the functions have been found generally
-   useful and they are listed below.  The behaviour of these functions
-   may vary slightly from those defined by ANSI, and these deviations
-   are noted in the text.
- 
-
- String Conversions
-!Elib/vsprintf.c
-!Finclude/linux/kernel.h kstrtol
-!Finclude/linux/kernel.h kstrtoul
-!Elib/kstrtox.c
- 
- String Manipulation
-
-!Elib/string.c
- 
- Bit Operations
-!Iarch/x86/include/asm/bitops.h
- 
-  
-
-  
- Basic Kernel Library Functions
-
- 
-   The Linux kernel provides more basic utility functions.
- 
-
- Bitmap Operations
-!Elib/bitmap.c
-!Ilib/bitmap.c
- 
-
- Command-line Parsing
-!Elib/cmdline.c
- 
-
- CRC Functions
-!Elib/crc7.c
-!Elib/crc16.c
-!Elib/crc-itu-t.c
-!Elib/crc32.c
-!Elib/crc-ccitt.c
- 
-
- idr/ida Functions
-!Pinclude/linux/idr.h idr sync
-!Plib/idr.c IDA description
-!Elib/idr.c
- 
-  
-
-  
- Memory Management in Linux
- The Slab Cache
-!Iinclude/linux/slab.h
-!Emm/slab.c
-!Emm/util.c
- 
- User Space Memory Access
-!Iarch/x86/include/asm/uaccess_32.h
-!Earch/x86/lib/usercopy_32.c
- 
- More Memory Management Functions
-!Emm/readahead.c
-!Emm/filemap.c
-!Emm/memory.c
-!Emm/vmalloc.c
-!Imm/page_alloc.c
-!Emm/mempool.c
-!Emm/dmapool.c
-!Emm/page-writeback.c
-!Emm/truncate.c
- 
-  
-
-
-  
- Kernel IPC facilities
-
- IPC utilities
-!Iipc/util.c
- 
-  
-
-  
- FIFO Buffer
- kfifo interface
-!Iinclude/linux/kfifo.h
- 
-  
-
-  
- relay interface support
-
- 
-   Relay interface support
-   is designed to provide an efficient mechanism for tools and
-   facilities to relay large amounts of data from kernel space to
-   user space.
- 
-
- relay interface
-!Ekernel/relay.c
-!Ikernel/relay.c
- 
-  
-
-  
- Module Support
- Module Loading
-!Ekernel/kmod.c
- 
- Inter Module support
-
-   Refer to the file kernel/module.c for more information.
-
-
- 
-  
-
-  
- Hardware Interfaces
- Interrupt Handling
-!Ekernel/irq/manage.c
- 
-
- DMA Channels
-!Ekernel/dma.c
- 
-
- Resources Management
-!Ikernel/resource.c
-!Ekernel/resource.c
- 
-
- MTRR Handling
-!Earch/x86/kernel/cpu/mtrr/main.c
- 
-
- PCI Support Library
-!Edrivers/pci/pci.c
-!Edrivers/pci/pci-drive

[PATCH 8/9] kernel-api.rst: fix some complex tags at lib/bitmap.c

[Mauro Carvalho Chehab]

Fix the following issues:

./lib/bitmap.c:869: WARNING: Definition list ends without a blank line; 
unexpected unindent.
./lib/bitmap.c:876: WARNING: Inline emphasis start-string without end-string.
./lib/bitmap.c:508: ERROR: Unexpected indentation.

And make sure that a table and a footnote will use the right tags.

Signed-off-by: Mauro Carvalho Chehab 
---
 lib/bitmap.c | 28 +---
 1 file changed, 17 insertions(+), 11 deletions(-)

diff --git a/lib/bitmap.c b/lib/bitmap.c
index 0b66f0e5eb6b..08c6ef3a2b6f 100644
--- a/lib/bitmap.c
+++ b/lib/bitmap.c
@@ -502,11 +502,11 @@ EXPORT_SYMBOL(bitmap_print_to_pagebuf);
  * Syntax: range:used_size/group_size
  * Example: 0-1023:2/256 ==> 0,1,256,257,512,513,768,769
  *
- * Returns 0 on success, -errno on invalid input strings.
- * Error values:
- *%-EINVAL: second number in range smaller than first
- *%-EINVAL: invalid character in string
- *%-ERANGE: bit number specified too large for mask
+ * Returns: 0 on success, -errno on invalid input strings. Error values:
+ *
+ *   - ``-EINVAL``: second number in range smaller than first
+ *   - ``-EINVAL``: invalid character in string
+ *   - ``-ERANGE``: bit number specified too large for mask
  */
 static int __bitmap_parselist(const char *buf, unsigned int buflen,
int is_user, unsigned long *maskp,
@@ -864,14 +864,16 @@ EXPORT_SYMBOL(bitmap_bitremap);
  *  11 was set in @orig had no affect on @dst.
  *
  * Example [2] for bitmap_fold() + bitmap_onto():
- *  Let's say @relmap has these ten bits set:
+ *  Let's say @relmap has these ten bits set::
+ *
  * 40 41 42 43 45 48 53 61 74 95
+ *
  *  (for the curious, that's 40 plus the first ten terms of the
  *  Fibonacci sequence.)
  *
  *  Further lets say we use the following code, invoking
  *  bitmap_fold() then bitmap_onto, as suggested above to
- *  avoid the possibility of an empty @dst result:
+ *  avoid the possibility of an empty @dst result::
  *
  * unsigned long *tmp; // a temporary bitmap's bits
  *
@@ -882,22 +884,26 @@ EXPORT_SYMBOL(bitmap_bitremap);
  *  various @orig's.  I list the zero-based positions of each set bit.
  *  The tmp column shows the intermediate result, as computed by
  *  using bitmap_fold() to fold the @orig bitmap modulo ten
- *  (the weight of @relmap).
+ *  (the weight of @relmap):
  *
+ *  === == =
  *  @orig   tmp@dst
  *  00 40
  *  11 41
  *  99 95
- *  10   0 40 (*)
+ *  10   0 40 [#f1]_
  *  1 3 5 7  1 3 5 7   41 43 48 61
  *  0 1 2 3 40 1 2 3 4 40 41 42 43 45
  *  0 9 18 270 9 8 7   40 61 74 95
  *  0 10 20 30   0 40
  *  0 11 22 33   0 1 2 3   40 41 42 43
  *  0 12 24 36   0 2 4 6   40 42 45 53
- *  78 102 211   1 2 8 41 42 74 (*)
+ *  78 102 211   1 2 8 41 42 74 [#f1]_
+ *  === == =
  *
- * (*) For these marked lines, if we hadn't first done bitmap_fold()
+ * .. [#f1]
+ *
+ * For these marked lines, if we hadn't first done bitmap_fold()
  * into tmp, then the @dst result would have been empty.
  *
  * If either of @orig or @relmap is empty (no set bits), then @dst
-- 
2.9.3


--
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 4/9] genericirq.rst: add cross-reference links and use monospaced fonts

[Mauro Carvalho Chehab]

The document describes several functions that are documented
there via kernel doc macros. Add cross-references to them.

In order to be consistend with other documents, use monospaced
fonts for fields.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/core-api/genericirq.rst | 97 +--
 1 file changed, 46 insertions(+), 51 deletions(-)

diff --git a/Documentation/core-api/genericirq.rst 
b/Documentation/core-api/genericirq.rst
index 65d023b26864..0054bd48be84 100644
--- a/Documentation/core-api/genericirq.rst
+++ b/Documentation/core-api/genericirq.rst
@@ -26,7 +26,7 @@ Rationale
 =
 
 The original implementation of interrupt handling in Linux uses the
-__do_IRQ() super-handler, which is able to deal with every type of
+:c:func:`__do_IRQ` super-handler, which is able to deal with every type of
 interrupt logic.
 
 Originally, Russell King identified different types of handlers to build
@@ -43,7 +43,7 @@ During the implementation we identified another type:
 
 -  Fast EOI type
 
-In the SMP world of the __do_IRQ() super-handler another type was
+In the SMP world of the :c:func:`__do_IRQ` super-handler another type was
 identified:
 
 -  Per CPU type
@@ -54,11 +54,11 @@ type. This reduces complexity in that particular code path 
and allows
 the optimized handling of a given type.
 
 The original general IRQ implementation used hw_interrupt_type
-structures and their ->ack(), ->end() [etc.] callbacks to differentiate
+structures and their ``->ack``, ``->end`` [etc.] callbacks to differentiate
 the flow control in the super-handler. This leads to a mix of flow logic
 and low-level hardware logic, and it also leads to unnecessary code
-duplication: for example in i386, there is an ioapic_level_irq and an
-ioapic_edge_irq IRQ-type which share many of the low-level details but
+duplication: for example in i386, there is an ``ioapic_level_irq`` and an
+``ioapic_edge_irq`` IRQ-type which share many of the low-level details but
 have different flow handling.
 
 A more natural abstraction is the clean separation of the 'irq flow' and
@@ -83,7 +83,7 @@ IRQ-flow implementation for 'level type' interrupts and add a
 (sub)architecture specific 'edge type' implementation.
 
 To make the transition to the new model easier and prevent the breakage
-of existing implementations, the __do_IRQ() super-handler is still
+of existing implementations, the :c:func:`__do_IRQ` super-handler is still
 available. This leads to a kind of duality for the time being. Over time
 the new model should be used in more and more architectures, as it
 enables smaller and cleaner IRQ subsystems. It's deprecated for three
@@ -116,7 +116,7 @@ status information and pointers to the interrupt flow 
method and the
 interrupt chip structure which are assigned to this interrupt.
 
 Whenever an interrupt triggers, the low-level architecture code calls
-into the generic interrupt code by calling desc->handle_irq(). This
+into the generic interrupt code by calling :c:func:`desc->handle_irq`. This
 high-level IRQ handling function only uses desc->irq_data.chip
 primitives referenced by the assigned chip descriptor structure.
 
@@ -125,27 +125,27 @@ High-level Driver API
 
 The high-level Driver API consists of following functions:
 
--  request_irq()
+-  :c:func:`request_irq`
 
--  free_irq()
+-  :c:func:`free_irq`
 
--  disable_irq()
+-  :c:func:`disable_irq`
 
--  enable_irq()
+-  :c:func:`enable_irq`
 
--  disable_irq_nosync() (SMP only)
+-  :c:func:`disable_irq_nosync` (SMP only)
 
--  synchronize_irq() (SMP only)
+-  :c:func:`synchronize_irq` (SMP only)
 
--  irq_set_irq_type()
+-  :c:func:`irq_set_irq_type`
 
--  irq_set_irq_wake()
+-  :c:func:`irq_set_irq_wake`
 
--  irq_set_handler_data()
+-  :c:func:`irq_set_handler_data`
 
--  irq_set_chip()
+-  :c:func:`irq_set_chip`
 
--  irq_set_chip_data()
+-  :c:func:`irq_set_chip_data`
 
 See the autogenerated function documentation for details.
 
@@ -154,19 +154,19 @@ High-level IRQ flow handlers
 
 The generic layer provides a set of pre-defined irq-flow methods:
 
--  handle_level_irq
+-  :c:func:`handle_level_irq`
 
--  handle_edge_irq
+-  :c:func:`handle_edge_irq`
 
--  handle_fasteoi_irq
+-  :c:func:`handle_fasteoi_irq`
 
--  handle_simple_irq
+-  :c:func:`handle_simple_irq`
 
--  handle_percpu_irq
+-  :c:func:`handle_percpu_irq`
 
--  handle_edge_eoi_irq
+-  :c:func:`handle_edge_eoi_irq`
 
--  handle_bad_irq
+-  :c:func:`handle_bad_irq`
 
 The interrupt flow handlers (either pre-defined or architecture
 specific) are assigned to specific interrupts by the architecture either
@@ -225,9 +225,9 @@ interrupts.
 
 The following control flow is implemented (simplified excerpt)::
 
-desc->irq_data.chip->irq_mask_ack();
+:c:func:`desc->irq_data.chip->irq_mask_ack`;
 handle_irq_event(desc->action);
-desc->irq_data.chip->irq_unmask();
+:c:func:`desc->irq_data.chip->irq_unmask`;
 
 
 Default Fast EOI IRQ flow handler
@@ -239,7 +239,7 @@ which only 

[PATCH 1/9] scripts/kernel-doc: fix parser for apostrophes

[Mauro Carvalho Chehab]

On ReST, adding a text like ``literal`` is valid. However,
the kernel-doc script won't handle it fine.

We really need this feature, in order to escape things like
%ph, with is found on some C files.

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

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 33c85dfdfce9..a4e5cc3b38e8 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -202,6 +202,7 @@ EOF
 # '&struct_name.member' - name of a structure member
 # '@parameter' - name of a parameter
 # '%CONST' - name of a constant.
+# '``LITERAL``' - literal string without any spaces on it.
 
 ## init lots of data
 
@@ -210,7 +211,8 @@ my $warnings = 0;
 my $anon_struct_union = 0;
 
 # match expressions used to find embedded type information
-my $type_constant = '\%([-_\w]+)';
+my $type_constant = '\b``([^\`]+)``\b';
+my $type_constant2 = '\%([-_\w]+)';
 my $type_func = '(\w+)\(\)';
 my $type_param = '\@(\w+(\.\.\.)?)';
 my $type_fp_param = '\@(\w+)\(\)';  # Special RST handling for func ptr params
@@ -235,6 +237,7 @@ my $type_member_func = $type_member . '\(\)';
 # these work fairly well
 my @highlights_html = (
[$type_constant, "\$1"],
+   [$type_constant2, "\$1"],
[$type_func, "\$1"],
[$type_enum_xml, "\$1"],
[$type_struct_xml, "\$1"],
@@ -252,6 +255,7 @@ my $blankline_html = $local_lt . "p" . $local_gt;   # was 
""
 # html version 5
 my @highlights_html5 = (
 [$type_constant, "\$1"],
+[$type_constant2, "\$1"],
 [$type_func, "\$1"],
 [$type_enum_xml, "\$1"],
 [$type_struct_xml, "\$1"],
@@ -268,6 +272,7 @@ my $blankline_html5 = $local_lt . "br /" . $local_gt;
 my @highlights_xml = (
   ["([^=])\\\"([^\\\"<]+)\\\"", "\$1\$2"],
   [$type_constant, "\$1"],
+  [$type_constant2, "\$1"],
   [$type_enum_xml, "\$1"],
   [$type_struct_xml, "\$1"],
   [$type_typedef_xml, "\$1"],
@@ -283,6 +288,7 @@ my $blankline_xml = $local_lt . "/para" . $local_gt . 
$local_lt . "para" . $loca
 # gnome, docbook format
 my @highlights_gnome = (
 [$type_constant, "\$1"],
+[$type_constant2, "\$1"],
 [$type_func, "\$1"],
 [$type_enum, "\$1"],
 [$type_struct, "\$1"],
@@ -298,6 +304,7 @@ my $blankline_gnome = "\n";
 # these are pretty rough
 my @highlights_man = (
   [$type_constant, "\$1"],
+  [$type_constant2, "\$1"],
   [$type_func, "fB\$1fP"],
   [$type_enum, "fI\$1fP"],
   [$type_struct, "fI\$1fP"],
@@ -312,6 +319,7 @@ my $blankline_man = "";
 # text-mode
 my @highlights_text = (
[$type_constant, "\$1"],
+   [$type_constant2, "\$1"],
[$type_func, "\$1"],
[$type_enum, "\$1"],
[$type_struct, "\$1"],
@@ -326,6 +334,7 @@ my $blankline_text = "";
 # rst-mode
 my @highlights_rst = (
[$type_constant, "``\$1``"],
+   [$type_constant2, "``\$1``"],
# Note: need to escape () to avoid func matching later
[$type_member_func, "\\:c\\:type\\:`\$1\$2\$3() 
<\$1>`"],
[$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],
@@ -344,6 +353,7 @@ my $blankline_rst = "\n";
 # list mode
 my @highlights_list = (
[$type_constant, "\$1"],
+   [$type_constant2, "\$1"],
[$type_func, "\$1"],
[$type_enum, "\$1"],
[$type_struct, "\$1"],
-- 
2.9.3


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

[PATCH 0/9] convert genericirq.tmpl and kernel-api.tmpl to DocBook

[Mauro Carvalho Chehab]

Jani proposed to batch-convert the remaining DocBooks for us
to get rid of it.

Well, I tried ;) 

The conversion itself can easily done, but the problem is that
it hits several errors/warnings when parsing kernel-doc tags.

It ends that it takes some time to fix those.

Also, it seems that the "!I" and "!E" tags at the DocBook
template are not quite right. So, despite being properly
converted to the corresponding kernel-doc tags at ReST, they
didn't produce all that it was needed. I manually fixed a
few, but I guess there are more to be fixed there. Anyway,
this is something that the subsystem maintainers can fix later,
as they understand better what functions they want exported at
the public API documentation, and what functions they want to
hide.

This series converts just two documents, adding them to the
core-api.rst book. It addresses the errors/warnings that popup
after the conversion.

I had to add two fixes to scripts/kernel-doc, in order to solve
some of the issues.

If I have some time during this weekend, I may try to convert
some additional documents to DocBook.


Mauro Carvalho Chehab (9):
  scripts/kernel-doc: fix parser for apostrophes
  scripts/kernel-doc: fix handling of parameters with parenthesis
  genericirq.tmpl: convert it to ReST
  genericirq.rst: add cross-reference links and use monospaced fonts
  kernel-api.tmpl: convert it to ReST
  kernel-api.rst: fix output of the vsnprintf() documentation
  kernel-api.rst: make it handle lib/crc32.c
  kernel-api.rst: fix some complex tags at lib/bitmap.c
  kernel-api.rst: fix a series of errors when parsing C files

 Documentation/DocBook/Makefile|   4 +-
 Documentation/DocBook/genericirq.tmpl | 520 --
 Documentation/DocBook/kernel-api.tmpl | 331 --
 Documentation/core-api/genericirq.rst | 440 
 Documentation/core-api/index.rst  |   2 +
 Documentation/core-api/kernel-api.rst | 418 +++
 block/genhd.c |   7 +-
 drivers/pci/irq.c |   2 +-
 include/linux/clk.h   |   4 +-
 ipc/util.c|  12 +-
 lib/bitmap.c  |  28 +-
 lib/string.c  |   2 +-
 lib/vsprintf.c|   6 +-
 mm/filemap.c  |  18 +-
 mm/page_alloc.c   |   3 +-
 mm/vmalloc.c  |   2 +-
 scripts/kernel-doc|  19 +-
 security/security.c   |  12 +-
 18 files changed, 932 insertions(+), 898 deletions(-)
 delete mode 100644 Documentation/DocBook/genericirq.tmpl
 delete mode 100644 Documentation/DocBook/kernel-api.tmpl
 create mode 100644 Documentation/core-api/genericirq.rst
 create mode 100644 Documentation/core-api/kernel-api.rst

-- 
2.9.3


--
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 7/9] kernel-api.rst: make it handle lib/crc32.c

[Mauro Carvalho Chehab]

This file has only "internal" functions:
./lib/crc32.c:1: warning: no structured comments found

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/core-api/kernel-api.rst | 1 -
 1 file changed, 1 deletion(-)

diff --git a/Documentation/core-api/kernel-api.rst 
b/Documentation/core-api/kernel-api.rst
index e820247e90d3..9a3d3597a6b7 100644
--- a/Documentation/core-api/kernel-api.rst
+++ b/Documentation/core-api/kernel-api.rst
@@ -80,7 +80,6 @@ CRC Functions
:export:
 
 .. kernel-doc:: lib/crc32.c
-   :export:
 
 .. kernel-doc:: lib/crc-ccitt.c
:export:
-- 
2.9.3


--
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 6/9] kernel-api.rst: fix output of the vsnprintf() documentation

[Mauro Carvalho Chehab]

The vsnprintf() kernel-doc comment uses % character with a special
meaning other than escaping a constant. As ReST already defines
``literal`` as an escape sequence, let's make kernel-doc handle it,
and use it at lib/vsprintf.c.

Signed-off-by: Mauro Carvalho Chehab 
---
 lib/vsprintf.c | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/lib/vsprintf.c b/lib/vsprintf.c
index e3bf4e0f10b5..176641cc549d 100644
--- a/lib/vsprintf.c
+++ b/lib/vsprintf.c
@@ -1954,13 +1954,13 @@ set_precision(struct printf_spec *spec, int prec)
  * This function generally follows C99 vsnprintf, but has some
  * extensions and a few limitations:
  *
- * %n is unsupported
- * %p* is handled by pointer()
+ *  - ``%n`` is unsupported
+ *  - ``%p*`` is handled by pointer()
  *
  * See pointer() or Documentation/printk-formats.txt for more
  * extensive description.
  *
- * ** Please update the documentation in both places when making changes **
+ * **Please update the documentation in both places when making changes**
  *
  * The return value is the number of characters which would
  * be generated for the given input, excluding the trailing
-- 
2.9.3


--
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/9] genericirq.tmpl: convert it to ReST

[Mauro Carvalho Chehab]

Brainless conversion of genericirq.tmpl book to ReST, via
Documentation/sphinx/tmplcvt

Copyright information inserted manually.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/DocBook/Makefile|   2 +-
 Documentation/DocBook/genericirq.tmpl | 520 --
 Documentation/core-api/genericirq.rst | 445 +
 Documentation/core-api/index.rst  |   1 +
 4 files changed, 447 insertions(+), 521 deletions(-)
 delete mode 100644 Documentation/DocBook/genericirq.tmpl
 create mode 100644 Documentation/core-api/genericirq.rst

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 7d94db2b53cd..e0c13655f770 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -11,7 +11,7 @@ DOCBOOKS := z8530book.xml  \
networking.xml \
kernel-api.xml filesystems.xml lsm.xml kgdb.xml \
libata.xml mtdnand.xml librs.xml rapidio.xml \
-   genericirq.xml s390-drivers.xml scsi.xml \
+   s390-drivers.xml scsi.xml \
sh.xml w1.xml
 
 ifeq ($(DOCBOOKS),)
diff --git a/Documentation/DocBook/genericirq.tmpl 
b/Documentation/DocBook/genericirq.tmpl
deleted file mode 100644
index 59fb5c077541..
--- a/Documentation/DocBook/genericirq.tmpl
+++ /dev/null
@@ -1,520 +0,0 @@
-
-http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; []>
-
-
- 
-  Linux generic IRQ handling
-
-  
-   
-Thomas
-Gleixner
-
- 
-  t...@linutronix.de
- 
-
-   
-   
-Ingo
-Molnar
-
- 
-  mi...@elte.hu
- 
-
-   
-  
-
-  
-   2005-2010
-   Thomas Gleixner
-  
-  
-   2005-2006
-   Ingo Molnar
-  
-
-  
-   
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License version 2 as published by the Free Software Foundation.
-   
-
-   
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
-   
-
-   
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
-   
-
-   
- For more details see the file COPYING in the source
- distribution of Linux.
-   
-  
- 
-
-
-
-  
-Introduction
-
-   The generic interrupt handling layer is designed to provide a
-   complete abstraction of interrupt handling for device drivers.
-   It is able to handle all the different types of interrupt controller
-   hardware. Device drivers use generic API functions to request, enable,
-   disable and free interrupts. The drivers do not have to know anything
-   about interrupt hardware details, so they can be used on different
-   platforms without code changes.
-
-
-   This documentation is provided to developers who want to implement
-   an interrupt subsystem based for their architecture, with the help
-   of the generic IRQ handling layer.
-
-  
-
-  
-Rationale
-   
-   The original implementation of interrupt handling in Linux uses
-   the __do_IRQ() super-handler, which is able to deal with every
-   type of interrupt logic.
-   
-   
-   Originally, Russell King identified different types of handlers to
-   build a quite universal set for the ARM interrupt handler
-   implementation in Linux 2.5/2.6. He distinguished between:
-   
- Level type
- Edge type
- Simple type
-   
-   During the implementation we identified another type:
-   
- Fast EOI type
-   
-   In the SMP world of the __do_IRQ() super-handler another type
-   was identified:
-   
- Per CPU type
-   
-   
-   
-   This split implementation of high-level IRQ handlers allows us to
-   optimize the flow of the interrupt handling for each specific
-   interrupt type. This reduces complexity in that particular code path
-   and allows the optimized handling of a given type.
-   
-   
-   The original general IRQ implementation used hw_interrupt_type
-   structures and their ->ack(), ->end() [etc.] callbacks to
-   differentiate the flow control in the super-handler. This leads to
-   a mix of flow logic and low-level hardware logic, and it also leads
-   to unnecessary code duplication: for example in i386, there is an
-   ioapic_level_irq and an ioapic_edge_irq IRQ-type which share many
-   of the low-level details but have different flow handling.
-   
-   
-   A more natural abstraction is the clean separation of the
-   'irq flow' and the 'chip details'.
-   
-

[PATCH 9/9] kernel-api.rst: fix a series of errors when parsing C files

[Mauro Carvalho Chehab]

./lib/string.c:134: WARNING: Inline emphasis start-string without end-string.
./mm/filemap.c:522: WARNING: Inline interpreted text or phrase reference 
start-string without end-string.
./mm/filemap.c:1283: ERROR: Unexpected indentation.
./mm/filemap.c:3003: WARNING: Inline interpreted text or phrase reference 
start-string without end-string.
./mm/vmalloc.c:1544: WARNING: Inline emphasis start-string without end-string.
./mm/page_alloc.c:4245: ERROR: Unexpected indentation.
./ipc/util.c:676: ERROR: Unexpected indentation.
./drivers/pci/irq.c:35: WARNING: Block quote ends without a blank line; 
unexpected unindent.
./security/security.c:109: ERROR: Unexpected indentation.
./security/security.c:110: WARNING: Definition list ends without a blank line; 
unexpected unindent.
./block/genhd.c:275: WARNING: Inline strong start-string without end-string.
./block/genhd.c:283: WARNING: Inline strong start-string without end-string.
./include/linux/clk.h:134: WARNING: Inline emphasis start-string without 
end-string.
./include/linux/clk.h:134: WARNING: Inline emphasis start-string without 
end-string.
./ipc/util.c:477: ERROR: Unknown target name: "s".

Signed-off-by: Mauro Carvalho Chehab 
---
 block/genhd.c   |  7 ---
 drivers/pci/irq.c   |  2 +-
 include/linux/clk.h |  4 ++--
 ipc/util.c  | 12 +++-
 lib/string.c|  2 +-
 mm/filemap.c| 18 ++
 mm/page_alloc.c |  3 ++-
 mm/vmalloc.c|  2 +-
 security/security.c | 12 
 9 files changed, 36 insertions(+), 26 deletions(-)

diff --git a/block/genhd.c b/block/genhd.c
index b26a5ea115d0..a53bfd19a0ec 100644
--- a/block/genhd.c
+++ b/block/genhd.c
@@ -271,16 +271,17 @@ void blkdev_show(struct seq_file *seqf, off_t offset)
 /**
  * register_blkdev - register a new block device
  *
- * @major: the requested major device number [1..255]. If @major=0, try to
+ * @major: the requested major device number [1..255]. If @major = 0, try to
  * allocate any unused major number.
  * @name: the name of the new block device as a zero terminated string
  *
  * The @name must be unique within the system.
  *
- * The return value depends on the @major input parameter.
+ * The return value depends on the @major input parameter:
+ *
  *  - if a major device number was requested in range [1..255] then the
  *function returns zero on success, or a negative error code
- *  - if any unused major number was requested with @major=0 parameter
+ *  - if any unused major number was requested with @major = 0 parameter
  *then the return value is the allocated major number in range
  *[1..255] or a negative error code otherwise
  */
diff --git a/drivers/pci/irq.c b/drivers/pci/irq.c
index 6684f153ab57..f9f2a0324ecc 100644
--- a/drivers/pci/irq.c
+++ b/drivers/pci/irq.c
@@ -31,7 +31,7 @@ static void pci_note_irq_problem(struct pci_dev *pdev, const 
char *reason)
  * driver).
  *
  * Returns:
- *  a suggestion for fixing it (although the driver is not required to
+ * a suggestion for fixing it (although the driver is not required to
  * act on this).
  */
 enum pci_lost_interrupt_reason pci_lost_interrupt(struct pci_dev *pdev)
diff --git a/include/linux/clk.h b/include/linux/clk.h
index e9d36b3e49de..024cd07870d0 100644
--- a/include/linux/clk.h
+++ b/include/linux/clk.h
@@ -132,8 +132,8 @@ int clk_get_phase(struct clk *clk);
  * @q: clk compared against p
  *
  * Returns true if the two struct clk pointers both point to the same hardware
- * clock node. Put differently, returns true if struct clk *p and struct clk *q
- * share the same struct clk_core object.
+ * clock node. Put differently, returns true if @p and @q
+ * share the same &struct clk_core object.
  *
  * Returns false otherwise. Note that two NULL clks are treated as matching.
  */
diff --git a/ipc/util.c b/ipc/util.c
index 798cad18dd87..3459a16a9df9 100644
--- a/ipc/util.c
+++ b/ipc/util.c
@@ -474,7 +474,7 @@ void ipc_rcu_free(struct rcu_head *head)
  * Check user, group, other permissions for access
  * to ipc resources. return 0 if allowed
  *
- * @flag will most probably be 0 or S_...UGO from 
+ * @flag will most probably be 0 or ``S_...UGO`` from 
  */
 int ipcperms(struct ipc_namespace *ns, struct kern_ipc_perm *ipcp, short flag)
 {
@@ -672,10 +672,12 @@ int ipc_update_perm(struct ipc64_perm *in, struct 
kern_ipc_perm *out)
  *
  * This function does some common audit and permissions check for some IPC_XXX
  * cmd and is called from semctl_down, shmctl_down and msgctl_down.
- * It must be called without any lock held and
- *  - retrieves the ipc with the given id in the given table.
- *  - performs some audit and permission check, depending on the given cmd
- *  - returns a pointer to the ipc object or otherwise, the corresponding 
error.
+ * It must be called without any lock held and:
+ *
+ *   - retrieves the ipc with the given id in the given table.
+ *   - performs some audit and permission check, depending on the given cmd
+ *   - ret

Re: [PATCH 22/22] usb: document that URB transfer_buffer should be aligned

[Laurent Pinchart]

Hi Alan,

On Thursday 30 Mar 2017 11:55:18 Alan Stern wrote:
> On Thu, 30 Mar 2017, Mauro Carvalho Chehab wrote:
> > Em Thu, 30 Mar 2017 10:26:32 -0400 (EDT) Alan Stern escreveu:
> >> On Thu, 30 Mar 2017, Oliver Neukum wrote:
>  Btw, I'm a lot more concerned about USB storage drivers. When I was
>  discussing about this issue at the #raspberrypi-devel IRC channel,
>  someone complained that, after switching from the RPi downstream
>  Kernel to upstream, his USB data storage got corrupted. Well, if the
>  USB storage drivers also assume that the buffer can be continuous,
>  that can corrupt data.
> >>> 
> >>> They do assume that.
> >> 
> >> Wait a minute.  Where does that assumption occur?
> >> 
> >> And exactly what is the assumption?  Mauro wrote "the buffer can be
> >> continuous", but that is certainly not what he meant.
> > 
> > What I meant to say is that drivers like the uvcdriver (and maybe network
> > and usb-storage drivers) may allocate a big buffer and get data there on
> > some random order, e. g.:
> > 
> > int get_from_buf_pos(char *buf, int pos, int size)
> > {
> > /* or an equivalent call to usb_submit_urb() */
> > usb_control_msg(..., buf + pos, size, ...);
> > }
> > 
> > some_function ()
> > {
> > ...
> > 
> > chr *buf = kzalloc(4, GFP_KERNEL);
> > 
> > /*
> >  * Access the bytes at the array on a random order, with random size,
> >  * Like:
> >  */
> > get_from_buf_pos(buf, 2, 2);/* should read 0x56, 0x78 */
> > get_from_buf_pos(buf, 0, 2);/* should read 0x12, 0x34 */
> > 
> > /*
> >  * the expected value for the buffer would be:
> >  *  { 0x12, 0x34, 0x56, 0x78 }
> >  */
> > 
> > E. g. they assume that the transfer URB can work with any arbitrary
> > pointer and size, without needing of pre-align them.
> > 
> > This doesn't work with HCD drivers like dwc2, as each USB_IN operation
> > will actually write 4 bytes to the buffer.
> > 
> > So, what happens, instead, is that each data transfer will get four
> > bytes. Due to a hack inside dwc2, with checks if the transfer_buffer
> > is DWORD aligned. So, the first transfer will do what's expected: it will
> > read 4 bytes to a temporary buffer, allocated inside the driver,
> > copying just two bytes to buf. So, after the first read, the
> > 
> > buffer content will be:
> > buf = { 0x00, x00, 0x56, 0x78 }
> > 
> > But, on the second read, it won't be using any temporary
> > buffer. So, instead of reading a 16-bits word (0x5678),
> > it will actually read 32 bits, with 16-bits with some random value,
> > 
> > causing a buffer overflow. E. g. buffer content will now be:
> > buf = { 0x12, x34, 0xde, 0xad }
> > 
> > In other words, the second transfer corrupted the data from the
> > first transfer.
> 
> I'm pretty sure that usb-storage does not do this, at least, not when
> operating in its normal Bulk-Only-Transport mode.  It never tries to
> read the results of an earlier transfer after carrying out a later
> transfer to any part of the same buffer.

The uvcvideo driver does something similar. Given the size of the transfer a 
bounce buffer shouldn't affect performances. Handling this in the USB core 
sounds like the best solution to me.

-- 
Regards,

Laurent Pinchart

--
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 22/22] usb: document that URB transfer_buffer should be aligned

[Oliver Neukum]

Am Donnerstag, den 30.03.2017, 11:55 -0400 schrieb Alan Stern:
> 
> I'm pretty sure that usb-storage does not do this, at least, not when 
> operating in its normal Bulk-Only-Transport mode.  It never tries to 
> read the results of an earlier transfer after carrying out a later 
> transfer to any part of the same buffer.

The storage driver takes buffers as the block layer (or sg) provide
them, does it not?

Regards
Oliver

--
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 9/9] kernel-api.rst: fix a series of errors when parsing C files

[Bjorn Helgaas]

On Thu, Mar 30, 2017 at 05:11:36PM -0300, Mauro Carvalho Chehab wrote:
> ./lib/string.c:134: WARNING: Inline emphasis start-string without end-string.
> ./mm/filemap.c:522: WARNING: Inline interpreted text or phrase reference 
> start-string without end-string.
> ./mm/filemap.c:1283: ERROR: Unexpected indentation.
> ./mm/filemap.c:3003: WARNING: Inline interpreted text or phrase reference 
> start-string without end-string.
> ./mm/vmalloc.c:1544: WARNING: Inline emphasis start-string without end-string.
> ./mm/page_alloc.c:4245: ERROR: Unexpected indentation.
> ./ipc/util.c:676: ERROR: Unexpected indentation.
> ./drivers/pci/irq.c:35: WARNING: Block quote ends without a blank line; 
> unexpected unindent.
> ./security/security.c:109: ERROR: Unexpected indentation.
> ./security/security.c:110: WARNING: Definition list ends without a blank 
> line; unexpected unindent.
> ./block/genhd.c:275: WARNING: Inline strong start-string without end-string.
> ./block/genhd.c:283: WARNING: Inline strong start-string without end-string.
> ./include/linux/clk.h:134: WARNING: Inline emphasis start-string without 
> end-string.
> ./include/linux/clk.h:134: WARNING: Inline emphasis start-string without 
> end-string.
> ./ipc/util.c:477: ERROR: Unknown target name: "s".
> 
> Signed-off-by: Mauro Carvalho Chehab 

Acked-by: Bjorn Helgaas# for drivers/pci/irq.c

> diff --git a/drivers/pci/irq.c b/drivers/pci/irq.c
> index 6684f153ab57..f9f2a0324ecc 100644
> --- a/drivers/pci/irq.c
> +++ b/drivers/pci/irq.c
> @@ -31,7 +31,7 @@ static void pci_note_irq_problem(struct pci_dev *pdev, 
> const char *reason)
>   * driver).
>   *
>   * Returns:
> - *  a suggestion for fixing it (although the driver is not required to
> + * a suggestion for fixing it (although the driver is not required to
>   * act on this).
>   */
>  enum pci_lost_interrupt_reason pci_lost_interrupt(struct pci_dev *pdev)
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH linux v5 1/2] Documentation: dt-bindings: Document bindings for ASPEED AST2400/AST2500 PWM and Fan tach controller device driver

[Rob Herring]

On Fri, Mar 24, 2017 at 11:17:22AM -0700, Jaghathiswari Rankappagounder 
Natarajan wrote:
> This binding provides interface for adding values related to ASPEED
> AST2400/2500 PWM and Fan tach controller support.
> The PWM controller can support upto 8 PWM output ports.
> The Fan tach controller can support upto 16 tachometer inputs.
> 
> Signed-off-by: Jaghathiswari Rankappagounder Natarajan 
> ---
>  v5:
> - Changed the naming scheme to aspeed,ast2400/2500-pwm-tacho
> - Removed gpio pin muxing
> - Added aspeed vendor prefix for fan-tach-ch
> - Changed to fan@0/1
> - Changed reg to 32 bits
> 
>  v4:
> - Used 'reg'
> 
>  v3:
> - Made the structure more common
> 
>  v2:
> - Removed '_' in node and property names
> - Gave some explanation for the properties used
> 
>  .../devicetree/bindings/hwmon/aspeed-pwm-tacho.txt | 68 
> ++
>  1 file changed, 68 insertions(+)
>  create mode 100644 
> Documentation/devicetree/bindings/hwmon/aspeed-pwm-tacho.txt
> 
> diff --git a/Documentation/devicetree/bindings/hwmon/aspeed-pwm-tacho.txt 
> b/Documentation/devicetree/bindings/hwmon/aspeed-pwm-tacho.txt
> new file mode 100644
> index ..f96d32bfcdfa
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/hwmon/aspeed-pwm-tacho.txt
> @@ -0,0 +1,68 @@
> +ASPEED AST2400/AST2500 PWM and Fan Tacho controller device driver
> +
> +The ASPEED PWM controller can support upto 8 PWM outputs. The ASPEED Fan 
> Tacho
> +controller can support upto 16 Fan tachometer inputs.
> +
> +There can be upto 8 fans supported. Each fan can have one PWM output and
> +one/two Fan tach inputs.
> +
> +Required properties for pwm-tacho node:
> +- #address-cells : should be 1.
> +
> +- #size-cells : should be 1.
> +
> +- reg : address and length of the register set for the device.
> +
> +- pinctrl-names : a pinctrl state named "default" must be defined.
> +
> +- pinctrl-0 : phandle referencing pin configuration of the PWM ports.
> +
> +- compatible : should be "aspeed,ast2400-pwm-tacho" for AST2400 and
> +"aspeed,ast2500-pwm-tacho" for AST2500.
> +
> +- clocks : a fixed clock providing input clock frequency(PWM
> +and Fan Tach clock)
> +
> +fan subnode format:
> +===
> +Under fan subnode there can upto 8 child nodes, with each child node
> +representing a fan. If there are 8 fans each fan can have one PWM port and
> +one/two Fan tach inputs.
> +
> +Required properties for each child node:
> +- reg : should specify PWM source port.
> + integer value in the range 0 to 7 with 0 indicating PWM port A and
> + 7 indicating PWM port H.
> +
> +- aspeed-fan-tach-ch : should specify the Fan tach input channel.

aspeed,fan-tach-ch

With that,

Acked-by: Rob Herring 

> +integer value in the range 0 through 15, with 0 indicating
> + Fan tach channel 0 and 15 indicating Fan tach channel 15.
> + Atleast one Fan tach input channel is required.
> +
> +Examples:
> +
> +pwm_tacho_fixed_clk: fixedclk {
> + compatible = "fixed-clock";
> + #clock-cells = <0>;
> + clock-frequency = <2400>;
> +}
> +
> +pwm_tacho: pwmtachocontroller@1e786000 {
> + #address-cells = <1>;
> + #size-cells = <1>;
> + reg = <0x1E786000 0x1000>;
> + compatible = "aspeed,ast2500-pwm-tacho";
> + clocks = <&pwm_tacho_fixed_clk>;
> + pinctrl-names = "default";
> + pinctrl-0 = <&pinctrl_pwm0_default &pinctrl_pwm1_default>;
> +
> + fan@0 {
> + reg = <0x00>;
> + aspeed-fan-tach-ch = /bits/ 8 <0x00>;
> + };
> +
> + fan@1 {
> + reg = <0x01>;
> + aspeed-fan-tach-ch = /bits/ 8 <0x01 0x02>;
> + };
> +};
> --
> 2.12.1.578.ge9c3154ca4-goog
> 
--
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 v5 1/9] coresight: bindings for CPU debug module

[Rob Herring]

On Sun, Mar 26, 2017 at 02:23:09AM +0800, Leo Yan wrote:
> According to ARMv8 architecture reference manual (ARM DDI 0487A.k)
> Chapter 'Part H: External debug', the CPU can integrate debug module
> and it can support self-hosted debug and external debug. Especially
> for supporting self-hosted debug, this means the program can access
> the debug module from mmio region; and usually the mmio region is
> integrated with coresight.
> 
> So add document for binding debug component, includes binding to APB
> clock; and also need specify the CPU node which the debug module is
> dedicated to specific CPU.
> 
> Suggested-by: Mike Leach 
> Reviewed-by: Mathieu Poirier 
> Signed-off-by: Leo Yan 
> ---
>  .../bindings/arm/coresight-cpu-debug.txt   | 48 
> ++
>  1 file changed, 48 insertions(+)
>  create mode 100644 
> Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt

Acked-by: Rob Herring 
--
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 v5 6/9] coresight: add support for CPU debug module

[Leo Yan]

On Thu, Mar 30, 2017 at 04:56:52PM +0100, Sudeep Holla wrote:

[...]

> > +static struct pm_qos_request debug_qos_req;
> > +static int idle_constraint = PM_QOS_DEFAULT_VALUE;
> > +module_param(idle_constraint, int, 0600);
> > +MODULE_PARM_DESC(idle_constraint, "Latency requirement in microseconds for 
> > CPU "
> > +"idle states (default is -1, which means have no limiation "
> > +"to CPU idle states; 0 means disabling all idle states; user "
> > +"can choose other platform dependent values so can disable "
> > +"specific idle states for the platform)");
> > +
> 
> NACK for this. Why you want the policy inside the driver. You can always
> do that from the user-space. I have mentioned it several times now.
> What can't you do these ?
> 
> 1. echo "what_ever_latency_you_need_in_uS" > /dev/cpu_dma_latency
> 2. echo 1 > /sys/devices/system/cpu/cpu$cpu/cpuidle/state$state/disable
>(for all cpus and their states) (1) is definitely simpler way to
> disable deeper idle if latency = 0uS
> 
> You can always warn user about that when it's enabled via debugfs/sysfs

Thanks for suggestion, now it's clear for me.

> -- 
> Regards,
> Sudeep
--
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 01/22] driver-api/basics.rst: add device table header

[kbuild test robot]

Hi Mauro,

[auto build test WARNING on linus/master]
[also build test WARNING on v4.11-rc4 next-20170330]
[if your patch is applied to the wrong git tree, please drop us a note to help 
improve the system]

url:
https://github.com/0day-ci/linux/commits/Mauro-Carvalho-Chehab/driver-api-basics-rst-add-device-table-header/20170331-041911
reproduce: make htmldocs

All warnings (new ones prefixed by >>):

   include/linux/init.h:1: warning: no structured comments found
>> include/linux/mod_devicetable.h:676: warning: Excess 
>> struct/union/enum/typedef member 'ver_major' description in 
>> 'fsl_mc_device_id'
>> include/linux/mod_devicetable.h:676: warning: Excess 
>> struct/union/enum/typedef member 'ver_minor' description in 
>> 'fsl_mc_device_id'
   kernel/sched/core.c:2085: warning: No description found for parameter 'rf'
   kernel/sched/core.c:2085: warning: Excess function parameter 'cookie' 
description in 'try_to_wake_up_local'
   include/linux/kthread.h:26: warning: Excess function parameter '...' 
description in 'kthread_create'
   kernel/sys.c:1: warning: no structured comments found
   include/linux/device.h:969: warning: No description found for parameter 
'dma_ops'
   drivers/dma-buf/seqno-fence.c:1: warning: no structured comments found
   include/linux/iio/iio.h:597: warning: No description found for parameter 
'trig_readonly'
   include/linux/iio/trigger.h:151: warning: No description found for parameter 
'indio_dev'
   include/linux/iio/trigger.h:151: warning: No description found for parameter 
'trig'
   include/linux/device.h:970: warning: No description found for parameter 
'dma_ops'
   drivers/regulator/core.c:1467: warning: Excess function parameter 'ret' 
description in 'regulator_dev_lookup'
   include/drm/drm_drv.h:438: warning: No description found for parameter 'open'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'preclose'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'postclose'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'lastclose'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'set_busid'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'irq_handler'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'irq_preinstall'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'irq_postinstall'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'irq_uninstall'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'debugfs_init'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'debugfs_cleanup'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'gem_open_object'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'gem_close_object'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'prime_handle_to_fd'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'prime_fd_to_handle'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'gem_prime_export'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'gem_prime_import'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'gem_prime_pin'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'gem_prime_unpin'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'gem_prime_res_obj'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'gem_prime_get_sg_table'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'gem_prime_import_sg_table'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'gem_prime_vmap'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'gem_prime_vunmap'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'gem_prime_mmap'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'gem_vm_ops'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'major'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'minor'
   include/drm/drm_drv.h:438: warning: No description found for parameter 
'patchlevel'
   include/drm/drm_drv.h:438: warning: No description found for parameter 'name'
   include/drm/drm_d

doc build requirements

[Johannes Berg]

Hi,

I notice that now - since

commit ec868e4ee2bcebb9e4c03979d90e0ac0b79fe05a
Author: Mauro Carvalho Chehab 
Date:   Wed Nov 30 08:00:17 2016 -0200

docs-rst: media: build SVG from graphviz files

was merged, it is strictly necessary to have `dot' installed to build
documentation - there isn't even any fallback.

Now, it's not hard to install, so I have no major objection against it,
but I wanted to take the opportunity to point out that this seems a bit
arbitrary - last I tried adding new functionality and *didn't* even
make it a build requirement (logging only a warning if not installed) I
was told I can't add such a thing.

Does this mean something has changed and I can try again? :)

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