Re: [PATCH v2 5/5] media: atmel-isc: Rework the format list

[Yang, Wenyou]

On 2017/9/27 16:03, Hans Verkuil wrote:

On 09/27/2017 07:15 AM, Yang, Wenyou wrote:

Hi Hans,

Thank  you very much for your review.

On 2017/9/25 21:24, Hans Verkuil wrote:

Hi Wenyou,

On 18/09/17 08:39, Wenyou Yang wrote:

To improve the readability of code, split the format array into two,
one for the format description, other for the register configuration.
Meanwhile, add the flag member to indicate the format can be achieved
from the sensor or be produced by the controller, and rename members
related to the register configuration.

Also add more formats support: GREY, ARGB444, ARGB555 and ARGB32.

Signed-off-by: Wenyou Yang 

This looks better. Just a few comments, see below.


---

Changes in v2:
   - Add the new patch to remove the unnecessary member from
 isc_subdev_entity struct.
   - Rebase on the patch set,
  [PATCH 0/6] [media] Atmel: Adjustments for seven function 
implementations
  
https://www.mail-archive.com/linux-media@vger.kernel.org/msg118342.html

   drivers/media/platform/atmel/atmel-isc.c | 524 
---
   1 file changed, 405 insertions(+), 119 deletions(-)

diff --git a/drivers/media/platform/atmel/atmel-isc.c 
b/drivers/media/platform/atmel/atmel-isc.c
index 2d876903da71..90bd0b28a975 100644
--- a/drivers/media/platform/atmel/atmel-isc.c
+++ b/drivers/media/platform/atmel/atmel-isc.c
@@ -89,34 +89,56 @@ struct isc_subdev_entity {
struct list_head list;
   };
   
+#define FMT_FLAG_FROM_SENSOR		BIT(0)

+#define FMT_FLAG_FROM_CONTROLLER   BIT(1)

Document the meaning of these flags.

Will add it in next version.

+
   /*
* struct isc_format - ISC media bus format information
* @fourcc:  Fourcc code for this format
* @mbus_code:   V4L2 media bus format code.
+ * flags:  Indicate format from sensor or converted by controller
* @bpp: Bits per pixel (when stored in memory)
- * @reg_bps:   reg value for bits per sample
*   (when transferred over a bus)
- * @pipeline:  pipeline switch
* @sd_support:  Subdev supports this format
* @isc_support: ISC can convert raw format to this format
*/
+
   struct isc_format {
u32 fourcc;
u32 mbus_code;
+   u32 flags;
u8  bpp;
   
-	u32	reg_bps;

-   u32 reg_bay_cfg;
-   u32 reg_rlp_mode;
-   u32 reg_dcfg_imode;
-   u32 reg_dctrl_dview;
-
-   u32 pipeline;
-
boolsd_support;
boolisc_support;
   };
   
+/* Pipeline bitmap */

+#define WB_ENABLE  BIT(0)
+#define CFA_ENABLE BIT(1)
+#define CC_ENABLE  BIT(2)
+#define GAM_ENABLE BIT(3)
+#define GAM_BENABLEBIT(4)
+#define GAM_GENABLEBIT(5)
+#define GAM_RENABLEBIT(6)
+#define CSC_ENABLE BIT(7)
+#define CBC_ENABLE BIT(8)
+#define SUB422_ENABLE  BIT(9)
+#define SUB420_ENABLE  BIT(10)
+
+#define GAM_ENABLES(GAM_RENABLE | GAM_GENABLE | GAM_BENABLE | GAM_ENABLE)
+
+struct fmt_config {
+   u32 fourcc;
+
+   u32 pfe_cfg0_bps;
+   u32 cfa_baycfg;
+   u32 rlp_cfg_mode;
+   u32 dcfg_imode;
+   u32 dctrl_dview;
+
+   u32 bits_pipeline;
+};
   
   #define HIST_ENTRIES		512

   #define HIST_BAYER   (ISC_HIS_CFG_MODE_B + 1)
@@ -181,80 +203,321 @@ struct isc_device {
struct list_headsubdev_entities;
   };
   
-#define RAW_FMT_IND_START0

-#define RAW_FMT_IND_END  11
-#define ISC_FMT_IND_START12
-#define ISC_FMT_IND_END  14
-
-static struct isc_format isc_formats[] = {
-   { V4L2_PIX_FMT_SBGGR8, MEDIA_BUS_FMT_SBGGR8_1X8, 8,
- ISC_PFE_CFG0_BPS_EIGHT, ISC_BAY_CFG_BGBG, ISC_RLP_CFG_MODE_DAT8,
- ISC_DCFG_IMODE_PACKED8, ISC_DCTRL_DVIEW_PACKED, 0x0,
- false, false },
-   { V4L2_PIX_FMT_SGBRG8, MEDIA_BUS_FMT_SGBRG8_1X8, 8,
- ISC_PFE_CFG0_BPS_EIGHT, ISC_BAY_CFG_GBGB, ISC_RLP_CFG_MODE_DAT8,
- ISC_DCFG_IMODE_PACKED8, ISC_DCTRL_DVIEW_PACKED, 0x0,
- false, false },
-   { V4L2_PIX_FMT_SGRBG8, MEDIA_BUS_FMT_SGRBG8_1X8, 8,
- ISC_PFE_CFG0_BPS_EIGHT, ISC_BAY_CFG_GRGR, ISC_RLP_CFG_MODE_DAT8,
- ISC_DCFG_IMODE_PACKED8, ISC_DCTRL_DVIEW_PACKED, 0x0,
- false, false },
-   { V4L2_PIX_FMT_SRGGB8, MEDIA_BUS_FMT_SRGGB8_1X8, 8,
- ISC_PFE_CFG0_BPS_EIGHT, ISC_BAY_CFG_RGRG, ISC_RLP_CFG_MODE_DAT8,
- ISC_DCFG_IMODE_PACKED8, ISC_DCTRL_DVIEW_PACKED, 0x0,
- false, false },
-
-   { V4L2_PIX_FMT_SBGGR10, MEDIA_BUS_FMT_SBGGR10_1X10, 16,
- ISC_PFG_CFG0_BPS_TEN, ISC_BAY_CFG_BGBG, ISC_RLP_CFG_MODE_DAT10,
- ISC_DCFG_IMODE_PACKED16, ISC_DCTRL_DVIEW_PACKED, 0x0,
- false, false },
-   { V4L2_PIX_FMT_SGBRG10, MEDIA_BUS_FMT_SGBRG10_1X10, 16,
- ISC_PFG_CFG0_BPS_TEN, ISC_BAY_CFG_GBGB, ISC_RLP_CFG_MODE_DAT10,
- ISC_DCFG_IMODE_PACKED16, ISC_DCTRL_DVIEW_PACKED, 0x0,
- 

cron job: media_tree daily build: ERRORS

[Hans Verkuil]

This message is generated daily by a cron job that builds media_tree for
the kernels and architectures in the list below.

Results of the daily build of media_tree:

date:   Thu Sep 28 05:00:15 CEST 2017
media-tree git hash:d5426f4c2ebac8cf05de43988c3fccddbee13d28
media_build git hash:   b829b621b4c2e6c5cbedbd1ce62b4e958f7d13a4
v4l-utils git hash: 8be65674f9a57e4bc35858f86bb5489f0afd22c1
gcc version:i686-linux-gcc (GCC) 7.1.0
sparse version: v0.5.0
smatch version: v0.5.0-3553-g78b2ea6
host hardware:  x86_64
host os:4.12.0-164

linux-git-arm-at91: OK
linux-git-arm-davinci: OK
linux-git-arm-multi: OK
linux-git-arm-pxa: OK
linux-git-arm-stm32: OK
linux-git-blackfin-bf561: OK
linux-git-i686: OK
linux-git-m32r: OK
linux-git-mips: OK
linux-git-powerpc64: OK
linux-git-sh: OK
linux-git-x86_64: OK
linux-2.6.36.4-i686: ERRORS
linux-2.6.37.6-i686: ERRORS
linux-2.6.38.8-i686: ERRORS
linux-2.6.39.4-i686: ERRORS
linux-3.0.60-i686: ERRORS
linux-3.1.10-i686: ERRORS
linux-3.2.37-i686: ERRORS
linux-3.3.8-i686: WARNINGS
linux-3.4.27-i686: WARNINGS
linux-3.5.7-i686: WARNINGS
linux-3.6.11-i686: WARNINGS
linux-3.7.4-i686: WARNINGS
linux-3.8-i686: WARNINGS
linux-3.9.2-i686: WARNINGS
linux-3.10.1-i686: WARNINGS
linux-3.11.1-i686: WARNINGS
linux-3.12.67-i686: WARNINGS
linux-3.13.11-i686: WARNINGS
linux-3.14.9-i686: WARNINGS
linux-3.15.2-i686: WARNINGS
linux-3.16.7-i686: WARNINGS
linux-3.17.8-i686: WARNINGS
linux-3.18.7-i686: WARNINGS
linux-3.19-i686: WARNINGS
linux-4.0.9-i686: WARNINGS
linux-4.1.33-i686: WARNINGS
linux-4.2.8-i686: WARNINGS
linux-4.3.6-i686: WARNINGS
linux-4.4.22-i686: WARNINGS
linux-4.5.7-i686: WARNINGS
linux-4.6.7-i686: WARNINGS
linux-4.7.5-i686: WARNINGS
linux-4.8-i686: OK
linux-4.9.26-i686: OK
linux-4.10.14-i686: OK
linux-4.11-i686: OK
linux-4.12.1-i686: OK
linux-4.13-i686: OK
linux-2.6.36.4-x86_64: ERRORS
linux-2.6.37.6-x86_64: ERRORS
linux-2.6.38.8-x86_64: ERRORS
linux-2.6.39.4-x86_64: ERRORS
linux-3.0.60-x86_64: ERRORS
linux-3.1.10-x86_64: ERRORS
linux-3.2.37-x86_64: ERRORS
linux-3.3.8-x86_64: WARNINGS
linux-3.4.27-x86_64: WARNINGS
linux-3.5.7-x86_64: WARNINGS
linux-3.6.11-x86_64: WARNINGS
linux-3.7.4-x86_64: WARNINGS
linux-3.8-x86_64: WARNINGS
linux-3.9.2-x86_64: WARNINGS
linux-3.10.1-x86_64: WARNINGS
linux-3.11.1-x86_64: WARNINGS
linux-3.12.67-x86_64: WARNINGS
linux-3.13.11-x86_64: WARNINGS
linux-3.14.9-x86_64: WARNINGS
linux-3.15.2-x86_64: WARNINGS
linux-3.16.7-x86_64: WARNINGS
linux-3.17.8-x86_64: WARNINGS
linux-3.18.7-x86_64: WARNINGS
linux-3.19-x86_64: WARNINGS
linux-4.0.9-x86_64: WARNINGS
linux-4.1.33-x86_64: WARNINGS
linux-4.2.8-x86_64: WARNINGS
linux-4.3.6-x86_64: WARNINGS
linux-4.4.22-x86_64: WARNINGS
linux-4.5.7-x86_64: WARNINGS
linux-4.6.7-x86_64: WARNINGS
linux-4.7.5-x86_64: WARNINGS
linux-4.8-x86_64: WARNINGS
linux-4.9.26-x86_64: WARNINGS
linux-4.10.14-x86_64: WARNINGS
linux-4.11-x86_64: WARNINGS
linux-4.12.1-x86_64: WARNINGS
linux-4.13-x86_64: OK
apps: OK
spec-git: OK

Detailed results are available here:

http://www.xs4all.nl/~hverkuil/logs/Thursday.log

Full logs are available here:

http://www.xs4all.nl/~hverkuil/logs/Thursday.tar.bz2

The Media Infrastructure API from this daily build is here:

http://www.xs4all.nl/~hverkuil/spec/index.html

Re: [PATCH v2 07/13] docs: kernel-doc.rst: add documentation about man pages

[Mauro Carvalho Chehab]

Em Wed, 27 Sep 2017 14:20:03 -0700
Randy Dunlap  escreveu:

> On 09/27/17 14:10, Mauro Carvalho Chehab wrote:
> > kernel-doc-nano-HOWTO.txt has a chapter about man pages  
> 
>   kernel-doc.rst has a chapter (or section)

I actually meant to say that kernel-doc-nano-HOWTO.txt has a chapter
about man pages, but such chapter is missing at kernel-doc.rst.

I'll make it clearer at the patch's description.

Thanks!
Mauro

> 
> > production. While we don't have a working  "make manpages"
> > target, add it.
> > 
> > Signed-off-by: Mauro Carvalho Chehab 
> > ---
> >  Documentation/doc-guide/kernel-doc.rst | 34 
> > ++
> >  1 file changed, 34 insertions(+)
> > 
> > diff --git a/Documentation/doc-guide/kernel-doc.rst 
> > b/Documentation/doc-guide/kernel-doc.rst
> > index 0923c8bd5769..96012f9e314d 100644
> > --- a/Documentation/doc-guide/kernel-doc.rst
> > +++ b/Documentation/doc-guide/kernel-doc.rst  
> 
> 



Thanks,
Mauro

Re: [PATCH v7 4/7] media: open.rst: document devnode-centric and mc-centric types

[Mauro Carvalho Chehab]

Hi Randy,

Em Wed, 27 Sep 2017 15:32:12 -0700
Randy Dunlap  escreveu:

> > +Types of V4L2 media hardware control
> > +
> > +
> > +V4L2 hardware periferal is usually complex: support for it is  
> 
>  peripheral (in several places...)

Thanks for noticing! My brain is hardwired to automatically replace
ph -> f, as "ph" only exists on archaic Brazilian Portuguese ;-)

Just fixed everything with:

$ git filter-branch -f --tree-filter 'for i in $(git grep -l periferal 
Documentation/media); do sed s,periferal,peripheral,g -i $i; done' v4.14-rc1..

And pushed to my development's tree:

https://git.linuxtv.org/mchehab/experimental.git/log/?h=mc-centric-flag-v7

Thanks,
Mauro

HYVÄÄ PÄIVÄÄ!

[CAROLINE FRND]

Hyvää päivää!

Olen varma, että tämä posti olisi tulossa teille yllätyksenä, koska emme 
ole koskaan ennen tavannut, ja voit myös kysyä, miksi olen päättänyt 
valitsi sinulle joukossa lukuisia internetin käyttäjiä maailmassa. Sain 
sähköpostiosoitteesi läpi profiilin Internetissä, joka on tehnyt minua 
saavuttamaan pyyntöni.


Olen Caroline Freund, Bill ja Exchange Manager Cahoot Finance UK. 
Osastossani huomasin hylätyn 8 000 000 dollarin summan. (Kahdeksan 
miljoonaa) yhdelle ulkomaiselle asiakkaalle (Paul Louis Halley). Tämä 
asiakas ja hänen vaimonsa kuolivat vuoden 2003 kone-onnettomuudessa. 
Voit tarkastella alla olevaa sivua saadaksesi lisätietoja.

http://newswww.bbc.net.uk/2/hi/uk_news/england/oxfordshire/4537663.stm

Asiakas myöhään Paul Louis Halley polkumyynnillä $ 8,000,000.00 hänen 
pankkitilille minun pankki vuodesta 2003 tähän päivään.


Käytyään läpi myöhään Paul Louis Halley tiedosto pankissa, olen 
huomannut, että hän ei sisältänyt lähiomaiset tälle tilille ennen 
kuolemaansa vuonna 2003.


Siksi olen nyt hyvässä uskossa ja tietoisesti pyrkiä suostumustasi 
esitellä teille kuin lähiomaiset / Will edunsaajaa kuolleen jotta 
kokonaisarvo $ 8.000.000 siirretään pankkitilille Suomessa, johon meidän 
on jakaa tämän prosenttiosuuden suhde on 60% minulle ja 40% sinulle.


Pankin vuoden 1990 politiikan mukaan, jos tämän perinnön vastaanottaja 
ei ole hakenut rahaston vaatimusta kolmetoista (13) vuoden jälkeen, 
rahat tulevat Yhdistyneen kuningaskunnan hallituksen omaisuudeksi, enkä 
halua, että se toteutuu.


Siksi olen nyt hyvässä uskossa ja tietoisesti pyrkiä suostumustasi 
esitellä teille kuin lähiomaiset / Will edunsaajaa kuolleen jotta 
kokonaisarvo $ 8.000.000 siirretään pankkitilin Suomessa, jossa meillä 
on jakaa tämä prosenttiosuus suhde on 60% minulle ja 40% menee teille.


Haluan vakuuttaa teille, ettei ole mitään haittaa tai riskiä; Kauppa 
tapahtuu sähköpostilla pankille ja annan sinulle kaikki asiakirjat, 
joita pankki voi vaatia.


Lisätietoja; Haluan, että otat yhteyden minuun yksityisellä 
sähköpostiosoitteellani: carolinefreun...@yahoo.com


Kun yhteyttä minuun, minä annan sinulle enemmän tietoa.

Ystävällisin terveisin,
Caroline ystävä

Re: [PATCH v7 4/7] media: open.rst: document devnode-centric and mc-centric types

[Randy Dunlap]

On 09/27/17 15:23, Mauro Carvalho Chehab wrote:
> 
> Signed-off-by: Mauro Carvalho Chehab 
> ---
>  Documentation/media/uapi/v4l/open.rst | 40 
> +++
>  1 file changed, 40 insertions(+)
> 
> diff --git a/Documentation/media/uapi/v4l/open.rst 
> b/Documentation/media/uapi/v4l/open.rst
> index 18030131ef77..f603bc9b49a0 100644
> --- a/Documentation/media/uapi/v4l/open.rst
> +++ b/Documentation/media/uapi/v4l/open.rst
> @@ -7,6 +7,46 @@ Opening and Closing Devices
>  ***
>  
>  
> +.. _v4l2_hardware_control:
> +
> +
> +Types of V4L2 media hardware control
> +
> +
> +V4L2 hardware periferal is usually complex: support for it is

 peripheral (in several places...)

> +implemented via a V4L2 main driver and often by several additional drivers.
> +The main driver always exposes one or more **V4L2 device nodes**
> +(see :ref:`v4l2_device_naming`) with are responsible for implementing
> +data streaming, if applicable.
> +
> +The other drivers are called **V4L2 sub-devices** and provide control to
> +other hardware components usually connected via a serial bus (like
> +I²C, SMBus or SPI). Depending on the main driver, they can be implicitly
> +controlled directly by the main driver or explicitly via
> +the **V4L2 sub-device API** (see :ref:`subdev`).
> +
> +When V4L2 was originally designed, there was only one type of
> +media hardware control: via the **V4L2 device nodes**. We refer to this kind
> +of control as **V4L2 device node centric** (or, simply, 
> "**vdevnode-centric**").
> +
> +Later (kernel 2.6.39), a new type of periferal control was
> +added in order to support complex media hardware that are common for embedded
> +systems. This type of periferal is controlled mainly via the media
> +controller and V4L2 sub-devices. So, it is called
> +**Media controller centric** (or, simply, "**MC-centric**") control.
> +
> +For **vdevnode-centric** media hardware control, the media hardware is
> +controlled via the **V4L2 device nodes**. They may optionally support the
> +:ref:`media controller API ` as well,
> +in order to inform the application which device nodes are available
> +(see :ref:`related`).
> +
> +For **MC-centric** media hardware control it is required to configure
> +the pipelines via the :ref:`media controller API ` before
> +the periferal can be used. For such devices, the sub-devices' configuration
> +can be controlled via the :ref:`sub-device API `, which creates one
> +device node per sub-device.
> +
>  .. _v4l2_device_naming:
>  
>  V4L2 Device Node Naming
> 


-- 
~Randy

[PATCH v7 4/7] media: open.rst: document devnode-centric and mc-centric types

[Mauro Carvalho Chehab]

When we added support for omap3, back in 2010, we added a new
type of V4L2 devices that aren't fully controlled via the V4L2
device node.

Yet, we have never clearly documented in the V4L2 specification
the differences between the two types.

Let's document them based on the the current implementation.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/media/uapi/v4l/open.rst | 40 +++
 1 file changed, 40 insertions(+)

diff --git a/Documentation/media/uapi/v4l/open.rst 
b/Documentation/media/uapi/v4l/open.rst
index 18030131ef77..f603bc9b49a0 100644
--- a/Documentation/media/uapi/v4l/open.rst
+++ b/Documentation/media/uapi/v4l/open.rst
@@ -7,6 +7,46 @@ Opening and Closing Devices
 ***
 
 
+.. _v4l2_hardware_control:
+
+
+Types of V4L2 media hardware control
+
+
+V4L2 hardware periferal is usually complex: support for it is
+implemented via a V4L2 main driver and often by several additional drivers.
+The main driver always exposes one or more **V4L2 device nodes**
+(see :ref:`v4l2_device_naming`) with are responsible for implementing
+data streaming, if applicable.
+
+The other drivers are called **V4L2 sub-devices** and provide control to
+other hardware components usually connected via a serial bus (like
+I²C, SMBus or SPI). Depending on the main driver, they can be implicitly
+controlled directly by the main driver or explicitly via
+the **V4L2 sub-device API** (see :ref:`subdev`).
+
+When V4L2 was originally designed, there was only one type of
+media hardware control: via the **V4L2 device nodes**. We refer to this kind
+of control as **V4L2 device node centric** (or, simply, 
"**vdevnode-centric**").
+
+Later (kernel 2.6.39), a new type of periferal control was
+added in order to support complex media hardware that are common for embedded
+systems. This type of periferal is controlled mainly via the media
+controller and V4L2 sub-devices. So, it is called
+**Media controller centric** (or, simply, "**MC-centric**") control.
+
+For **vdevnode-centric** media hardware control, the media hardware is
+controlled via the **V4L2 device nodes**. They may optionally support the
+:ref:`media controller API ` as well,
+in order to inform the application which device nodes are available
+(see :ref:`related`).
+
+For **MC-centric** media hardware control it is required to configure
+the pipelines via the :ref:`media controller API ` before
+the periferal can be used. For such devices, the sub-devices' configuration
+can be controlled via the :ref:`sub-device API `, which creates one
+device node per sub-device.
+
 .. _v4l2_device_naming:
 
 V4L2 Device Node Naming
-- 
2.13.5

[PATCH v7 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec

[Mauro Carvalho Chehab]

Add a glossary of terms for V4L2, as several concepts are complex
enough to cause misunderstandings.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/media/uapi/v4l/glossary.rst | 136 ++
 Documentation/media/uapi/v4l/v4l2.rst |   1 +
 2 files changed, 137 insertions(+)
 create mode 100644 Documentation/media/uapi/v4l/glossary.rst

diff --git a/Documentation/media/uapi/v4l/glossary.rst 
b/Documentation/media/uapi/v4l/glossary.rst
new file mode 100644
index ..b6767da1a46e
--- /dev/null
+++ b/Documentation/media/uapi/v4l/glossary.rst
@@ -0,0 +1,136 @@
+
+Glossary
+
+
+.. note::
+
+   This goal of section is to standardize the terms used within the V4L2
+   documentation. It is written incrementally as they are standardized in
+   the V4L2 documentation. So, it is a Work In Progress.
+
+.. Please keep the glossary entries in alphabetical order
+
+.. glossary::
+
+Bridge driver
+   The same as V4L2 main driver.
+
+Device Node
+   A character device node in the file system used to control and do
+   input/output data transfers from/to a Kernel driver.
+
+Digital Signal Processor - DSP
+   A specialized microprocessor, with its architecture optimized for
+   the operational needs of digital signal processing.
+
+Driver
+   The part of the Linux Kernel that implements support
+   for a hardware component.
+
+Field-programmable Gate Array - FPGA
+   A field-programmable gate array (FPGA) is an integrated circuit
+   designed to be configured by a customer or a designer after
+   manufacturing.
+
+   See https://en.wikipedia.org/wiki/Field-programmable_gate_array.
+
+Hardware component
+   A subset of the media hardware. For example an I²C or SPI device,
+   or an IP block inside an SoC or FPGA.
+
+Image Signal Processor - ISP
+   A specialised processor that implements a set of algorithms for
+   processing image data. ISPs may implement algorithms for lens
+   shading correction, demosaic, scaling and pixel format conversion
+   as well as produce statistics for the use of the control
+   algorithms (e.g. automatic exposure, white balance and focus).
+
+Inter-Integrated Circuit - I²C
+   A  multi-master, multi-slave, packet switched, single-ended,
+   serial computer bus used to control V4L2 sub-devices.
+
+   See http://www.nxp.com/docs/en/user-guide/UM10204.pdf.
+
+Integrated circuit - IC
+   A set of electronic circuits on one small flat piece of
+   semiconductor material, normally silicon.
+
+   Also known as chip.
+
+Intellectual property core - IP core
+   In electronic design a semiconductor intellectual property core,
+   is a reusable unit of logic, cell, or integrated circuit layout
+   design that is the intellectual property of one party.
+   IP cores may be licensed to another party or can be owned
+   and used by a single party alone.
+
+   See 
https://en.wikipedia.org/wiki/Semiconductor_intellectual_property_core).
+
+IP block
+   The same as IP core.
+
+MC-centric
+   V4L2 hardware that requires a Media controller.
+
+   See :ref:`v4l2_hardware_control`.
+
+Media Controller
+   An API designed to expose and control devices and sub-devices
+   relationships to applications.
+
+   See :ref:`media_controller`.
+
+Media hardware
+   A group of hardware components that together make a larger
+   user-facing functional media hardware. For instance the SoC ISP IP
+   cores and external camera sensors together make a
+   camera media hardware.
+
+Media hardware control
+   Type of control for a media hardware supported by V4L2 drivers.
+
+   See :ref:`v4l2_hardware_control`.
+
+Microprocessor
+   An electronic circuitry that carries out the instructions
+   of a computer program by performing the basic arithmetic, logical,
+   control and input/output (I/O) operations specified by the
+   instructions on a single integrated circuit.
+
+SMBus
+   A subset of I²C, with defines a stricter usage of the bus.
+
+Serial Peripheral Interface Bus - SPI
+   Synchronous serial communication interface specification used for
+   short distance communication, primarily in embedded systems.
+
+System on a Chip - SoC
+   An integrated circuit that integrates all components of a computer
+   or other electronic systems.
+
+V4L2 device node
+   A device node that is associated to a V4L2 main driver,
+   as specified in :ref:`v4l2_device_naming`.
+
+V4L2 hardware
+   A hardware used to on a media device supported by the V4L2
+   subsystem.
+
+V4L2 main driver
+   The V4L2 device driver that implements the main logic to talk with
+   the V4L2 hardware.
+
+   Also known as bridge driver.
+
+   See 

[PATCH v7 6/7] media: videodev2: add a flag for MC-centric devices

[Mauro Carvalho Chehab]

As both vdev-centric and MC-centric devices may implement the
same APIs, we need a flag to allow userspace to distinguish
between them.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/media/uapi/v4l/open.rst| 7 +++
 Documentation/media/uapi/v4l/vidioc-querycap.rst | 5 +
 Documentation/media/videodev2.h.rst.exceptions   | 1 +
 include/uapi/linux/videodev2.h   | 2 ++
 4 files changed, 15 insertions(+)

diff --git a/Documentation/media/uapi/v4l/open.rst 
b/Documentation/media/uapi/v4l/open.rst
index 0daf0c122c19..75ccc9d6614d 100644
--- a/Documentation/media/uapi/v4l/open.rst
+++ b/Documentation/media/uapi/v4l/open.rst
@@ -47,6 +47,13 @@ the periferal can be used. For such devices, the 
sub-devices' configuration
 can be controlled via the :ref:`sub-device API `, which creates one
 device node per sub-device.
 
+.. attention::
+
+   Devices that require **MC-centric** media hardware control should
+   report a ``V4L2_MC_CENTRIC`` :c:type:`v4l2_capability` flag
+   (see :ref:`VIDIOC_QUERYCAP`).
+
+
 .. _v4l2_device_naming:
 
 V4L2 Device Node Naming
diff --git a/Documentation/media/uapi/v4l/vidioc-querycap.rst 
b/Documentation/media/uapi/v4l/vidioc-querycap.rst
index 66fb1b3d6e6e..944bc5ba484f 100644
--- a/Documentation/media/uapi/v4l/vidioc-querycap.rst
+++ b/Documentation/media/uapi/v4l/vidioc-querycap.rst
@@ -254,6 +254,11 @@ specification the ioctl returns an ``EINVAL`` error code.
 * - ``V4L2_CAP_TOUCH``
   - 0x1000
   - This is a touch device.
+* - ``V4L2_MC_CENTRIC``
+  - 0x2000
+  - Indicates that the device require **MC-centric** hardware
+control, and thus can't be used by **vdevnode-centric** applications.
+See :ref:`v4l2_hardware_control` for more details.
 * - ``V4L2_CAP_DEVICE_CAPS``
   - 0x8000
   - The driver fills the ``device_caps`` field. This capability can
diff --git a/Documentation/media/videodev2.h.rst.exceptions 
b/Documentation/media/videodev2.h.rst.exceptions
index a5cb0a8686ac..b51a575f9f75 100644
--- a/Documentation/media/videodev2.h.rst.exceptions
+++ b/Documentation/media/videodev2.h.rst.exceptions
@@ -157,6 +157,7 @@ replace define V4L2_CAP_META_CAPTURE device-capabilities
 replace define V4L2_CAP_READWRITE device-capabilities
 replace define V4L2_CAP_ASYNCIO device-capabilities
 replace define V4L2_CAP_STREAMING device-capabilities
+replace define V4L2_CAP_MC_CENTRIC device-capabilities
 replace define V4L2_CAP_DEVICE_CAPS device-capabilities
 replace define V4L2_CAP_TOUCH device-capabilities
 
diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
index 185d6a0acc06..4ff1224719a7 100644
--- a/include/uapi/linux/videodev2.h
+++ b/include/uapi/linux/videodev2.h
@@ -460,6 +460,8 @@ struct v4l2_capability {
 
 #define V4L2_CAP_TOUCH  0x1000  /* Is a touch device */
 
+#define V4L2_CAP_MC_CENTRIC 0x2000  /* Device require 
MC-centric hardware control */
+
 #define V4L2_CAP_DEVICE_CAPS0x8000  /* sets device 
capabilities field */
 
 /*
-- 
2.13.5

[PATCH v7 2/7] media: open.rst: better document device node naming

[Mauro Carvalho Chehab]

Right now, only kAPI documentation describes the device naming.
However, such description is needed at the uAPI too. Add it,
and describe how to get an unique identify for a given device.

Acked-by: Hans Verkuil 
Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/media/uapi/v4l/open.rst | 44 ---
 1 file changed, 41 insertions(+), 3 deletions(-)

diff --git a/Documentation/media/uapi/v4l/open.rst 
b/Documentation/media/uapi/v4l/open.rst
index afd116edb40d..7e7aad784388 100644
--- a/Documentation/media/uapi/v4l/open.rst
+++ b/Documentation/media/uapi/v4l/open.rst
@@ -7,12 +7,14 @@ Opening and Closing Devices
 ***
 
 
-Device Naming
-=
+.. _v4l2_device_naming:
+
+V4L2 Device Node Naming
+===
 
 V4L2 drivers are implemented as kernel modules, loaded manually by the
 system administrator or automatically when a device is first discovered.
-The driver modules plug into the "videodev" kernel module. It provides
+The driver modules plug into the ``videodev`` kernel module. It provides
 helper functions and a common application interface specified in this
 document.
 
@@ -23,6 +25,42 @@ option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor 
numbers
 are allocated in ranges depending on the device node type (video, radio,
 etc.).
 
+The existing V4L2 device node types are:
+
+ ==
+Default device node name Usage
+ ==
+``/dev/videoX`` Video input/output devices
+``/dev/vbiX``   Vertical blank data (i.e. closed captions, teletext)
+``/dev/radioX`` Radio tuners and modulators
+``/dev/swradioX``   Software Defined Radio tuners and modulators
+``/dev/v4l-touchX`` Touch sensors
+ ==
+
+Where ``X`` is a non-negative number.
+
+.. note::
+
+   1. The actual device node name is system-dependent, as udev rules may apply.
+   2. There is no guarantee that ``X`` will remain the same for the same
+  device, as the number depends on the device driver's probe order.
+  If you need an unique name, udev default rules produce
+  ``/dev/v4l/by-id/`` and ``/dev/v4l/by-path/`` directories containing
+  links that can be used uniquely to identify a V4L2 device node::
+
+   $ tree /dev/v4l
+   /dev/v4l
+   ├── by-id
+   │   └── usb-OmniVision._USB_Camera-B4.04.27.1-video-index0 -> 
../../video0
+   └── by-path
+   └── pci-:00:14.0-usb-0:2:1.0-video-index0 -> ../../video0
+
+   3. **V4L2 sub-device nodes** (e. g. ``/dev/v4l-sudevX``) provide a
+  different API and aren't considered as V4L2 device nodes.
+
+  They are covered at :ref:`subdev`.
+
+
 Many drivers support "video_nr", "radio_nr" or "vbi_nr" module
 options to select specific video/radio/vbi node numbers. This allows the
 user to request that the device node is named e.g. /dev/video5 instead
-- 
2.13.5

[PATCH v7 0/7] document types of hardware control for V4L2

[Mauro Carvalho Chehab]

On Kernel 2.6.39, the omap3 driver was introduced together with a new way
to control complex V4L2 devices used on embedded systems, but this was
never documented, as the original idea were to have "soon" support for
standard apps to use it as well, via libv4l, but that didn't happen so far.

Also, it is not possible for an userspace applicatin to detect the kind of
control a device supports.

This series fill the gap, by documenting the new type of hardware
control and adding a way for userspace to detect if the device can be
used or not by an standard V4L2 application.

Notes:


1) For the sake of better review, this series start with the addition of a
glossary, as requested by Laurent. Please notice, however, that
the glossary there references some new captions that will only be added
by subsequent patches. So, when this series get applied, the glossary
patch should actually be merged after the patches that introduce those
new captions, in order to avoid warnings for non-existing references.

2) This series doesn't contain patches that actually use the new flag.
This will be added after such patch gets reviewed.

v7:
- Altered some nomenclature at the glossary as suggested by Hans
  and used git-filter to change it on all patches.

v6:
- Some editorial changes based on comments from Hans and Sakari.

v5:
- Added more terms to the glossary
- Adjusted some wording as proposed by Hans on a few patches
  and added his ack on others

v4:

- Addressed Hans comments for v2;
- Fixed broken references at the glossary.rst

v3:

- Add a glossary to be used by the new documentation about hardware control;
- Add a patch removing minor number range
- Use glossary terms at open.rst
- Split the notice about subdev-API on vdev-centric, as this change
   will require further discussions.

v2:

- added a patch at the beginning of the series better defining the
  device node naming rules;
- better defined the differenes between device hardware and V4L2 device node
  as suggested by Laurent and with changes proposed by Hans and Sakari
- changed the caps flag to indicate MC-centric devices
- removed the final patch that would use the new caps flag. I'll write it
  once we agree on the new caps flag.

Mauro Carvalho Chehab (7):
  media: add glossary.rst with a glossary of terms used at V4L2 spec
  media: open.rst: better document device node naming
  media: open.rst: remove the minor number range
  media: open.rst: document devnode-centric and mc-centric types
  media: open.rst: Adjust some terms to match the glossary
  media: videodev2: add a flag for MC-centric devices
  media: open.rst: add a notice about subdev-API on vdev-centric

 Documentation/media/uapi/v4l/glossary.rst| 136 +++
 Documentation/media/uapi/v4l/open.rst| 119 +---
 Documentation/media/uapi/v4l/v4l2.rst|   1 +
 Documentation/media/uapi/v4l/vidioc-querycap.rst |   5 +
 Documentation/media/videodev2.h.rst.exceptions   |   1 +
 include/uapi/linux/videodev2.h   |   2 +
 6 files changed, 250 insertions(+), 14 deletions(-)
 create mode 100644 Documentation/media/uapi/v4l/glossary.rst

-- 
2.13.5

[PATCH v7 3/7] media: open.rst: remove the minor number range

[Mauro Carvalho Chehab]

minor numbers use to range between 0 to 255, but that
was changed a long time ago. While it still applies when
CONFIG_VIDEO_FIXED_MINOR_RANGES, when the minor number is
dynamically allocated, this may not be true. In any case,
this is not relevant, as udev will take care of it.

So, remove this useless misinformation.

Acked-by: Hans Verkuil 
Acked-by: Sakari Ailus 
Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/media/uapi/v4l/open.rst | 9 -
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/Documentation/media/uapi/v4l/open.rst 
b/Documentation/media/uapi/v4l/open.rst
index 7e7aad784388..18030131ef77 100644
--- a/Documentation/media/uapi/v4l/open.rst
+++ b/Documentation/media/uapi/v4l/open.rst
@@ -19,11 +19,10 @@ helper functions and a common application interface 
specified in this
 document.
 
 Each driver thus loaded registers one or more device nodes with major
-number 81 and a minor number between 0 and 255. Minor numbers are
-allocated dynamically unless the kernel is compiled with the kernel
-option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers
-are allocated in ranges depending on the device node type (video, radio,
-etc.).
+number 81. Minor numbers are allocated dynamically unless the kernel
+is compiled with the kernel option CONFIG_VIDEO_FIXED_MINOR_RANGES.
+In that case minor numbers are allocated in ranges depending on the
+device node type.
 
 The existing V4L2 device node types are:
 
-- 
2.13.5

[PATCH v7 5/7] media: open.rst: Adjust some terms to match the glossary

[Mauro Carvalho Chehab]

As we now have a glossary, some terms used on open.rst
require adjustments.

Acked-by: Hans Verkuil 
Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/media/uapi/v4l/open.rst | 12 ++--
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/media/uapi/v4l/open.rst 
b/Documentation/media/uapi/v4l/open.rst
index f603bc9b49a0..0daf0c122c19 100644
--- a/Documentation/media/uapi/v4l/open.rst
+++ b/Documentation/media/uapi/v4l/open.rst
@@ -143,7 +143,7 @@ Related Devices
 Devices can support several functions. For example video capturing, VBI
 capturing and radio support.
 
-The V4L2 API creates different nodes for each of these functions.
+The V4L2 API creates different V4L2 device nodes for each of these functions.
 
 The V4L2 API was designed with the idea that one device node could
 support all functions. However, in practice this never worked: this
@@ -153,17 +153,17 @@ switching a device node between different functions only 
works when
 using the streaming I/O API, not with the
 :ref:`read() `/\ :ref:`write() ` API.
 
-Today each device node supports just one function.
+Today each V4L2 device node supports just one function.
 
 Besides video input or output the hardware may also support audio
 sampling or playback. If so, these functions are implemented as ALSA PCM
 devices with optional ALSA audio mixer devices.
 
 One problem with all these devices is that the V4L2 API makes no
-provisions to find these related devices. Some really complex devices
-use the Media Controller (see :ref:`media_controller`) which can be
-used for this purpose. But most drivers do not use it, and while some
-code exists that uses sysfs to discover related devices (see
+provisions to find these related V4L2 device nodes. Some really complex
+hardware use the Media Controller (see :ref:`media_controller`) which can
+be used for this purpose. But several drivers do not use it, and while some
+code exists that uses sysfs to discover related V4L2 device nodes (see
 libmedia_dev in the
 `v4l-utils `__ git
 repository), there is no library yet that can provide a single API
-- 
2.13.5

[PATCH v7 7/7] media: open.rst: add a notice about subdev-API on vdev-centric

[Mauro Carvalho Chehab]

The documentation doesn't mention if vdev-centric hardware
control would have subdev API or not.

Add a notice about that, reflecting the current status, where
three drivers use it, in order to support some subdev-specific
controls.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/media/uapi/v4l/open.rst | 7 +++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/media/uapi/v4l/open.rst 
b/Documentation/media/uapi/v4l/open.rst
index 75ccc9d6614d..ed011ed123cc 100644
--- a/Documentation/media/uapi/v4l/open.rst
+++ b/Documentation/media/uapi/v4l/open.rst
@@ -47,6 +47,13 @@ the periferal can be used. For such devices, the 
sub-devices' configuration
 can be controlled via the :ref:`sub-device API `, which creates one
 device node per sub-device.
 
+.. note::
+
+   A **vdevnode-centric** may also optionally expose V4L2 sub-devices via
+   :ref:`sub-device API `. In that case, it has to implement
+   the :ref:`media controller API ` as well.
+
+
 .. attention::
 
Devices that require **MC-centric** media hardware control should
-- 
2.13.5

Re: [PATCH v6 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec

[Mauro Carvalho Chehab]

Em Fri, 1 Sep 2017 12:26:39 +0200
Hans Verkuil  escreveu:

> On 29/08/17 15:17, Mauro Carvalho Chehab wrote:
> > Add a glossary of terms for V4L2, as several concepts are complex
> > enough to cause misunderstandings.
> > 
> > Signed-off-by: Mauro Carvalho Chehab 
> > ---
> >  Documentation/media/uapi/v4l/glossary.rst | 150 
> > ++
> >  Documentation/media/uapi/v4l/v4l2.rst |   1 +
> >  2 files changed, 151 insertions(+)
> >  create mode 100644 Documentation/media/uapi/v4l/glossary.rst
> > 
> > diff --git a/Documentation/media/uapi/v4l/glossary.rst 
> > b/Documentation/media/uapi/v4l/glossary.rst
> > new file mode 100644
> > index ..afafe1bc1894
> > --- /dev/null
> > +++ b/Documentation/media/uapi/v4l/glossary.rst
> > @@ -0,0 +1,150 @@
> > +
> > +Glossary
> > +
> > +
> > +.. note::
> > +
> > +   This goal of section is to standardize the terms used within the V4L2
> > +   documentation. It is written incrementally as they are standardized in
> > +   the V4L2 documentation. So, it is a Work In Progress.
> > +
> > +.. Please keep the glossary entries in alphabetical order
> > +
> > +.. glossary::
> > +
> > +Bridge driver
> > +   The same as V4L2 main driver.
> > +
> > +Device Node
> > +   A character device node in the file system used to control and do
> > +   input/output data transfers from/to a Kernel driver.
> > +
> > +Digital Signal Processor - DSP
> > +   A specialized microprocessor, with its architecture optimized for
> > +   the operational needs of digital signal processing.
> > +
> > +Driver
> > +   The part of the Linux Kernel that implements support
> > +   for a hardware component.
> > +
> > +Field-programmable Gate Array - FPGA
> > +   A field-programmable gate array (FPGA) is an integrated circuit
> > +   designed to be configured by a customer or a designer after
> > +   manufacturing.
> > +
> > +   See https://en.wikipedia.org/wiki/Field-programmable_gate_array.
> > +
> > +Hardware component
> > +   A subset of the media hardware. For example an I²C or SPI device,
> > +   or an IP block inside an SoC or FPGA.
> > +
> > +Hardware peripheral  
> 
> As I mentioned before, I really don't like the term 'peripheral'. I am
> fine with "Media hardware". A peripheral to me are keyboards, mice, webcams,
> printers, etc. Not an SoC with a CSI sensor on the board.
> 
> > +   A group of hardware components that together make a larger
> > +   user-facing functional peripheral. For instance the SoC ISP IP
> > +   cores and external camera sensors together make a
> > +   camera hardware peripheral.
> > +
> > +   Also known as peripheral.
> > +
> > +Hardware peripheral control  
> 
> So this would become "Media hardware control"
> 
> > +   Type of control for a hardware peripheral supported by V4L2 drivers.
> > +
> > +   See :ref:`v4l2_hardware_control`.
> > +
> > +Inter-Integrated Circuit - I²C
> > +   A  multi-master, multi-slave, packet switched, single-ended,
> > +   serial computer bus used to control V4L2 sub-devices.
> > +
> > +   See http://www.nxp.com/docs/en/user-guide/UM10204.pdf.
> > +
> > +Integrated circuit - IC
> > +   A set of electronic circuits on one small flat piece of
> > +   semiconductor material, normally silicon.
> > +
> > +   Also known as chip.
> > +
> > +IP block
> > +   The same as IP core.
> > +
> > +Intelectual property core - IP core  
> 
> Typo: Intellectual
> 
> > +   In electronic design a semiconductor intellectual property core,
> > +   is a reusable unit of logic, cell, or integrated circuit layout
> > +   design that is the intellectual property of one party.
> > +   IP cores may be licensed to another party or can be owned
> > +   and used by a single party alone.
> > +
> > +   See 
> > https://en.wikipedia.org/wiki/Semiconductor_intellectual_property_core).
> > +
> > +Image Signal Processor - ISP
> > +   A specialised processor that implements a set of algorithms for
> > +   processing image data. ISPs may implement algorithms for lens
> > +   shading correction, demosaic, scaling and pixel format conversion
> > +   as well as produce statistics for the use of the control
> > +   algorithms (e.g. automatic exposure, white balance and focus).
> > +
> > +Peripheral
> > +   The same as hardware peripheral.  
> 
> I'd drop this.
> 
> > +
> > +Media Controller
> > +   An API designed to expose and control devices and sub-devices
> > +   relationships to applications.
> > +
> > +   See :ref:`media_controller`.
> > +
> > +MC-centric
> > +   V4L2 hardware that requires a Media controller.
> > +
> > +   See :ref:`v4l2_hardware_control`.
> > +
> > +Microprocessor
> > +   An electronic circuitry that carries out the instructions
> > +   of a computer program by performing the basic arithmetic, logical,
> > +   control and input/output (I/O) operations specified by the
> > +   instructions on a single 

Re: [RESEND RFC PATCH 4/7] dt-bindings: Document Allwinner DWC HDMI TX node

[Rob Herring]

On Wed, Sep 20, 2017 at 10:01:21PM +0200, Jernej Skrabec wrote:
> Add documentation about Allwinner DWC HDMI TX node, found in H3 SoC.
> 
> Signed-off-by: Jernej Skrabec 
> ---
>  .../bindings/display/sunxi/sun4i-drm.txt   | 158 
> -
>  1 file changed, 157 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt 
> b/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt
> index 92512953943e..cb6aee5c486f 100644
> --- a/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt
> +++ b/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt
> @@ -60,6 +60,40 @@ Required properties:
>  first port should be the input endpoint. The second should be the
>  output, usually to an HDMI connector.
>  
> +DWC HDMI TX Encoder
> +-
> +
> +The HDMI transmitter is a Synopsys DesignWare HDMI 1.4 TX controller IP
> +with Allwinner's own PHY IP. It supports audio and video outputs and CEC.
> +
> +These DT bindings follow the Synopsys DWC HDMI TX bindings defined in
> +Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt with the
> +following device-specific properties.
> +
> +Required properties:
> +
> +  - compatible: value must be one of:
> +* "allwinner,sun8i-h3-dw-hdmi"
> +  - reg: two pairs of base address and size of memory-mapped region, first
> +for controller and second for PHY
> +registers.
> +  - reg-io-width: See dw_hdmi.txt. Shall be 1.
> +  - interrupts: HDMI interrupt number
> +  - clocks: phandles to the clocks feeding the HDMI encoder
> +* iahb: the HDMI interface clock
> +* isfr: the HDMI module clock
> +* ddc: the HDMI ddc clock
> +  - clock-names: the clock names mentioned above
> +  - resets: phandles to the reset controllers driving the encoder
> +* hdmi: the reset line for the HDMI
> +* ddc: the reset line for the DDC
> +  - reset-names: the reset names mentioned above
> +
> +  - ports: A ports node with endpoint definitions as defined in
> +Documentation/devicetree/bindings/media/video-interfaces.txt. The
> +first port should be the input endpoint. The second should be the
> +output, usually to an HDMI connector.
> +
>  TV Encoder
>  --
>  
> @@ -255,7 +289,7 @@ Required properties:
>- allwinner,pipelines: list of phandle to the display engine
>  frontends (DE 1.0) or mixers (DE 2.0) available.
>  
> -Example:
> +Example 1:
>  
>  panel: panel {
>   compatible = "olimex,lcd-olinuxino-43-ts";
> @@ -455,3 +489,125 @@ display-engine {
>   compatible = "allwinner,sun5i-a13-display-engine";
>   allwinner,pipelines = <>;
>  };
> +
> +Example 2:
> +
> +connector {
> + compatible = "hdmi-connector";
> + type = "a";
> +
> + port {
> + hdmi_con_in: endpoint {
> + remote-endpoint = <_out_con>;
> + };
> + };
> +};
> +
> +de: display-engine {
> + compatible = "allwinner,sun8i-h3-display-engine";
> + allwinner,pipelines = <>;
> +};
> +
> +hdmi: hdmi@1ee {
> + compatible = "allwinner,h3-dw-hdmi";
> + reg = <0x01ee 0x1>,
> +   <0x01ef 0x1>;
> + reg-io-width = <1>;
> + interrupts = ;
> + clocks = < CLK_BUS_HDMI>, < CLK_HDMI>,
> +  < CLK_HDMI_DDC>;
> + clock-names = "iahb", "isfr", "ddc";
> + resets = < RST_BUS_HDMI0>, < RST_BUS_HDMI1>;
> + reset-names = "hdmi", "ddc";
> +
> + ports {
> + #address-cells = <1>;
> + #size-cells = <0>;
> +
> + hdmi_in: port@0 {
> + #address-cells = <1>;
> + #size-cells = <0>;
> + reg = <0>;
> +
> + hdmi_in_tcon0: endpoint@0 {
> + reg = <0>;

You don't need reg when there's only one.

Otherwise,

Acked-by: Rob Herring 

Re: [PATCH v3 2/4] [media] dt-bindings: Document BCM283x CSI2/CCP2 receiver

[Rob Herring]

On Fri, Sep 22, 2017 at 05:07:22PM +0100, Dave Stevenson wrote:
> Hi Stefan
> 
> On 22 September 2017 at 07:45, Stefan Wahren  wrote:
> > Hi Dave,
> >
> >> Dave Stevenson  hat am 20. September 2017 
> >> um 18:07 geschrieben:
> >>
> >>
> >> Document the DT bindings for the CSI2/CCP2 receiver peripheral
> >> (known as Unicam) on BCM283x SoCs.
> >>
> >> Signed-off-by: Dave Stevenson 
> >> ---
> >>
> >> Changes since v2
> >> - Removed all references to Linux drivers.
> >> - Reworded section about disabling the firmware driver.
> >> - Renamed clock from "lp_clock" to "lp" in description and example.
> >> - Referred to video-interfaces.txt and stated requirements on 
> >> remote-endpoint
> >>   and data-lanes.
> >> - Corrected typo in example from csi to csi1.
> >> - Removed unnecessary #address-cells and #size-cells in example.
> >> - Removed setting of status from the example.
> >>
> >>  .../devicetree/bindings/media/bcm2835-unicam.txt   | 85 
> >> ++
> >>  1 file changed, 85 insertions(+)
> >>  create mode 100644 
> >> Documentation/devicetree/bindings/media/bcm2835-unicam.txt
> >>
> >> diff --git a/Documentation/devicetree/bindings/media/bcm2835-unicam.txt 
> >> b/Documentation/devicetree/bindings/media/bcm2835-unicam.txt
> >> new file mode 100644
> >> index 000..7714fb3
> >> --- /dev/null
> >> +++ b/Documentation/devicetree/bindings/media/bcm2835-unicam.txt
> >> @@ -0,0 +1,85 @@
> >> +Broadcom BCM283x Camera Interface (Unicam)
> >> +--
> >> +
> >> +The Unicam block on BCM283x SoCs is the receiver for either
> >> +CSI-2 or CCP2 data from image sensors or similar devices.
> >> +
> >> +The main platform using this SoC is the Raspberry Pi family of boards.
> >> +On the Pi the VideoCore firmware can also control this hardware block,
> >> +and driving it from two different processors will cause issues.
> >> +To avoid this, the firmware checks the device tree configuration
> >> +during boot. If it finds device tree nodes called csi0 or csi1 then
> >> +it will stop the firmware accessing the block, and it can then
> >> +safely be used via the device tree binding.
> >> +
> >> +Required properties:
> >> +===
> >> +- compatible : must be "brcm,bcm2835-unicam".
> >> +- reg: physical base address and length of the register 
> >> sets for the
> >> +   device.
> >> +- interrupts : should contain the IRQ line for this Unicam instance.
> >> +- clocks : list of clock specifiers, corresponding to entries in
> >> +   clock-names property.
> >> +- clock-names: must contain an "lp" entry, matching entries in the
> >> +   clocks property.
> >> +
> >> +Unicam supports a single port node. It should contain one 'port' child 
> >> node
> >> +with child 'endpoint' node. Please refer to the bindings defined in
> >> +Documentation/devicetree/bindings/media/video-interfaces.txt.
> >> +
> >> +Within the endpoint node the "remote-endpoint" and "data-lanes" properties
> >> +are mandatory.
> >> +Data lane reordering is not supported so the data lanes must be in order,
> >> +starting at 1. The number of data lanes should represent the number of
> >> +usable lanes for the hardware block. That may be limited by either the 
> >> SoC or
> >> +how the platform presents the interface, and the lower value must be used.
> >> +
> >> +Lane reordering is not supported on the clock lane either, so the optional
> >> +property "clock-lane" will implicitly be <0>.
> >> +Similarly lane inversion is not supported, therefore "lane-polarities" 
> >> will
> >> +implicitly be <0 0 0 0 0>.
> >> +Neither of these values will be checked.
> >> +
> >> +Example:
> >> + csi1: csi1@7e801000 {
> >> + compatible = "brcm,bcm2835-unicam";
> >> + reg = <0x7e801000 0x800>,
> >> +   <0x7e802004 0x4>;
> >
> > sorry, i didn't noticed this before. I'm afraid this is using a small range 
> > of the CMI. Are there possible other users of this range? Does it make 
> > sense to handle this by a separate clock driver?
> 
> CMI (Clock Manager Image) consists of a total of 4 registers.
> 0x7e802000 is CMI_CAM0, with only bits 0-5 used for gating and
> inversion of the clock and data lanes (2 data lanes available on
> CAM0).
> 0x7e802004 is CMI_CAM1, with only bits 0-9 used for gating and
> inversion of the clock and data lanes (4 data lanes available on
> CAM1).
> 0x7e802008 is CMI_CAMTEST which I have no documentation or drivers for.
> 0x7e802010 is CMI_USBCTL. Only bit 6 is documented and is a reset. The
> default value is the required value. Nothing touches it that I can
> find.
> 
> The range listed only covers the one register associated with that
> Unicam instance, so no other users. The other two aren't touched.
> Do 16 active register bits solely for camera clock gating really
> warrant a full clock driver?

[PATCH v2 09/17] media: cec-pin.h: convert comments for cec_pin_state into kernel-doc

[Mauro Carvalho Chehab]

This enum is already documented, but it is not using a kernel-doc
format. Convert its format, in order to produce documentation.

Signed-off-by: Mauro Carvalho Chehab 
---
 include/media/cec-pin.h | 81 +++--
 1 file changed, 52 insertions(+), 29 deletions(-)

diff --git a/include/media/cec-pin.h b/include/media/cec-pin.h
index f09cc9579d53..fbe8c256820e 100644
--- a/include/media/cec-pin.h
+++ b/include/media/cec-pin.h
@@ -24,65 +24,88 @@
 #include 
 #include 
 
+/**
+ * enum cec_pin_state - state of CEC pins
+ * @CEC_ST_OFF:
+ * CEC is off
+ * @CEC_ST_IDLE:
+ * CEC is idle, waiting for Rx or Tx
+ * @CEC_ST_TX_WAIT:
+ * Pending Tx, waiting for Signal Free Time to expire
+ * @CEC_ST_TX_WAIT_FOR_HIGH:
+ * Low-drive was detected, wait for bus to go high
+ * @CEC_ST_TX_START_BIT_LOW:
+ * Drive CEC low for the start bit
+ * @CEC_ST_TX_START_BIT_HIGH:
+ * Drive CEC high for the start bit
+ * @CEC_ST_TX_DATA_BIT_0_LOW:
+ * Drive CEC low for the 0 bit
+ * @CEC_ST_TX_DATA_BIT_0_HIGH:
+ * Drive CEC high for the 0 bit
+ * @CEC_ST_TX_DATA_BIT_1_LOW:
+ * Drive CEC low for the 1 bit
+ * @CEC_ST_TX_DATA_BIT_1_HIGH:
+ * Drive CEC high for the 1 bit
+ * @CEC_ST_TX_DATA_BIT_1_HIGH_PRE_SAMPLE:
+ * Wait for start of sample time to check for Ack bit or first
+ * four initiator bits to check for Arbitration Lost.
+ * @CEC_ST_TX_DATA_BIT_1_HIGH_POST_SAMPLE:
+ * Wait for end of bit period after sampling
+ * @CEC_ST_RX_START_BIT_LOW:
+ * Start bit low detected
+ * @CEC_ST_RX_START_BIT_HIGH:
+ * Start bit high detected
+ * @CEC_ST_RX_DATA_SAMPLE:
+ * Wait for bit sample time
+ * @CEC_ST_RX_DATA_POST_SAMPLE:
+ * Wait for earliest end of bit period after sampling
+ * @CEC_ST_RX_DATA_HIGH:
+ * Wait for CEC to go high (i.e. end of bit period
+ * @CEC_ST_RX_ACK_LOW:
+ * Drive CEC low to send 0 Ack bit
+ * @CEC_ST_RX_ACK_LOW_POST:
+ * End of 0 Ack time, wait for earliest end of bit period
+ * @CEC_ST_RX_ACK_HIGH_POST:
+ * Wait for CEC to go high (i.e. end of bit period
+ * @CEC_ST_RX_ACK_FINISH:
+ * Wait for earliest end of bit period and end of message
+ * @CEC_ST_LOW_DRIVE:
+ * Start low drive
+ * @CEC_ST_RX_IRQ:
+ * Monitor pin using interrupts
+ * @CEC_PIN_STATES:
+ * Total number of pin states
+ */
 enum cec_pin_state {
-   /* CEC is off */
CEC_ST_OFF,
-   /* CEC is idle, waiting for Rx or Tx */
CEC_ST_IDLE,
 
/* Tx states */
-
-   /* Pending Tx, waiting for Signal Free Time to expire */
CEC_ST_TX_WAIT,
-   /* Low-drive was detected, wait for bus to go high */
CEC_ST_TX_WAIT_FOR_HIGH,
-   /* Drive CEC low for the start bit */
CEC_ST_TX_START_BIT_LOW,
-   /* Drive CEC high for the start bit */
CEC_ST_TX_START_BIT_HIGH,
-   /* Drive CEC low for the 0 bit */
CEC_ST_TX_DATA_BIT_0_LOW,
-   /* Drive CEC high for the 0 bit */
CEC_ST_TX_DATA_BIT_0_HIGH,
-   /* Drive CEC low for the 1 bit */
CEC_ST_TX_DATA_BIT_1_LOW,
-   /* Drive CEC high for the 1 bit */
CEC_ST_TX_DATA_BIT_1_HIGH,
-   /*
-* Wait for start of sample time to check for Ack bit or first
-* four initiator bits to check for Arbitration Lost.
-*/
CEC_ST_TX_DATA_BIT_1_HIGH_PRE_SAMPLE,
-   /* Wait for end of bit period after sampling */
CEC_ST_TX_DATA_BIT_1_HIGH_POST_SAMPLE,
 
/* Rx states */
-
-   /* Start bit low detected */
CEC_ST_RX_START_BIT_LOW,
-   /* Start bit high detected */
CEC_ST_RX_START_BIT_HIGH,
-   /* Wait for bit sample time */
CEC_ST_RX_DATA_SAMPLE,
-   /* Wait for earliest end of bit period after sampling */
CEC_ST_RX_DATA_POST_SAMPLE,
-   /* Wait for CEC to go high (i.e. end of bit period */
CEC_ST_RX_DATA_HIGH,
-   /* Drive CEC low to send 0 Ack bit */
CEC_ST_RX_ACK_LOW,
-   /* End of 0 Ack time, wait for earliest end of bit period */
CEC_ST_RX_ACK_LOW_POST,
-   /* Wait for CEC to go high (i.e. end of bit period */
CEC_ST_RX_ACK_HIGH_POST,
-   /* Wait for earliest end of bit period and end of message */
CEC_ST_RX_ACK_FINISH,
 
-   /* Start low drive */
CEC_ST_LOW_DRIVE,
-   /* Monitor pin using interrupts */
CEC_ST_RX_IRQ,
 
-   /* Total number of pin states */
CEC_PIN_STATES
 };
 
-- 
2.13.5

[PATCH v2 16/17] media: videobuf2-core: improve kernel-doc markups

[Mauro Carvalho Chehab]

Now that nested structs are supported, change the
documentation to use it. While here, add cross-references
where pertinent and use monotonic fonts where pertinent,
using the right markup tags.

Signed-off-by: Mauro Carvalho Chehab 
---
 include/media/videobuf2-core.h | 59 +-
 1 file changed, 29 insertions(+), 30 deletions(-)

diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h
index ef9b64398c8c..5f4df060affb 100644
--- a/include/media/videobuf2-core.h
+++ b/include/media/videobuf2-core.h
@@ -69,7 +69,7 @@ struct vb2_threadio_data;
  *  argument to other ops in this structure.
  * @put_userptr: inform the allocator that a USERPTR buffer will no longer
  *  be used.
- * @attach_dmabuf: attach a shared struct dma_buf for a hardware operation;
+ * @attach_dmabuf: attach a shared  dma_buf for a hardware operation;
  *used for DMABUF memory types; dev is the alloc device
  *dbuf is the shared dma_buf; returns ERR_PTR() on failure;
  *allocator private per-buffer structure on success;
@@ -153,20 +153,19 @@ struct vb2_mem_ops {
  * @length:size of this plane (NOT the payload) in bytes
  * @min_length:minimum required size of this plane (NOT the payload) 
in bytes.
  * @length is always greater or equal to @min_length.
- * @offset:when memory in the associated struct vb2_buffer is
- * VB2_MEMORY_MMAP, equals the offset from the start of
+ * @m: Union with memtype-specific data
+ * @m.offset:  when memory in the associated struct vb2_buffer is
+ * %VB2_MEMORY_MMAP, equals the offset from the start of
  * the device memory for this plane (or is a "cookie" that
  * should be passed to mmap() called on the video node)
- * @userptr:   when memory is VB2_MEMORY_USERPTR, a userspace pointer
+ * @m.userptr: when memory is %VB2_MEMORY_USERPTR, a userspace pointer
  * pointing to this plane
- * @fd:when memory is VB2_MEMORY_DMABUF, a userspace file
+ * @m.fd:  when memory is %VB2_MEMORY_DMABUF, a userspace file
  * descriptor associated with this plane
- * @m: Union with memtype-specific data (@offset, @userptr or
- * @fd).
  * @data_offset:   offset in the plane to the start of data; usually 0,
  * unless there is a header in front of the data
  * Should contain enough information to be able to cover all the fields
- * of struct v4l2_plane at videodev2.h
+ * of  v4l2_plane at videodev2.h
  */
 struct vb2_plane {
void*mem_priv;
@@ -356,7 +355,7 @@ struct vb2_buffer {
  * driver can return an error if hardware fails, in that
  * case all buffers that have been already given by
  * the @buf_queue callback are to be returned by the driver
- * by calling vb2_buffer_done() with %VB2_BUF_STATE_QUEUED.
+ * by calling vb2_buffer_done() with 
%%VB2_BUF_STATE_QUEUED.
  * If you need a minimum number of buffers before you can
  * start streaming, then set @min_buffers_needed in the
  * vb2_queue structure. If that is non-zero then
@@ -366,7 +365,7 @@ struct vb2_buffer {
  * should stop any DMA transactions or wait until they
  * finish and give back all buffers it got from _queue
  * callback by calling vb2_buffer_done() with either
- * %VB2_BUF_STATE_DONE or %VB2_BUF_STATE_ERROR; may use
+ * %VB2_BUF_STATE_DONE or %%VB2_BUF_STATE_ERROR; may use
  * vb2_wait_for_all_buffers() function
  * @buf_queue: passes buffer vb to the driver; driver may start
  * hardware operation on this buffer; driver should give
@@ -401,13 +400,13 @@ struct vb2_ops {
  * @verify_planes_array: Verify that a given user space structure contains
  * enough planes for the buffer. This is called
  * for each dequeued buffer.
- * @fill_user_buffer:  given a vb2_buffer fill in the userspace structure.
+ * @fill_user_buffer:  given a _buffer fill in the userspace structure.
  * For V4L2 this is a struct v4l2_buffer.
- * @fill_vb2_buffer:   given a userspace structure, fill in the vb2_buffer.
+ * @fill_vb2_buffer:   given a userspace structure, fill in the _buffer.
  * If the userspace structure is invalid, then this op
  * will return an error.
  * @copy_timestamp:copy the timestamp from a userspace structure to
- * the vb2_buffer struct.
+ * the _buffer struct.
  */
 struct vb2_buf_ops {
int (*verify_planes_array)(struct vb2_buffer *vb, const void *pb);
@@ -428,10 

[PATCH v2 06/17] media: v4l2-dv-timings.h: convert comment into kernel-doc markup

[Mauro Carvalho Chehab]

The can_reduce_fps() is already documented, but it is not
using the kernel-doc markup. Convert it, in order to generate
documentation from it.

Signed-off-by: Mauro Carvalho Chehab 
---
 include/media/v4l2-dv-timings.h | 14 --
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/include/media/v4l2-dv-timings.h b/include/media/v4l2-dv-timings.h
index 61a18893e004..c0855887ad87 100644
--- a/include/media/v4l2-dv-timings.h
+++ b/include/media/v4l2-dv-timings.h
@@ -203,13 +203,15 @@ struct v4l2_fract v4l2_calc_aspect_ratio(u8 
hor_landscape, u8 vert_portrait);
  */
 struct v4l2_fract v4l2_dv_timings_aspect_ratio(const struct v4l2_dv_timings 
*t);
 
-/*
- * reduce_fps - check if conditions for reduced fps are true.
- * bt - v4l2 timing structure
+/**
+ * can_reduce_fps - check if conditions for reduced fps are true.
+ * @bt: v4l2 timing structure
+ *
  * For different timings reduced fps is allowed if following conditions
- * are met -
- * For CVT timings: if reduced blanking v2 (vsync == 8) is true.
- * For CEA861 timings: if V4L2_DV_FL_CAN_REDUCE_FPS flag is true.
+ * are met:
+ *
+ *   - For CVT timings: if reduced blanking v2 (vsync == 8) is true.
+ *   - For CEA861 timings: if %V4L2_DV_FL_CAN_REDUCE_FPS flag is true.
  */
 static inline  bool can_reduce_fps(struct v4l2_bt_timings *bt)
 {
-- 
2.13.5

[PATCH v2 07/17] media: v4l2-event.rst: improve events description

[Mauro Carvalho Chehab]

Both v4l2-event.rst and v4l2-event.h have an overview of
events, but there are some inconsistencies there:

- at v4l2-event, the event's ringbuffer is called kevent. Its
  name is, instead, v4l2_kevent;

- Some things are mentioned on both places (with different words),
  others are either on one of the files.

In order to cleanup this mess, put everything at v4l2-event.rst
and improve it to be a little more coherent and to have cross
references.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/media/kapi/v4l2-event.rst | 64 ++---
 include/media/v4l2-event.h  | 34 --
 2 files changed, 52 insertions(+), 46 deletions(-)

diff --git a/Documentation/media/kapi/v4l2-event.rst 
b/Documentation/media/kapi/v4l2-event.rst
index 9938d21ef4d1..7831a503e2aa 100644
--- a/Documentation/media/kapi/v4l2-event.rst
+++ b/Documentation/media/kapi/v4l2-event.rst
@@ -5,27 +5,67 @@ V4L2 events
 The V4L2 events provide a generic way to pass events to user space.
 The driver must use :c:type:`v4l2_fh` to be able to support V4L2 events.
 
-Events are defined by a type and an optional ID. The ID may refer to a V4L2
-object such as a control ID. If unused, then the ID is 0.
+Events are subscribed per-filehandle. An event specification consists of a
+``type`` and is optionally associated with an object identified through the
+``id`` field. If unused, then the ``id`` is 0. So an event is uniquely
+identified by the ``(type, id)`` tuple.
 
-When the user subscribes to an event the driver will allocate a number of
-kevent structs for that event. So every (type, ID) event tuple will have
-its own set of kevent structs. This guarantees that if a driver is generating
-lots of events of one type in a short time, then that will not overwrite
-events of another type.
+The :c:type:`v4l2_fh` struct has a list of subscribed events on its
+``subscribed`` field.
 
-But if you get more events of one type than the number of kevents that were
-reserved, then the oldest event will be dropped and the new one added.
+When the user subscribes to an event, a :c:type:`v4l2_subscribed_event`
+struct is added to :c:type:`v4l2_fh`\ ``.subscribed``, one for every
+subscribed event.
+
+Each :c:type:`v4l2_subscribed_event` struct ends with a
+:c:type:`v4l2_kevent` ringbuffer, with the size given by the caller
+of :c:func:`v4l2_event_subscribe`. Such ringbuffer is used to store any events
+raised by the driver.
+
+So every ``(type, ID)`` event tuple will have its own set of
+:c:type:`v4l2_kevent` ringbuffer. This guarantees that if a driver is
+generating lots of events of one type in a short time, then that will
+not overwrite events of another type.
+
+But if you get more events of one type than the size of the
+:c:type:`v4l2_kevent` ringbuffer, then the oldest event will be dropped
+and the new one added.
+
+The :c:type:`v4l2_kevent` struct links into the ``available``
+list of the :c:type:`v4l2_fh` struct so :ref:`VIDIOC_DQEVENT` will
+know which event to dequeue first.
+
+Finally, if the event subscription is associated with a particular object
+such as a V4L2 control, then that object needs to know about that as well
+so that an event can be raised by that object. So the ``node`` field can
+be used to link the :c:type:`v4l2_subscribed_event` struct into a list of
+such object.
+
+So to summarize:
+
+- struct :c:type:`v4l2_fh` has two lists: one of the ``subscribed`` events,
+  and one of the ``available`` events.
+
+- struct :c:type:`v4l2_subscribed_event` has a ringbuffer of raised
+  (pending) events of that particular type.
+
+- If struct :c:type:`v4l2_subscribed_event` is associated with a specific
+  object, then that object will have an internal list of
+  struct :c:type:`v4l2_subscribed_event` so it knows who subscribed an
+  event to that object.
 
 Furthermore, the internal struct :c:type:`v4l2_subscribed_event` has
 ``merge()`` and ``replace()`` callbacks which drivers can set. These
 callbacks are called when a new event is raised and there is no more room.
+
 The ``replace()`` callback allows you to replace the payload of the old event
 with that of the new event, merging any relevant data from the old payload
 into the new payload that replaces it. It is called when this event type has
-only one kevent struct allocated. The ``merge()`` callback allows you to merge
-the oldest event payload into that of the second-oldest event payload. It is
-called when there are two or more kevent structs allocated.
+only one :c:type:`v4l2_kevent` struct allocated.
+
+The ``merge()`` callback allows you to merge the oldest event payload into
+that of the second-oldest event payload. It is called when there are two
+or more :c:type:`v4l2_kevent` structs allocated.
 
 This way no status information is lost, just the intermediate steps leading
 up to that state.
diff --git a/include/media/v4l2-event.h b/include/media/v4l2-event.h
index 6741910c3a18..4e83529117f7 100644
--- 

[PATCH v2 11/17] media: rc-core.h: minor adjustments at rc_driver_type doc

[Mauro Carvalho Chehab]

The description of this enum doesn't match what it
actually represents. Adjust it.

Signed-off-by: Mauro Carvalho Chehab 
---
 include/media/rc-core.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/include/media/rc-core.h b/include/media/rc-core.h
index 314a1edb6189..a381abe9186e 100644
--- a/include/media/rc-core.h
+++ b/include/media/rc-core.h
@@ -30,9 +30,9 @@ do {  
\
 } while (0)
 
 /**
- * enum rc_driver_type - type of the RC output
+ * enum rc_driver_type - type of the RC driver.
  *
- * @RC_DRIVER_SCANCODE: Driver or hardware generates a scancode
+ * @RC_DRIVER_SCANCODE: Driver or hardware generates a scancode.
  * @RC_DRIVER_IR_RAW:   Driver or hardware generates pulse/space sequences.
  *  It needs a Infra-Red pulse/space decoder
  * @RC_DRIVER_IR_RAW_TX: Device transmitter only,
-- 
2.13.5

[PATCH v2 02/17] media: v4l2-common: get rid of v4l2_routing dead struct

[Mauro Carvalho Chehab]

This struct is not used anymore. Get rid of it and update
the documentation about what should still be converted.

Signed-off-by: Mauro Carvalho Chehab 
---
 include/media/v4l2-common.h | 14 +-
 1 file changed, 5 insertions(+), 9 deletions(-)

diff --git a/include/media/v4l2-common.h b/include/media/v4l2-common.h
index aac8b7b6e691..7dbecbe3009c 100644
--- a/include/media/v4l2-common.h
+++ b/include/media/v4l2-common.h
@@ -224,10 +224,11 @@ void v4l2_spi_subdev_init(struct v4l2_subdev *sd, struct 
spi_device *spi,
 
 /* - */
 
-/* Note: these remaining ioctls/structs should be removed as well, but they are
-   still used in tuner-simple.c (TUNER_SET_CONFIG), cx18/ivtv (RESET) and
-   v4l2-int-device.h (v4l2_routing). To remove these ioctls some more cleanup
-   is needed in those modules. */
+/*
+ * FIXME: these remaining ioctls/structs should be removed as well, but they
+ * are still used in tuner-simple.c (TUNER_SET_CONFIG) and cx18/ivtv (RESET).
+ * To remove these ioctls some more cleanup is needed in those modules.
+ */
 
 /* s_config */
 struct v4l2_priv_tun_config {
@@ -238,11 +239,6 @@ struct v4l2_priv_tun_config {
 
 #define VIDIOC_INT_RESET   _IOW ('d', 102, u32)
 
-struct v4l2_routing {
-   u32 input;
-   u32 output;
-};
-
 /* - */
 
 /* Miscellaneous helper functions */
-- 
2.13.5

[PATCH v2 12/17] media: v4l2-fwnode.h: better describe bus union at fwnode endpoint struct

[Mauro Carvalho Chehab]

Now that kernel-doc handles nested unions, better document the
bus union at struct v4l2_fwnode_endpoint.

Signed-off-by: Mauro Carvalho Chehab 
---
 include/media/v4l2-fwnode.h | 13 -
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/include/media/v4l2-fwnode.h b/include/media/v4l2-fwnode.h
index 7adec9851d9e..5f4716f967d0 100644
--- a/include/media/v4l2-fwnode.h
+++ b/include/media/v4l2-fwnode.h
@@ -79,7 +79,18 @@ struct v4l2_fwnode_bus_mipi_csi1 {
  * struct v4l2_fwnode_endpoint - the endpoint data structure
  * @base: fwnode endpoint of the v4l2_fwnode
  * @bus_type: bus type
- * @bus: bus configuration data structure
+ * @bus: union with bus configuration data structure
+ * @bus.parallel: pointer for  v4l2_fwnode_bus_parallel.
+ *   Used if the bus is parallel.
+ * @bus.mipi_csi1: pointer for  v4l2_fwnode_bus_mipi_csi1.
+ *Used if the bus is Mobile Industry Processor
+ *Interface's Camera Serial Interface version 1
+ *(MIPI CSI1) or Standard Mobile Imaging Architecture's
+ *Compact Camera Port 2 (SMIA CCP2).
+ * @bus.mipi_csi2: pointer for  v4l2_fwnode_bus_mipi_csi2.
+ *Used if the bus is Mobile Industry Processor
+ *Interface's Camera Serial Interface version 2
+ *(MIPI CSI2).
  * @link_frequencies: array of supported link frequencies
  * @nr_of_link_frequencies: number of elements in link_frequenccies array
  */
-- 
2.13.5

[PATCH v2 15/17] media: v4l2-ctrls: document nested members of structs

[Mauro Carvalho Chehab]

There are a few nested members at v4l2-ctrls.h. Now that
kernel-doc supports, document them.

Signed-off-by: Mauro Carvalho Chehab 
---
 include/media/v4l2-ctrls.h | 11 +--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/include/media/v4l2-ctrls.h b/include/media/v4l2-ctrls.h
index dacfe54057f8..ca05f0f49bc5 100644
--- a/include/media/v4l2-ctrls.h
+++ b/include/media/v4l2-ctrls.h
@@ -147,7 +147,7 @@ typedef void (*v4l2_ctrl_notify_fnc)(struct v4l2_ctrl 
*ctrl, void *priv);
  * @type_ops:  The control type ops.
  * @id:The control ID.
  * @name:  The control name.
- * @type:  The control type.
+ * @type:  The control type, as defined by  v4l2_ctrl_type.
  * @minimum:   The control's minimum value.
  * @maximum:   The control's maximum value.
  * @default_value: The control's default value.
@@ -166,8 +166,15 @@ typedef void (*v4l2_ctrl_notify_fnc)(struct v4l2_ctrl 
*ctrl, void *priv);
  * empty strings ("") correspond to non-existing menu items (this
  * is in addition to the menu_skip_mask above). The last entry
  * must be NULL.
+ * Used only if the @type is %V4L2_CTRL_TYPE_MENU.
+ * @qmenu_int: A 64-bit integer array for with integer menu items.
+ * The size of array must be equal to the menu size, e. g.:
+ * :math:`ceil(\frac{maximum - minimum}{step}) + 1`.
+ * Used only if the @type is %V4L2_CTRL_TYPE_INTEGER_MENU.
  * @flags: The control's flags.
- * @cur:   The control's current value.
+ * @cur:   Struct to store data about the current value.
+ * @cur.val:   The control's current value, if the @type is represented via
+ * a u32 integer (see  v4l2_ctrl_type).
  * @val:   The control's new s32 value.
  * @priv:  The control's private pointer. For use by the driver. It is
  * untouched by the control framework. Note that this pointer is
-- 
2.13.5

[PATCH v2 10/17] media: rc-core.rst: add an introduction for RC core

[Mauro Carvalho Chehab]

The RC core does several assumptions, but those aren't documented
anywhere, with could make harder for ones that want to understand
what's there.

So, add an introduction explaining the basic concepts of RC and
how they're related to the RC core implementation.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/media/kapi/rc-core.rst | 77 
 1 file changed, 77 insertions(+)

diff --git a/Documentation/media/kapi/rc-core.rst 
b/Documentation/media/kapi/rc-core.rst
index a45895886257..355c8ea3ad9f 100644
--- a/Documentation/media/kapi/rc-core.rst
+++ b/Documentation/media/kapi/rc-core.rst
@@ -4,6 +4,83 @@ Remote Controller devices
 Remote Controller core
 ~~
 
+The remote controller core implements infrastructure to receive and send
+remote controller keyboard keystrokes and mouse events.
+
+Every time a key is pressed on a remote controller, a scan code is produced.
+Also, on most hardware, keeping a key pressed for more than a few dozens of
+milliseconds produce a repeat key event. That's somewhat similar to what
+a normal keyboard or mouse is handled internally on Linux\ [#f1]_. So, the
+remote controller core is implemented on the top of the linux input/evdev
+interface.
+
+.. [#f1]
+
+   The main difference is that, on keyboard events, the keyboard controller
+   produces one event for a key press and another one for key release. On
+   infrared-based remote controllers, there's no key release event. Instead,
+   an extra code is produced to indicate key repeats.
+
+However, most of the remote controllers use infrared (IR) to transmit signals.
+As there are several protocols used to modulate infrared signals, one
+important part of the core is dedicated to adjust the driver and the core
+system to support the infrared protocol used by the emitter.
+
+The infrared transmission is done by blinking a infrared emitter using a
+carrier. The carrier can be switched on or off by the IR transmitter
+hardware. When the carrier is switched on, it is called *PULSE*.
+When the carrier is switched off, it is called *SPACE*.
+
+In other words, a typical IR transmission can be thinking on a sequence of
+*PULSE* and *SPACE* events, each with a given duration.
+
+The carrier parameters (frequency, duty cycle) and the intervals for
+*PULSE* and *SPACE* events depend on the protocol.
+For example, the NEC protocol uses a carrier of 38kHz, and transmissions
+start with a 9ms *PULSE* and a 4.5ms SPACE. It then transmits 16 bits of
+scan code, being 8 bits for address (usually it is a fixed number for a
+given remote controller), followed by 8 bits of code. A bit "1" is modulated
+with 560µs *PULSE* followed by 1690µs *SPACE* and a bit "0"  is modulated
+with 560µs *PULSE* followed by 560µs *SPACE*.
+
+At receiver, a simple low-pass filter can be used to convert the received
+signal in a sequence of *PULSE/SPACE* events, filtering out the carrier
+frequency. Due to that, the receiver doesn't care about the carrier's
+actual frequency parameters: all it has to do is to measure the amount
+of time it receives *PULSE/SPACE* events.
+So, a simple IR receiver hardware will just provide a sequence of timings
+for those events to the Kernel. The drivers for hardware with such kind of
+receivers are identified by  ``RC_DRIVER_IR_RAW``, as defined by
+:c:type:`rc_driver_type`\ [#f2]_. Other hardware come with a
+microcontroller that decode the *PULSE/SPACE* sequence and return scan
+codes to the Kernel. Such kind of receivers are identified
+by ``RC_DRIVER_SCANCODE``.
+
+.. [#f2]
+
+   The RC core also supports devices that have just IR emitters,
+   without any receivers. Right now, all such devices work only in
+   raw TX mode. Such kind of hardware is identified as
+   ``RC_DRIVER_IR_RAW_TX``.
+
+When the RC core receives events produced by ``RC_DRIVER_IR_RAW`` IR
+receivers, it needs to decode the IR protocol, in order to obtain the
+corresponding scan code. The protocols supported by the RC core are
+defined at enum :c:type:`rc_proto`.
+
+When the RC code receives a scan code (either directly, by a driver
+of the type ``RC_DRIVER_SCANCODE``, or via its IR decoders), it needs
+to convert into a Linux input event code. This is done via a mapping
+table.
+
+The Kernel has support for mapping tables available on most media
+devices. It also supports loading a table in runtime, via some
+sysfs nodes. See the :ref:`RC userspace API `
+for more details.
+
+Remote controller data structures and functions
+^^^
+
 .. kernel-doc:: include/media/rc-core.h
 
 .. kernel-doc:: include/media/rc-map.h
-- 
2.13.5

[PATCH v2 14/17] media: v4l2-async: better describe match union at async match struct

[Mauro Carvalho Chehab]

Now that kernel-doc handles nested unions, better document the
match union at struct v4l2_async_subdev.

Signed-off-by: Mauro Carvalho Chehab 
---
 include/media/v4l2-async.h | 35 ---
 1 file changed, 32 insertions(+), 3 deletions(-)

diff --git a/include/media/v4l2-async.h b/include/media/v4l2-async.h
index e66a3521596f..62c2d572ec23 100644
--- a/include/media/v4l2-async.h
+++ b/include/media/v4l2-async.h
@@ -46,10 +46,39 @@ enum v4l2_async_match_type {
 /**
  * struct v4l2_async_subdev - sub-device descriptor, as known to a bridge
  *
- * @match_type:type of match that will be used
- * @match: union of per-bus type matching data sets
+ * @match_type:
+ * type of match that will be used
+ * @match:
+ * union of per-bus type matching data sets
+ * @match.fwnode:
+ * pointer to  fwnode_handle to be matched.
+ * Used if @match_type is %V4L2_ASYNC_MATCH_FWNODE.
+ * @match.device_name:
+ * string containing the device name to be matched.
+ * Used if @match_type is %V4L2_ASYNC_MATCH_DEVNAME.
+ * @match.i2c:
+ * embedded struct with I2C parameters to be matched.
+ * Both @match.i2c.adapter_id and @match.i2c.address
+ * should be matched.
+ * Used if @match_type is %V4L2_ASYNC_MATCH_I2C.
+ * @match.i2c.adapter_id:
+ * I2C adapter ID to be matched.
+ * Used if @match_type is %V4L2_ASYNC_MATCH_I2C.
+ * @match.i2c.address:
+ * I2C address to be matched.
+ * Used if @match_type is %V4L2_ASYNC_MATCH_I2C.
+ * @match.custom:
+ * Driver-specific match criteria.
+ * Used if @match_type is %V4L2_ASYNC_MATCH_CUSTOM.
+ * @match.custom.match:
+ * Driver-specific match function to be used if
+ * %V4L2_ASYNC_MATCH_CUSTOM.
+ * @match.custom.priv:
+ * Driver-specific private struct with match parameters
+ * to be used if %V4L2_ASYNC_MATCH_CUSTOM.
  * @list:  used to link struct v4l2_async_subdev objects, waiting to be
- * probed, to a notifier->waiting list
+ * probed, to a notifier->waiting list.
+ * Not to be used by drivers.
  */
 struct v4l2_async_subdev {
enum v4l2_async_match_type match_type;
-- 
2.13.5

[PATCH v2 17/17] media: media-entity.h: add kernel-doc markups for nested structs

[Mauro Carvalho Chehab]

Now that nested structs are parsed by kernel-doc, add markups
to them.

Signed-off-by: Mauro Carvalho Chehab 
---
 include/media/media-entity.h | 5 +
 1 file changed, 5 insertions(+)

diff --git a/include/media/media-entity.h b/include/media/media-entity.h
index 222d379960b7..d7a669058b5e 100644
--- a/include/media/media-entity.h
+++ b/include/media/media-entity.h
@@ -88,6 +88,8 @@ struct media_entity_enum {
  * @stack: Graph traversal stack; the stack contains information
  * on the path the media entities to be walked and the
  * links through which they were reached.
+ * @stack.entity:  pointer to  media_entity at the graph.
+ * @stack.link:pointer to  list_head.
  * @ent_enum:  Visited entities
  * @top:   The top of the stack
  */
@@ -247,6 +249,9 @@ enum media_entity_type {
  * @pipe:  Pipeline this entity belongs to.
  * @info:  Union with devnode information.  Kept just for backward
  * compatibility.
+ * @info.dev:  Contains device major and minor info.
+ * @info.dev.major: device node major, if the device is a devnode.
+ * @info.dev.minor: device node minor, if the device is a devnode.
  * @major: Devnode major number (zero if not applicable). Kept just
  * for backward compatibility.
  * @minor: Devnode minor number (zero if not applicable). Kept just
-- 
2.13.5

[PATCH v2 08/17] media: v4l2-ioctl.h: convert debug macros into enum and document

[Mauro Carvalho Chehab]

Currently, there's no way to document #define foo 
with kernel-doc. So, convert it to an enum, and document.

Signed-off-by: Mauro Carvalho Chehab 
---
 include/media/v4l2-ioctl.h | 33 +++--
 1 file changed, 19 insertions(+), 14 deletions(-)

diff --git a/include/media/v4l2-ioctl.h b/include/media/v4l2-ioctl.h
index bd5312118013..136e2cffcf9e 100644
--- a/include/media/v4l2-ioctl.h
+++ b/include/media/v4l2-ioctl.h
@@ -588,20 +588,25 @@ struct v4l2_ioctl_ops {
 };
 
 
-/* v4l debugging and diagnostics */
-
-/* Device debug flags to be used with the video device debug attribute */
-
-/* Just log the ioctl name + error code */
-#define V4L2_DEV_DEBUG_IOCTL   0x01
-/* Log the ioctl name arguments + error code */
-#define V4L2_DEV_DEBUG_IOCTL_ARG   0x02
-/* Log the file operations open, release, mmap and get_unmapped_area */
-#define V4L2_DEV_DEBUG_FOP 0x04
-/* Log the read and write file operations and the VIDIOC_(D)QBUF ioctls */
-#define V4L2_DEV_DEBUG_STREAMING   0x08
-/* Log poll() */
-#define V4L2_DEV_DEBUG_POLL0x10
+/**
+ * enum v4l2_debug_flags - Device debug flags to be used with the video
+ * device debug attribute
+ *
+ * @V4L2_DEV_DEBUG_IOCTL:  Just log the ioctl name + error code.
+ * @V4L2_DEV_DEBUG_IOCTL_ARG:  Log the ioctl name arguments + error code.
+ * @V4L2_DEV_DEBUG_FOP:Log the file operations and open, 
release,
+ * mmap and get_unmapped_area syscalls.
+ * @V4L2_DEV_DEBUG_STREAMING:  Log the read and write syscalls and
+ * :c:ref:`VIDIOC_[Q|DQ]BUFF ` ioctls.
+ * @V4L2_DEV_DEBUG_POLL:   Log poll syscalls.
+ */
+enum v4l2_debug_flags {
+   V4L2_DEV_DEBUG_IOCTL= 0x01,
+   V4L2_DEV_DEBUG_IOCTL_ARG= 0x02,
+   V4L2_DEV_DEBUG_FOP  = 0x04,
+   V4L2_DEV_DEBUG_STREAMING= 0x08,
+   V4L2_DEV_DEBUG_POLL = 0x10,
+};
 
 /*  Video standard functions  */
 
-- 
2.13.5

[PATCH v2 04/17] media: v4l2-common.h: document ancillary functions

[Mauro Carvalho Chehab]

There are several ancillary functions that aren't documented.

Document them.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/v4l2-core/v4l2-common.c |  14 -
 include/media/v4l2-common.h   | 104 ++
 2 files changed, 94 insertions(+), 24 deletions(-)

diff --git a/drivers/media/v4l2-core/v4l2-common.c 
b/drivers/media/v4l2-core/v4l2-common.c
index fb9a2a3c1072..ac404d5083e0 100644
--- a/drivers/media/v4l2-core/v4l2-common.c
+++ b/drivers/media/v4l2-core/v4l2-common.c
@@ -320,20 +320,6 @@ static unsigned int clamp_align(unsigned int x, unsigned 
int min,
return x;
 }
 
-/* Bound an image to have a width between wmin and wmax, and height between
- * hmin and hmax, inclusive.  Additionally, the width will be a multiple of
- * 2^walign, the height will be a multiple of 2^halign, and the overall size
- * (width*height) will be a multiple of 2^salign.  The image may be shrunk
- * or enlarged to fit the alignment constraints.
- *
- * The width or height maximum must not be smaller than the corresponding
- * minimum.  The alignments must not be so high there are no possible image
- * sizes within the allowed bounds.  wmin and hmin must be at least 1
- * (don't use 0).  If you don't care about a certain alignment, specify 0,
- * as 2^0 is 1 and one byte alignment is equivalent to no alignment.  If
- * you only want to adjust downward, specify a maximum that's the same as
- * the initial value.
- */
 void v4l_bound_align_image(u32 *w, unsigned int wmin, unsigned int wmax,
   unsigned int walign,
   u32 *h, unsigned int hmin, unsigned int hmax,
diff --git a/include/media/v4l2-common.h b/include/media/v4l2-common.h
index 7ae7840df068..d3f5f907d566 100644
--- a/include/media/v4l2-common.h
+++ b/include/media/v4l2-common.h
@@ -174,17 +174,43 @@ void v4l2_i2c_subdev_init(struct v4l2_subdev *sd, struct 
i2c_client *client,
  */
 unsigned short v4l2_i2c_subdev_addr(struct v4l2_subdev *sd);
 
+/**
+ * enum v4l2_i2c_tuner_type - specifies the range of tuner address that
+ * should be used when seeking for I2C devices.
+ *
+ * @ADDRS_RADIO:   Radio tuner addresses.
+ * Represent the following I2C addresses:
+ * 0x10 (if compiled with tea5761 support)
+ * and 0x60.
+ * @ADDRS_DEMOD:   Demod tuner addresses.
+ * Represent the following I2C addresses:
+ * 0x42, 0x43, 0x4a and 0x4b.
+ * @ADDRS_TV:  TV tuner addresses.
+ * Represent the following I2C addresses:
+ * 0x42, 0x43, 0x4a, 0x4b, 0x60, 0x61, 0x62,
+ * 0x63 and 0x64.
+ * @ADDRS_TV_WITH_DEMOD:   TV tuner addresses if demod is present, this
+ * excludes addresses used by the demodulator
+ * from the list of candidates.
+ * Represent the following I2C addresses:
+ * 0x60, 0x61, 0x62, 0x63 and 0x64.
+ *
+ * NOTE: All I2C addresses above use the 7-bit notation.
+ */
 enum v4l2_i2c_tuner_type {
-   ADDRS_RADIO,/* Radio tuner addresses */
-   ADDRS_DEMOD,/* Demod tuner addresses */
-   ADDRS_TV,   /* TV tuner addresses */
-   /* TV tuner addresses if demod is present, this excludes
-  addresses used by the demodulator from the list of
-  candidates. */
+   ADDRS_RADIO,
+   ADDRS_DEMOD,
+   ADDRS_TV,
ADDRS_TV_WITH_DEMOD,
 };
-/* Return a list of I2C tuner addresses to probe. Use only if the tuner
-   addresses are unknown. */
+/**
+ * v4l2_i2c_tuner_addrs - Return a list of I2C tuner addresses to probe.
+ *
+ * @type: type of the tuner type to seek, as defined by
+ *v4l2_i2c_tuner_type.
+ *
+ * NOTE: Use only if the tuner addresses are unknown.
+ */
 const unsigned short *v4l2_i2c_tuner_addrs(enum v4l2_i2c_tuner_type type);
 
 /* - */
@@ -228,6 +254,9 @@ void v4l2_spi_subdev_init(struct v4l2_subdev *sd, struct 
spi_device *spi,
  * FIXME: these remaining ioctls/structs should be removed as well, but they
  * are still used in tuner-simple.c (TUNER_SET_CONFIG) and cx18/ivtv (RESET).
  * To remove these ioctls some more cleanup is needed in those modules.
+ *
+ * It doesn't make much sense on documenting them, as what we really want is
+ * to get rid of them.
  */
 
 /* s_config */
@@ -243,17 +272,72 @@ struct v4l2_priv_tun_config {
 
 /* Miscellaneous helper functions */
 
-void v4l_bound_align_image(unsigned int *w, unsigned int wmin,
+/**
+ * v4l_bound_align_image - adjust video dimensions according to
+ * a given criteria.
+ *
+ * @width: pointer to width that will be adjusted if needed.
+ * @wmin:  minimum width.
+ 

[PATCH v2 05/17] media: v4l2-device.h: document ancillary macros

[Mauro Carvalho Chehab]

There are several widely macros that aren't documented using kernel-docs
markups.

Add it.

Signed-off-by: Mauro Carvalho Chehab 
---
 include/media/v4l2-device.h | 238 +---
 1 file changed, 204 insertions(+), 34 deletions(-)

diff --git a/include/media/v4l2-device.h b/include/media/v4l2-device.h
index 8ffa94009d1a..d6d1c4f7d42c 100644
--- a/include/media/v4l2-device.h
+++ b/include/media/v4l2-device.h
@@ -56,7 +56,6 @@ struct v4l2_ctrl_handler;
  *#) @dev->driver_data points to this struct.
  *#) @dev might be %NULL if there is no parent device
  */
-
 struct v4l2_device {
struct device *dev;
 #if defined(CONFIG_MEDIA_CONTROLLER)
@@ -166,7 +165,7 @@ void v4l2_device_unregister(struct v4l2_device *v4l2_dev);
  * v4l2_device_register_subdev - Registers a subdev with a v4l2 device.
  *
  * @v4l2_dev: pointer to struct _device
- * @sd: pointer to struct _subdev
+ * @sd: pointer to  v4l2_subdev
  *
  * While registered, the subdev module is marked as in-use.
  *
@@ -179,7 +178,7 @@ int __must_check v4l2_device_register_subdev(struct 
v4l2_device *v4l2_dev,
 /**
  * v4l2_device_unregister_subdev - Unregisters a subdev with a v4l2 device.
  *
- * @sd: pointer to struct _subdev
+ * @sd: pointer to  v4l2_subdev
  *
  * .. note ::
  *
@@ -201,7 +200,7 @@ v4l2_device_register_subdev_nodes(struct v4l2_device 
*v4l2_dev);
 /**
  * v4l2_subdev_notify - Sends a notification to v4l2_device.
  *
- * @sd: pointer to struct _subdev
+ * @sd: pointer to  v4l2_subdev
  * @notification: type of notification. Please notice that the notification
  * type is driver-specific.
  * @arg: arguments for the notification. Those are specific to each
@@ -214,13 +213,43 @@ static inline void v4l2_subdev_notify(struct v4l2_subdev 
*sd,
sd->v4l2_dev->notify(sd, notification, arg);
 }
 
-/* Iterate over all subdevs. */
+/* Ancillary macros to iterate over all subdevs. */
+
+/**
+ * v4l2_device_for_each_subdev - Ancillary macro that interates over all
+ * sub-devices
+ *
+ * @sd: pointer that will be filled by the macro with all
+ *  v4l2_subdev sub-devices associated with @v4l2_dev.
+ * @v4l2_dev: pointer to  v4l2_device
+ *
+ * Sometimes, a driver may need to broadcast a command to all subdevices.
+ * This ancillary macro allows interacting to all sub-devices associated
+ * to a device.
+ */
 #define v4l2_device_for_each_subdev(sd, v4l2_dev)  \
list_for_each_entry(sd, &(v4l2_dev)->subdevs, list)
 
-/* Call the specified callback for all subdevs matching the condition.
-   Ignore any errors. Note that you cannot add or delete a subdev
-   while walking the subdevs list. */
+/**
+ * __v4l2_device_call_subdevs_p - Calls the specified callback for
+ * all subdevs matching the condition.
+ *
+ * @v4l2_dev: pointer to  v4l2_device
+ * @sd: pointer that will be filled by the macro with all
+ *  v4l2_subdev sub-devices associated with @v4l2_dev.
+ * @cond: condition to be match
+ * @o: name of the element at  v4l2_subdev_ops that contains @f.
+ * Each element there groups a set of callbacks functions.
+ * @f: callback function that will be called if @cond matches.
+ * The callback functions are defined in groups, according to
+ * each element at  v4l2_subdev_ops.
+ * @args...: arguments for @f.
+ *
+ * Ignore any errors.
+ *
+ * Note: subdevs cannot be added or deleted while walking at
+ * the subdevs list.
+ */
 #define __v4l2_device_call_subdevs_p(v4l2_dev, sd, cond, o, f, args...)
\
do {\
list_for_each_entry((sd), &(v4l2_dev)->subdevs, list)   \
@@ -228,6 +257,24 @@ static inline void v4l2_subdev_notify(struct v4l2_subdev 
*sd,
(sd)->ops->o->f((sd) , ##args); \
} while (0)
 
+/**
+ * __v4l2_device_call_subdevs - Calls the specified callback for
+ * all subdevs matching the condition.
+ *
+ * @v4l2_dev: pointer to  v4l2_device
+ * @cond: condition to be match
+ * @o: name of the element at  v4l2_subdev_ops that contains @f.
+ * Each element there groups a set of callbacks functions.
+ * @f: callback function that will be called if @cond matches.
+ * The callback functions are defined in groups, according to
+ * each element at  v4l2_subdev_ops.
+ * @args...: arguments for @f.
+ *
+ * Ignore any errors.
+ *
+ * Note: subdevs cannot be added or deleted while walking at
+ * the subdevs list.
+ */
 #define __v4l2_device_call_subdevs(v4l2_dev, cond, o, f, args...)  \
do {\
struct v4l2_subdev *__sd;   \
@@ -236,10 +283,29 @@ static inline void v4l2_subdev_notify(struct v4l2_subdev 
*sd,
f , ##args);\
} while (0)
 
-/* Call the specified callback for all subdevs 

[PATCH v2 01/17] media: tuner-types: add kernel-doc markups for struct tunertype

[Mauro Carvalho Chehab]

This struct is lacking documentation. Add it.

Signed-off-by: Mauro Carvalho Chehab 
---
 include/media/tuner-types.h | 15 +++
 1 file changed, 15 insertions(+)

diff --git a/include/media/tuner-types.h b/include/media/tuner-types.h
index aed539068d2d..55bc14093c0f 100644
--- a/include/media/tuner-types.h
+++ b/include/media/tuner-types.h
@@ -170,6 +170,21 @@ struct tuner_params {
struct tuner_range *ranges;
 };
 
+/**
+ * struct tunertype - describes the known tuners.
+ *
+ * @name:  string with the tuner's name.
+ * @count: size of  tuner_params array.
+ * @params:pointer to  tuner_params array.
+ *
+ * @min:   minimal tuner frequency, in 62.5 kHz step.
+ * should be multiplied to 16 to convert to MHz.
+ * @max:   minimal tuner frequency, in 62.5 kHz step.
+ * Should be multiplied to 16 to convert to MHz.
+ * @stepsize:  frequency step, in Hz.
+ * @initdata:  optional byte sequence to initialize the tuner.
+ * @sleepdata: optional byte sequence to power down the tuner.
+ */
 struct tunertype {
char *name;
unsigned int count;
-- 
2.13.5

[PATCH v2 03/17] media: v4l2-common: get rid of struct v4l2_discrete_probe

[Mauro Carvalho Chehab]

This struct is there just two store two arguments of
v4l2_find_nearest_format(). The other two arguments are passed
as parameter.

IMHO, there isn't much sense on doing that, and that will just
add one more struct to document ;)

So, let's get rid of the struct, passing the parameters directly.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/platform/vivid/vivid-vid-cap.c |  9 +++--
 drivers/media/v4l2-core/v4l2-common.c| 13 +++--
 include/media/v4l2-common.h  | 12 
 3 files changed, 14 insertions(+), 20 deletions(-)

diff --git a/drivers/media/platform/vivid/vivid-vid-cap.c 
b/drivers/media/platform/vivid/vivid-vid-cap.c
index 01419455e545..0fbbcde19f0d 100644
--- a/drivers/media/platform/vivid/vivid-vid-cap.c
+++ b/drivers/media/platform/vivid/vivid-vid-cap.c
@@ -93,11 +93,6 @@ static const struct v4l2_fract 
webcam_intervals[VIVID_WEBCAM_IVALS] = {
{  1, 60 },
 };
 
-static const struct v4l2_discrete_probe webcam_probe = {
-   webcam_sizes,
-   VIVID_WEBCAM_SIZES
-};
-
 static int vid_cap_queue_setup(struct vb2_queue *vq,
   unsigned *nbuffers, unsigned *nplanes,
   unsigned sizes[], struct device *alloc_devs[])
@@ -578,7 +573,9 @@ int vivid_try_fmt_vid_cap(struct file *file, void *priv,
mp->field = vivid_field_cap(dev, mp->field);
if (vivid_is_webcam(dev)) {
const struct v4l2_frmsize_discrete *sz =
-   v4l2_find_nearest_format(_probe, mp->width, 
mp->height);
+   v4l2_find_nearest_format(webcam_sizes,
+VIVID_WEBCAM_SIZES,
+mp->width, mp->height);
 
w = sz->width;
h = sz->height;
diff --git a/drivers/media/v4l2-core/v4l2-common.c 
b/drivers/media/v4l2-core/v4l2-common.c
index a5ea1f517291..fb9a2a3c1072 100644
--- a/drivers/media/v4l2-core/v4l2-common.c
+++ b/drivers/media/v4l2-core/v4l2-common.c
@@ -371,18 +371,19 @@ void v4l_bound_align_image(u32 *w, unsigned int wmin, 
unsigned int wmax,
 }
 EXPORT_SYMBOL_GPL(v4l_bound_align_image);
 
-const struct v4l2_frmsize_discrete *v4l2_find_nearest_format(
-   const struct v4l2_discrete_probe *probe,
-   s32 width, s32 height)
+const struct v4l2_frmsize_discrete
+*v4l2_find_nearest_format(const struct v4l2_frmsize_discrete *sizes,
+ const size_t num_sizes,
+ s32 width, s32 height)
 {
int i;
u32 error, min_error = UINT_MAX;
const struct v4l2_frmsize_discrete *size, *best = NULL;
 
-   if (!probe)
-   return best;
+   if (!sizes)
+   return NULL;
 
-   for (i = 0, size = probe->sizes; i < probe->num_sizes; i++, size++) {
+   for (i = 0, size = sizes; i < num_sizes; i++, size++) {
error = abs(size->width - width) + abs(size->height - height);
if (error < min_error) {
min_error = error;
diff --git a/include/media/v4l2-common.h b/include/media/v4l2-common.h
index 7dbecbe3009c..7ae7840df068 100644
--- a/include/media/v4l2-common.h
+++ b/include/media/v4l2-common.h
@@ -249,14 +249,10 @@ void v4l_bound_align_image(unsigned int *w, unsigned int 
wmin,
   unsigned int hmax, unsigned int halign,
   unsigned int salign);
 
-struct v4l2_discrete_probe {
-   const struct v4l2_frmsize_discrete  *sizes;
-   int num_sizes;
-};
-
-const struct v4l2_frmsize_discrete *v4l2_find_nearest_format(
-   const struct v4l2_discrete_probe *probe,
-   s32 width, s32 height);
+const struct v4l2_frmsize_discrete
+*v4l2_find_nearest_format(const struct v4l2_frmsize_discrete *sizes,
+ const size_t num_sizes,
+ s32 width, s32 height);
 
 void v4l2_get_timestamp(struct timeval *tv);
 
-- 
2.13.5

[PATCH v2 00/17] V4L cleanups and documentation improvements

[Mauro Carvalho Chehab]

This patch series is meant to improve V4L documentation. It touches
some files at the tree doing some cleanup, in order to simplify
the source code.

Mauro Carvalho Chehab (17):
  media: tuner-types: add kernel-doc markups for struct tunertype
  media: v4l2-common: get rid of v4l2_routing dead struct
  media: v4l2-common: get rid of struct v4l2_discrete_probe
  media: v4l2-common.h: document ancillary functions
  media: v4l2-device.h: document ancillary macros
  media: v4l2-dv-timings.h: convert comment into kernel-doc markup
  media: v4l2-event.rst: improve events description
  media: v4l2-ioctl.h: convert debug macros into enum and document
  media: cec-pin.h: convert comments for cec_pin_state into kernel-doc
  media: rc-core.rst: add an introduction for RC core
  media: rc-core.h: minor adjustments at rc_driver_type doc
  media: v4l2-fwnode.h: better describe bus union at fwnode endpoint
struct
  media: v4l2-async: simplify v4l2_async_subdev structure
  media: v4l2-async: better describe match union at async match struct
  media: v4l2-ctrls: document nested members of structs
  media: videobuf2-core: improve kernel-doc markups
  media: media-entity.h: add kernel-doc markups for nested structs

 Documentation/media/kapi/rc-core.rst   |  77 
 Documentation/media/kapi/v4l2-event.rst|  64 +--
 drivers/media/platform/am437x/am437x-vpfe.c|   6 +-
 drivers/media/platform/atmel/atmel-isc.c   |   2 +-
 drivers/media/platform/atmel/atmel-isi.c   |   2 +-
 drivers/media/platform/davinci/vpif_capture.c  |   4 +-
 drivers/media/platform/exynos4-is/media-dev.c  |   4 +-
 drivers/media/platform/omap3isp/isp.c  |   4 +-
 drivers/media/platform/pxa_camera.c|   2 +-
 drivers/media/platform/qcom/camss-8x16/camss.c |   2 +-
 drivers/media/platform/rcar-vin/rcar-core.c|   8 +-
 drivers/media/platform/rcar_drif.c |   4 +-
 drivers/media/platform/soc_camera/soc_camera.c |   2 +-
 drivers/media/platform/stm32/stm32-dcmi.c  |   2 +-
 drivers/media/platform/ti-vpe/cal.c|   2 +-
 drivers/media/platform/vivid/vivid-vid-cap.c   |   9 +-
 drivers/media/platform/xilinx/xilinx-vipp.c|   2 +-
 drivers/media/v4l2-core/v4l2-async.c   |   4 +-
 drivers/media/v4l2-core/v4l2-common.c  |  27 +--
 drivers/staging/media/imx/imx-media-dev.c  |   8 +-
 include/media/cec-pin.h|  81 ++---
 include/media/media-entity.h   |   5 +
 include/media/rc-core.h|   4 +-
 include/media/tuner-types.h|  15 ++
 include/media/v4l2-async.h |  43 -
 include/media/v4l2-common.h| 130 +++---
 include/media/v4l2-ctrls.h |  11 +-
 include/media/v4l2-device.h| 238 +
 include/media/v4l2-dv-timings.h|  14 +-
 include/media/v4l2-event.h |  34 
 include/media/v4l2-fwnode.h|  13 +-
 include/media/v4l2-ioctl.h |  33 ++--
 include/media/videobuf2-core.h |  59 +++---
 33 files changed, 660 insertions(+), 255 deletions(-)

-- 
2.13.5

[PATCH v2 13/37] media: dvbdev: convert DVB device types into an enum

[Mauro Carvalho Chehab]

Enums can be documented via kernel-doc. So, convert the
DVB_DEVICE_* macros to an enum.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-core/dvbdev.c | 34 +++
 drivers/media/dvb-core/dvbdev.h | 51 -
 2 files changed, 64 insertions(+), 21 deletions(-)

diff --git a/drivers/media/dvb-core/dvbdev.c b/drivers/media/dvb-core/dvbdev.c
index 41aad0f99d73..7b4cdcfbb02c 100644
--- a/drivers/media/dvb-core/dvbdev.c
+++ b/drivers/media/dvb-core/dvbdev.c
@@ -51,8 +51,15 @@ static LIST_HEAD(dvb_adapter_list);
 static DEFINE_MUTEX(dvbdev_register_lock);
 
 static const char * const dnames[] = {
-   "video", "audio", "sec", "frontend", "demux", "dvr", "ca",
-   "net", "osd"
+   [DVB_DEVICE_VIDEO] ="video",
+   [DVB_DEVICE_AUDIO] ="audio",
+   [DVB_DEVICE_SEC] =  "sec",
+   [DVB_DEVICE_FRONTEND] = "frontend",
+   [DVB_DEVICE_DEMUX] ="demux",
+   [DVB_DEVICE_DVR] =  "dvr",
+   [DVB_DEVICE_CA] =   "ca",
+   [DVB_DEVICE_NET] =  "net",
+   [DVB_DEVICE_OSD] =  "osd"
 };
 
 #ifdef CONFIG_DVB_DYNAMIC_MINORS
@@ -60,7 +67,24 @@ static const char * const dnames[] = {
 #define DVB_MAX_IDSMAX_DVB_MINORS
 #else
 #define DVB_MAX_IDS4
-#define nums2minor(num, type, id)  ((num << 6) | (id << 4) | type)
+
+static int nums2minor(int num, enum dvb_device_type type, int id)
+{
+   int n = (num << 6) | (id << 4);
+
+   switch (type) {
+   case DVB_DEVICE_VIDEO:  return n;
+   case DVB_DEVICE_AUDIO:  return n | 1;
+   case DVB_DEVICE_SEC:return n | 2;
+   case DVB_DEVICE_FRONTEND:   return n | 3;
+   case DVB_DEVICE_DEMUX:  return n | 4;
+   case DVB_DEVICE_DVR:return n | 5;
+   case DVB_DEVICE_CA: return n | 6;
+   case DVB_DEVICE_NET:return n | 7;
+   case DVB_DEVICE_OSD:return n | 8;
+   }
+}
+
 #define MAX_DVB_MINORS (DVB_MAX_ADAPTERS*64)
 #endif
 
@@ -426,8 +450,8 @@ static int dvb_register_media_device(struct dvb_device 
*dvbdev,
 }
 
 int dvb_register_device(struct dvb_adapter *adap, struct dvb_device **pdvbdev,
-   const struct dvb_device *template, void *priv, int type,
-   int demux_sink_pads)
+   const struct dvb_device *template, void *priv,
+   enum dvb_device_type type, int demux_sink_pads)
 {
struct dvb_device *dvbdev;
struct file_operations *dvbdevfops;
diff --git a/drivers/media/dvb-core/dvbdev.h b/drivers/media/dvb-core/dvbdev.h
index 49189392cf3b..53058da83873 100644
--- a/drivers/media/dvb-core/dvbdev.h
+++ b/drivers/media/dvb-core/dvbdev.h
@@ -35,15 +35,37 @@
 
 #define DVB_UNSET (-1)
 
-#define DVB_DEVICE_VIDEO  0
-#define DVB_DEVICE_AUDIO  1
-#define DVB_DEVICE_SEC2
-#define DVB_DEVICE_FRONTEND   3
-#define DVB_DEVICE_DEMUX  4
-#define DVB_DEVICE_DVR5
-#define DVB_DEVICE_CA 6
-#define DVB_DEVICE_NET7
-#define DVB_DEVICE_OSD8
+/* List of DVB device types */
+
+/**
+ * enum dvb_device_type - type of the Digital TV device
+ *
+ * @DVB_DEVICE_SEC:Digital TV standalone Common Interface (CI)
+ * @DVB_DEVICE_FRONTEND:   Digital TV frontend.
+ * @DVB_DEVICE_DEMUX:  Digital TV demux.
+ * @DVB_DEVICE_DVR:Digital TV digital video record (DVR).
+ * @DVB_DEVICE_CA: Digital TV Conditional Access (CA).
+ * @DVB_DEVICE_NET:Digital TV network.
+ *
+ * @DVB_DEVICE_VIDEO:  Digital TV video decoder.
+ * Deprecated. Used only on av7110-av.
+ * @DVB_DEVICE_AUDIO:  Digital TV audio decoder.
+ * Deprecated. Used only on av7110-av.
+ * @DVB_DEVICE_OSD:Digital TV On Screen Display (OSD).
+ * Deprecated. Used only on av7110.
+ */
+enum dvb_device_type {
+   DVB_DEVICE_SEC,
+   DVB_DEVICE_FRONTEND,
+   DVB_DEVICE_DEMUX,
+   DVB_DEVICE_DVR,
+   DVB_DEVICE_CA,
+   DVB_DEVICE_NET,
+
+   DVB_DEVICE_VIDEO,
+   DVB_DEVICE_AUDIO,
+   DVB_DEVICE_OSD,
+};
 
 #define DVB_DEFINE_MOD_OPT_ADAPTER_NR(adapter_nr) \
static short adapter_nr[] = \
@@ -104,8 +126,7 @@ struct dvb_adapter {
  * @list_head: List head with all DVB devices
  * @fops:  pointer to struct file_operations
  * @adapter:   pointer to the adapter that holds this device node
- * @type:  type of the device: DVB_DEVICE_SEC, DVB_DEVICE_FRONTEND,
- * DVB_DEVICE_DEMUX, DVB_DEVICE_DVR, DVB_DEVICE_CA, DVB_DEVICE_NET
+ * @type:  type of the device, as defined by  dvb_device_type.
  * @minor: devnode minor number. Major number is always DVB_MAJOR.
  * @id:device ID number, inside the 

[PATCH v2 22/37] media: dvb_demux: mark a boolean field as such

[Mauro Carvalho Chehab]

The struct dvb_demux_filter.doneq is a boolean.

Mark it as such, as it helps to understand what it does.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-core/dvb_demux.c | 4 ++--
 drivers/media/dvb-core/dvb_demux.h | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/drivers/media/dvb-core/dvb_demux.c 
b/drivers/media/dvb-core/dvb_demux.c
index 6628f80d184f..68e93362c081 100644
--- a/drivers/media/dvb-core/dvb_demux.c
+++ b/drivers/media/dvb-core/dvb_demux.c
@@ -898,14 +898,14 @@ static void prepare_secfilters(struct dvb_demux_feed 
*dvbdmxfeed)
return;
do {
sf = >filter;
-   doneq = 0;
+   doneq = false;
for (i = 0; i < DVB_DEMUX_MASK_MAX; i++) {
mode = sf->filter_mode[i];
mask = sf->filter_mask[i];
f->maskandmode[i] = mask & mode;
doneq |= f->maskandnotmode[i] = mask & ~mode;
}
-   f->doneq = doneq ? 1 : 0;
+   f->doneq = doneq ? true : false;
} while ((f = f->next));
 }
 
diff --git a/drivers/media/dvb-core/dvb_demux.h 
b/drivers/media/dvb-core/dvb_demux.h
index 045f7fd1a8b1..700887938145 100644
--- a/drivers/media/dvb-core/dvb_demux.h
+++ b/drivers/media/dvb-core/dvb_demux.h
@@ -64,7 +64,7 @@ struct dvb_demux_filter {
struct dmx_section_filter filter;
u8 maskandmode[DMX_MAX_FILTER_SIZE];
u8 maskandnotmode[DMX_MAX_FILTER_SIZE];
-   int doneq;
+   bool doneq;
 
struct dvb_demux_filter *next;
struct dvb_demux_feed *feed;
-- 
2.13.5

[PATCH v2 23/37] media: dvb_demux: dvb_demux_feed.pusi_seen is boolean

[Mauro Carvalho Chehab]

Instead of using an integer to represent it, use boolean,
as this better describes what this field really means.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-core/dvb_demux.c| 12 ++--
 drivers/media/dvb-core/dvb_demux.h|  2 +-
 drivers/media/pci/ttpci/av7110.c  |  2 +-
 drivers/media/pci/ttpci/budget-core.c |  2 +-
 4 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/drivers/media/dvb-core/dvb_demux.c 
b/drivers/media/dvb-core/dvb_demux.c
index 68e93362c081..b9360cbc3519 100644
--- a/drivers/media/dvb-core/dvb_demux.c
+++ b/drivers/media/dvb-core/dvb_demux.c
@@ -223,10 +223,10 @@ static void dvb_dmx_swfilter_section_new(struct 
dvb_demux_feed *feed)
  *  when the second packet arrives.
  *
  * Fix:
- * when demux is started, let feed->pusi_seen = 0 to
+ * when demux is started, let feed->pusi_seen = false to
  * prevent initial feeding of garbage from the end of
  * previous section. When you for the first time see PUSI=1
- * then set feed->pusi_seen = 1
+ * then set feed->pusi_seen = true
  */
 static int dvb_dmx_swfilter_section_copy_dump(struct dvb_demux_feed *feed,
  const u8 *buf, u8 len)
@@ -318,10 +318,10 @@ static int dvb_dmx_swfilter_section_packet(struct 
dvb_demux_feed *feed,
 */
 #endif
/*
-* Discontinuity detected. Reset pusi_seen = 0 to
+* Discontinuity detected. Reset pusi_seen to
 * stop feeding of suspicious data until next PUSI=1 arrives
 */
-   feed->pusi_seen = 0;
+   feed->pusi_seen = false;
dvb_dmx_swfilter_section_new(feed);
}
 
@@ -335,8 +335,8 @@ static int dvb_dmx_swfilter_section_packet(struct 
dvb_demux_feed *feed,
 
dvb_dmx_swfilter_section_copy_dump(feed, before,
   before_len);
-   /* before start of new section, set pusi_seen = 1 */
-   feed->pusi_seen = 1;
+   /* before start of new section, set pusi_seen */
+   feed->pusi_seen = true;
dvb_dmx_swfilter_section_new(feed);
dvb_dmx_swfilter_section_copy_dump(feed, after,
   after_len);
diff --git a/drivers/media/dvb-core/dvb_demux.h 
b/drivers/media/dvb-core/dvb_demux.h
index 700887938145..9db3c2b7c64e 100644
--- a/drivers/media/dvb-core/dvb_demux.h
+++ b/drivers/media/dvb-core/dvb_demux.h
@@ -101,7 +101,7 @@ struct dvb_demux_feed {
enum dmx_ts_pes pes_type;
 
int cc;
-   int pusi_seen;  /* prevents feeding of garbage from previous 
section */
+   bool pusi_seen; /* prevents feeding of garbage from previous 
section */
 
u16 peslen;
 
diff --git a/drivers/media/pci/ttpci/av7110.c b/drivers/media/pci/ttpci/av7110.c
index f46947d8adf8..f89fb23f6c57 100644
--- a/drivers/media/pci/ttpci/av7110.c
+++ b/drivers/media/pci/ttpci/av7110.c
@@ -1224,7 +1224,7 @@ static int budget_start_feed(struct dvb_demux_feed *feed)
dprintk(2, "av7110: %p\n", budget);
 
spin_lock(>feedlock1);
-   feed->pusi_seen = 0; /* have a clean section start */
+   feed->pusi_seen = false; /* have a clean section start */
status = start_ts_capture(budget);
spin_unlock(>feedlock1);
return status;
diff --git a/drivers/media/pci/ttpci/budget-core.c 
b/drivers/media/pci/ttpci/budget-core.c
index 97499b2af714..b3dc45b91101 100644
--- a/drivers/media/pci/ttpci/budget-core.c
+++ b/drivers/media/pci/ttpci/budget-core.c
@@ -330,7 +330,7 @@ static int budget_start_feed(struct dvb_demux_feed *feed)
return -EINVAL;
 
spin_lock(>feedlock);
-   feed->pusi_seen = 0; /* have a clean section start */
+   feed->pusi_seen = false; /* have a clean section start */
if (budget->feeding++ == 0)
status = start_ts_capture(budget);
spin_unlock(>feedlock);
-- 
2.13.5

[PATCH v2 27/37] media: dvb_frontend: dtv_property_process_set() cleanups

[Mauro Carvalho Chehab]

From: Satendra Singh Thakur 

Since all properties in the func dtv_property_process_set() use
at most 4 bytes arguments, change the code to pass
u32 cmd and u32 data as function arguments, instead of passing a
pointer to the entire struct dtv_property *tvp.

Instead of having a generic dtv_property_dump(), added its own
properties debug logic in the dtv_property_process_set().

Signed-off-by: Satendra Singh Thakur 
Reviewed-by: Shuah Khan 
Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-core/dvb_frontend.c | 125 --
 1 file changed, 72 insertions(+), 53 deletions(-)

diff --git a/drivers/media/dvb-core/dvb_frontend.c 
b/drivers/media/dvb-core/dvb_frontend.c
index 768d7703bdb3..717b84e50a4a 100644
--- a/drivers/media/dvb-core/dvb_frontend.c
+++ b/drivers/media/dvb-core/dvb_frontend.c
@@ -1107,22 +1107,19 @@ static struct dtv_cmds_h dtv_cmds[DTV_MAX_COMMAND + 1] 
= {
_DTV_CMD(DTV_STAT_TOTAL_BLOCK_COUNT, 0, 0),
 };
 
-static void dtv_property_dump(struct dvb_frontend *fe,
- bool is_set,
+static void dtv_get_property_dump(struct dvb_frontend *fe,
  struct dtv_property *tvp)
 {
int i;
 
if (tvp->cmd <= 0 || tvp->cmd > DTV_MAX_COMMAND) {
-   dev_warn(fe->dvb->device, "%s: %s tvp.cmd = 0x%08x undefined\n",
-   __func__,
-   is_set ? "SET" : "GET",
+   dev_warn(fe->dvb->device, "%s: GET tvp.cmd = 0x%08x undefined\n"
+   , __func__,
tvp->cmd);
return;
}
 
-   dev_dbg(fe->dvb->device, "%s: %s tvp.cmd= 0x%08x (%s)\n", __func__,
-   is_set ? "SET" : "GET",
+   dev_dbg(fe->dvb->device, "%s: GET tvp.cmd= 0x%08x (%s)\n", __func__,
tvp->cmd,
dtv_cmds[tvp->cmd].name);
 
@@ -1532,7 +1529,7 @@ static int dtv_property_process_get(struct dvb_frontend 
*fe,
return -EINVAL;
}
 
-   dtv_property_dump(fe, false, tvp);
+   dtv_get_property_dump(fe, tvp);
 
return 0;
 }
@@ -1755,16 +1752,36 @@ static int dvbv3_set_delivery_system(struct 
dvb_frontend *fe)
return emulate_delivery_system(fe, delsys);
 }
 
+/**
+ * dtv_property_process_set -  Sets a single DTV property
+ * @fe:Pointer to  dvb_frontend
+ * @file:  Pointer to  file
+ * @cmd:   Digital TV command
+ * @data:  An unsigned 32-bits number
+ *
+ * This routine assigns the property
+ * value to the corresponding member of
+ *  dtv_frontend_properties
+ *
+ * Returns:
+ * Zero on success, negative errno on failure.
+ */
 static int dtv_property_process_set(struct dvb_frontend *fe,
-   struct dtv_property *tvp,
-   struct file *file)
+   struct file *file,
+   u32 cmd, u32 data)
 {
int r = 0;
struct dtv_frontend_properties *c = >dtv_property_cache;
 
-   dtv_property_dump(fe, true, tvp);
-
-   switch(tvp->cmd) {
+   /** Dump DTV command name and value*/
+   if (!cmd || cmd > DTV_MAX_COMMAND)
+   dev_warn(fe->dvb->device, "%s: SET cmd 0x%08x undefined\n",
+__func__, cmd);
+   else
+   dev_dbg(fe->dvb->device,
+   "%s: SET cmd 0x%08x (%s) to 0x%08x\n",
+   __func__, cmd, dtv_cmds[cmd].name, data);
+   switch (cmd) {
case DTV_CLEAR:
/*
 * Reset a cache of data specific to the frontend here. This 
does
@@ -1784,133 +1801,133 @@ static int dtv_property_process_set(struct 
dvb_frontend *fe,
r = dtv_set_frontend(fe);
break;
case DTV_FREQUENCY:
-   c->frequency = tvp->u.data;
+   c->frequency = data;
break;
case DTV_MODULATION:
-   c->modulation = tvp->u.data;
+   c->modulation = data;
break;
case DTV_BANDWIDTH_HZ:
-   c->bandwidth_hz = tvp->u.data;
+   c->bandwidth_hz = data;
break;
case DTV_INVERSION:
-   c->inversion = tvp->u.data;
+   c->inversion = data;
break;
case DTV_SYMBOL_RATE:
-   c->symbol_rate = tvp->u.data;
+   c->symbol_rate = data;
break;
case DTV_INNER_FEC:
-   c->fec_inner = tvp->u.data;
+   c->fec_inner = data;
break;
case DTV_PILOT:
-   c->pilot = tvp->u.data;
+   c->pilot = data;
break;
case DTV_ROLLOFF:
-   c->rolloff = tvp->u.data;
+   

[PATCH v2 08/37] media: dvb_frontend: cleanup ioctl handling logic

[Mauro Carvalho Chehab]

Currently, there are two handlers for ioctls:
 - dvb_frontend_ioctl_properties()
 - dvb_frontend_ioctl_legacy()

Despite their names, both handles non-legacy DVB ioctls.

Besides that, there's no reason why to not handle all ioctls
on a single handler function.

So, merge them into a single function (dvb_frontend_handle_ioctl)
and reorganize the ioctl's to indicate what's the current DVB
API and what's deprecated.

Despite the big diff, the handling logic for each ioctl is the
same as before.

Reviewed-by: Shuah Khan 
Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-core/dvb_frontend.c | 328 --
 1 file changed, 158 insertions(+), 170 deletions(-)

diff --git a/drivers/media/dvb-core/dvb_frontend.c 
b/drivers/media/dvb-core/dvb_frontend.c
index 725cb1c8a088..9e6ee9df233b 100644
--- a/drivers/media/dvb-core/dvb_frontend.c
+++ b/drivers/media/dvb-core/dvb_frontend.c
@@ -1315,10 +1315,8 @@ static int dtv_get_frontend(struct dvb_frontend *fe,
return 0;
 }
 
-static int dvb_frontend_ioctl_legacy(struct file *file,
-   unsigned int cmd, void *parg);
-static int dvb_frontend_ioctl_properties(struct file *file,
-   unsigned int cmd, void *parg);
+static int dvb_frontend_handle_ioctl(struct file *file,
+unsigned int cmd, void *parg);
 
 static int dtv_property_process_get(struct dvb_frontend *fe,
const struct dtv_frontend_properties *c,
@@ -1816,12 +1814,12 @@ static int dtv_property_process_set(struct dvb_frontend 
*fe,
break;
case DTV_VOLTAGE:
c->voltage = tvp->u.data;
-   r = dvb_frontend_ioctl_legacy(file, FE_SET_VOLTAGE,
+   r = dvb_frontend_handle_ioctl(file, FE_SET_VOLTAGE,
(void *)c->voltage);
break;
case DTV_TONE:
c->sectone = tvp->u.data;
-   r = dvb_frontend_ioctl_legacy(file, FE_SET_TONE,
+   r = dvb_frontend_handle_ioctl(file, FE_SET_TONE,
(void *)c->sectone);
break;
case DTV_CODE_RATE_HP:
@@ -1928,14 +1926,13 @@ static int dtv_property_process_set(struct dvb_frontend 
*fe,
return r;
 }
 
-static int dvb_frontend_ioctl(struct file *file,
-   unsigned int cmd, void *parg)
+static int dvb_frontend_ioctl(struct file *file, unsigned int cmd, void *parg)
 {
struct dvb_device *dvbdev = file->private_data;
struct dvb_frontend *fe = dvbdev->priv;
struct dtv_frontend_properties *c = >dtv_property_cache;
struct dvb_frontend_private *fepriv = fe->frontend_priv;
-   int err = -EOPNOTSUPP;
+   int err;
 
dev_dbg(fe->dvb->device, "%s: (%d)\n", __func__, _IOC_NR(cmd));
if (down_interruptible(>sem))
@@ -1953,121 +1950,13 @@ static int dvb_frontend_ioctl(struct file *file,
return -EPERM;
}
 
-   if ((cmd == FE_SET_PROPERTY) || (cmd == FE_GET_PROPERTY))
-   err = dvb_frontend_ioctl_properties(file, cmd, parg);
-   else {
-   c->state = DTV_UNDEFINED;
-   err = dvb_frontend_ioctl_legacy(file, cmd, parg);
-   }
+   c->state = DTV_UNDEFINED;
+   err = dvb_frontend_handle_ioctl(file, cmd, parg);
 
up(>sem);
return err;
 }
 
-static int dvb_frontend_ioctl_properties(struct file *file,
-   unsigned int cmd, void *parg)
-{
-   struct dvb_device *dvbdev = file->private_data;
-   struct dvb_frontend *fe = dvbdev->priv;
-   struct dvb_frontend_private *fepriv = fe->frontend_priv;
-   struct dtv_frontend_properties *c = >dtv_property_cache;
-   int err, i;
-
-   dev_dbg(fe->dvb->device, "%s:\n", __func__);
-
-   switch(cmd) {
-   case FE_SET_PROPERTY: {
-   struct dtv_properties *tvps = parg;
-   struct dtv_property *tvp = NULL;
-
-   dev_dbg(fe->dvb->device, "%s: properties.num = %d\n",
-   __func__, tvps->num);
-   dev_dbg(fe->dvb->device, "%s: properties.props = %p\n",
-   __func__, tvps->props);
-
-   /*
-* Put an arbitrary limit on the number of messages that can
-* be sent at once
-*/
-   if (!tvps->num || (tvps->num > DTV_IOCTL_MAX_MSGS))
-   return -EINVAL;
-
-   tvp = memdup_user(tvps->props, tvps->num * sizeof(*tvp));
-   if (IS_ERR(tvp))
-   return PTR_ERR(tvp);
-
-   for (i = 0; i < tvps->num; i++) {
-   err = dtv_property_process_set(fe, tvp + i, file);
-   if (err < 0) {
-   kfree(tvp);
-   return err;
-   }
-   (tvp 

[PATCH v2 01/37] media: dvb_frontend: only use kref after initialized

[Mauro Carvalho Chehab]

As reported by Laurent, when a DVB frontend need to register
two drivers (e. g. a tuner and a demod), if the second driver
fails to register (for example because it was not compiled),
the error handling logic frees the frontend by calling
dvb_frontend_detach(). That used to work fine, but changeset
1f862a68df24 ("[media] dvb_frontend: move kref to struct dvb_frontend")
added a kref at struct dvb_frontend. So, now, instead of just
freeing the data, the error handling do a kref_put().

That works fine only after dvb_register_frontend() succeeds.

While it would be possible to add a helper function that
would be initializing earlier the kref, that would require
changing every single DVB frontend on non-trivial ways, and
would make frontends different than other drivers.

So, instead of doing that, let's focus on the real issue:
only call kref_put() after kref_init(). That's easy to
check, as, when the dvb frontend is successfuly registered,
it will allocate its own private struct. So, if such
struct is allocated, it means that it is safe to use
kref_put(). If not, then nobody is using yet the frontend,
and it is safe to just deallocate it.

Fixes: 1f862a68df24 ("[media] dvb_frontend: move kref to struct dvb_frontend")
Reported-by: Laurent Pinchart 
Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-core/dvb_frontend.c | 25 +
 1 file changed, 21 insertions(+), 4 deletions(-)

diff --git a/drivers/media/dvb-core/dvb_frontend.c 
b/drivers/media/dvb-core/dvb_frontend.c
index 2fcba1616168..9139d01ba7ed 100644
--- a/drivers/media/dvb-core/dvb_frontend.c
+++ b/drivers/media/dvb-core/dvb_frontend.c
@@ -141,22 +141,39 @@ struct dvb_frontend_private {
 static void dvb_frontend_invoke_release(struct dvb_frontend *fe,
void (*release)(struct dvb_frontend 
*fe));
 
-static void dvb_frontend_free(struct kref *ref)
+static void __dvb_frontend_free(struct dvb_frontend *fe)
 {
-   struct dvb_frontend *fe =
-   container_of(ref, struct dvb_frontend, refcount);
struct dvb_frontend_private *fepriv = fe->frontend_priv;
 
+   if (!fepriv)
+   return;
+
dvb_free_device(fepriv->dvbdev);
 
dvb_frontend_invoke_release(fe, fe->ops.release);
 
kfree(fepriv);
+   fe->frontend_priv = NULL;
+}
+
+static void dvb_frontend_free(struct kref *ref)
+{
+   struct dvb_frontend *fe =
+   container_of(ref, struct dvb_frontend, refcount);
+
+   __dvb_frontend_free(fe);
 }
 
 static void dvb_frontend_put(struct dvb_frontend *fe)
 {
-   kref_put(>refcount, dvb_frontend_free);
+   /*
+* Check if the frontend was registered, as otherwise
+* kref was not initialized yet.
+*/
+   if (fe->frontend_priv)
+   kref_put(>refcount, dvb_frontend_free);
+   else
+   __dvb_frontend_free(fe);
 }
 
 static void dvb_frontend_get(struct dvb_frontend *fe)
-- 
2.13.5

[PATCH v2 09/37] media: dvb_frontend: get rid of property cache's state

[Mauro Carvalho Chehab]

In the past, I guess the idea was to use state in order to
allow an autofush logic. However, in the current code, it is
used only for debug messages, on a poor man's solution, as
there's already a debug message to indicate when the properties
got flushed.

So, just get rid of it for good.

Reviewed-by: Shuah Khan 
Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-core/dvb_frontend.c | 20 ++--
 drivers/media/dvb-core/dvb_frontend.h |  5 -
 2 files changed, 6 insertions(+), 19 deletions(-)

diff --git a/drivers/media/dvb-core/dvb_frontend.c 
b/drivers/media/dvb-core/dvb_frontend.c
index 9e6ee9df233b..01bd19fd4c57 100644
--- a/drivers/media/dvb-core/dvb_frontend.c
+++ b/drivers/media/dvb-core/dvb_frontend.c
@@ -951,8 +951,6 @@ static int dvb_frontend_clear_cache(struct dvb_frontend *fe)
memset(c, 0, offsetof(struct dtv_frontend_properties, strength));
c->delivery_system = delsys;
 
-   c->state = DTV_CLEAR;
-
dev_dbg(fe->dvb->device, "%s: Clearing cache for delivery system %d\n",
__func__, c->delivery_system);
 
@@ -1775,13 +1773,13 @@ static int dtv_property_process_set(struct dvb_frontend 
*fe,
dvb_frontend_clear_cache(fe);
break;
case DTV_TUNE:
-   /* interpret the cache of data, build either a traditional 
frontend
-* tunerequest so we can pass validation in the FE_SET_FRONTEND
-* ioctl.
+   /*
+* Use the cached Digital TV properties to tune the
+* frontend
 */
-   c->state = tvp->cmd;
-   dev_dbg(fe->dvb->device, "%s: Finalised property cache\n",
-   __func__);
+   dev_dbg(fe->dvb->device,
+   "%s: Setting the frontend from property cache\n",
+   __func__);
 
r = dtv_set_frontend(fe);
break;
@@ -1930,7 +1928,6 @@ static int dvb_frontend_ioctl(struct file *file, unsigned 
int cmd, void *parg)
 {
struct dvb_device *dvbdev = file->private_data;
struct dvb_frontend *fe = dvbdev->priv;
-   struct dtv_frontend_properties *c = >dtv_property_cache;
struct dvb_frontend_private *fepriv = fe->frontend_priv;
int err;
 
@@ -1950,7 +1947,6 @@ static int dvb_frontend_ioctl(struct file *file, unsigned 
int cmd, void *parg)
return -EPERM;
}
 
-   c->state = DTV_UNDEFINED;
err = dvb_frontend_handle_ioctl(file, cmd, parg);
 
up(>sem);
@@ -2134,10 +2130,6 @@ static int dvb_frontend_handle_ioctl(struct file *file,
}
(tvp + i)->result = err;
}
-
-   if (c->state == DTV_TUNE)
-   dev_dbg(fe->dvb->device, "%s: Property cache is full, 
tuning\n", __func__);
-
kfree(tvp);
break;
}
diff --git a/drivers/media/dvb-core/dvb_frontend.h 
b/drivers/media/dvb-core/dvb_frontend.h
index 852b91ba49d2..1bdeb10f0d78 100644
--- a/drivers/media/dvb-core/dvb_frontend.h
+++ b/drivers/media/dvb-core/dvb_frontend.h
@@ -620,11 +620,6 @@ struct dtv_frontend_properties {
struct dtv_fe_stats post_bit_count;
struct dtv_fe_stats block_error;
struct dtv_fe_stats block_count;
-
-   /* private: */
-   /* Cache State */
-   u32 state;
-
 };
 
 #define DVB_FE_NO_EXIT  0
-- 
2.13.5

[PATCH v2 14/37] media: dvbdev: fully document its functions

[Mauro Carvalho Chehab]

There are several functions at the dvbdev that are common to all
digital TV device nodes with aren't documented.

Add documentation for them. No functional changes.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-core/dvbdev.h | 86 +
 1 file changed, 78 insertions(+), 8 deletions(-)

diff --git a/drivers/media/dvb-core/dvbdev.h b/drivers/media/dvb-core/dvbdev.h
index 53058da83873..bbc1c20c0529 100644
--- a/drivers/media/dvb-core/dvbdev.h
+++ b/drivers/media/dvb-core/dvbdev.h
@@ -261,7 +261,7 @@ void dvb_unregister_device(struct dvb_device *dvbdev);
  * dvb_create_media_graph - Creates media graph for the Digital TV part of the
  * device.
  *
- * @adap:  pointer to struct dvb_adapter
+ * @adap:  pointer to  dvb_adapter
  * @create_rf_connector:   if true, it creates the RF connector too
  *
  * This function checks all DVB-related functions at the media controller
@@ -274,12 +274,23 @@ void dvb_unregister_device(struct dvb_device *dvbdev);
 __must_check int dvb_create_media_graph(struct dvb_adapter *adap,
bool create_rf_connector);
 
+/**
+ * dvb_register_media_controller - registers a media controller at DVB adapter
+ *
+ * @adap:  pointer to  dvb_adapter
+ * @mdev:  pointer to  media_device
+ */
 static inline void dvb_register_media_controller(struct dvb_adapter *adap,
 struct media_device *mdev)
 {
adap->mdev = mdev;
 }
 
+/**
+ * dvb_get_media_controller - gets the associated media controller
+ *
+ * @adap:  pointer to  dvb_adapter
+ */
 static inline struct media_device
 *dvb_get_media_controller(struct dvb_adapter *adap)
 {
@@ -296,20 +307,71 @@ int dvb_create_media_graph(struct dvb_adapter *adap,
 #define dvb_get_media_controller(a) NULL
 #endif
 
-int dvb_generic_open (struct inode *inode, struct file *file);
-int dvb_generic_release (struct inode *inode, struct file *file);
-long dvb_generic_ioctl (struct file *file,
- unsigned int cmd, unsigned long arg);
+/**
+ * dvb_generic_open - Digital TV open function, used by DVB devices
+ *
+ * @inode: pointer to  inode.
+ * @file: pointer to  file.
+ *
+ * Checks if a DVB devnode is still valid, and if the permissions are
+ * OK and increment negative use count.
+ */
+int dvb_generic_open(struct inode *inode, struct file *file);
 
-/* we don't mess with video_usercopy() any more,
-we simply define out own dvb_usercopy(), which will hopefully become
-generic_usercopy()  someday... */
+/**
+ * dvb_generic_close - Digital TV close function, used by DVB devices
+ *
+ * @inode: pointer to  inode.
+ * @file: pointer to  file.
+ *
+ * Checks if a DVB devnode is still valid, and if the permissions are
+ * OK and decrement negative use count.
+ */
+int dvb_generic_release(struct inode *inode, struct file *file);
 
+/**
+ * dvb_generic_ioctl - Digital TV close function, used by DVB devices
+ *
+ * @file: pointer to  file.
+ * @cmd: Ioctl name.
+ * @arg: Ioctl argument.
+ *
+ * Checks if a DVB devnode and struct dvbdev.kernel_ioctl is still valid.
+ * If so, calls dvb_usercopy().
+ */
+long dvb_generic_ioctl(struct file *file,
+  unsigned int cmd, unsigned long arg);
+
+/**
+ * dvb_usercopy - copies data from/to userspace memory when an ioctl is
+ *  issued.
+ *
+ * @file: Pointer to struct 
+ * @cmd: Ioctl name.
+ * @arg: Ioctl argument.
+ * @func: function that will actually handle the ioctl
+ *
+ * Ancillary function that uses ioctl direction and size to copy from
+ * userspace. Then, it calls @func, and, if needed, data is copied back
+ * to userspace.
+ */
 int dvb_usercopy(struct file *file, unsigned int cmd, unsigned long arg,
 int (*func)(struct file *file, unsigned int cmd, void *arg));
 
 /** generic DVB attach function. */
 #ifdef CONFIG_MEDIA_ATTACH
+
+/**
+ * dvb_attach - attaches a DVB frontend into the DVB core.
+ *
+ * @FUNCTION:  function on a frontend module to be called.
+ * @ARGS...:   @FUNCTION arguments.
+ *
+ * This ancillary function loads a frontend module in runtime and runs
+ * the @FUNCTION function there, with @ARGS.
+ * As it increments symbol usage cont, at unregister, dvb_detach()
+ * should be called.
+ */
 #define dvb_attach(FUNCTION, ARGS...) ({ \
void *__r = NULL; \
typeof() __a = symbol_request(FUNCTION); \
@@ -323,6 +385,14 @@ int dvb_usercopy(struct file *file, unsigned int cmd, 
unsigned long arg,
__r; \
 })
 
+/**
+ * dvb_detach - detaches a DVB frontend loaded via dvb_attach()
+ *
+ * @FUNC:  attach function
+ *
+ * Decrements usage count for a function previously called via dvb_attach().
+ */
+
 #define dvb_detach(FUNC)   symbol_put_addr(FUNC)
 
 #else
-- 
2.13.5

[PATCH v2 18/37] media: dtv-demux.rst: minor markup improvements

[Mauro Carvalho Chehab]

Add a cross-reference to a mentioned structure and split
the kernel-doc stuff on a separate chapter.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/media/kapi/dtv-demux.rst | 11 ++-
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/Documentation/media/kapi/dtv-demux.rst 
b/Documentation/media/kapi/dtv-demux.rst
index 8169c479156e..3ee69266e206 100644
--- a/Documentation/media/kapi/dtv-demux.rst
+++ b/Documentation/media/kapi/dtv-demux.rst
@@ -7,8 +7,8 @@ Digital TV Demux
 The Kernel Digital TV Demux kABI defines a driver-internal interface for
 registering low-level, hardware specific driver to a hardware independent
 demux layer. It is only of interest for Digital TV device driver writers.
-The header file for this kABI is named demux.h and located in
-drivers/media/dvb-core.
+The header file for this kABI is named ``demux.h`` and located in
+``drivers/media/dvb-core``.
 
 The demux kABI should be implemented for each demux in the system. It is
 used to select the TS source of a demux and to manage the demux resources.
@@ -27,7 +27,7 @@ tuning, are devined via the Digital TV Frontend kABI.
 The functions that implement the abstract interface demux should be defined
 static or module private and registered to the Demux core for external
 access. It is not necessary to implement every function in the struct
-_demux. For example, a demux interface might support Section filtering,
+:c:type:`dmx_demux`. For example, a demux interface might support Section 
filtering,
 but not PES filtering. The kABI client is expected to check the value of any
 function pointer before calling the function: the value of ``NULL`` means
 that the function is not available.
@@ -43,8 +43,6 @@ Linux Kernel calls the functions of a network device 
interface from a
 bottom half context. Thus, if a demux kABI function is called from network
 device code, the function must not sleep.
 
-
-
 Demux Callback API
 ~~
 
@@ -68,4 +66,7 @@ function call directly from a hardware interrupt.
 This mechanism is implemented by :c:func:`dmx_ts_cb()` and 
:c:func:`dmx_section_cb()`
 callbacks.
 
+Digital TV Demux functions and types
+
+
 .. kernel-doc:: drivers/media/dvb-core/demux.h
-- 
2.13.5

[PATCH v2 07/37] media: dvb_frontend: cleanup dvb_frontend_ioctl_properties()

[Mauro Carvalho Chehab]

Use a switch() on this function, just like on other ioctl
handlers and handle parameters inside each part of the
switch.

That makes it easier to integrate with the already existing
ioctl handler function.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-core/dvb_frontend.c | 83 +--
 1 file changed, 51 insertions(+), 32 deletions(-)

diff --git a/drivers/media/dvb-core/dvb_frontend.c 
b/drivers/media/dvb-core/dvb_frontend.c
index 8abe4f541a36..725cb1c8a088 100644
--- a/drivers/media/dvb-core/dvb_frontend.c
+++ b/drivers/media/dvb-core/dvb_frontend.c
@@ -1971,21 +1971,25 @@ static int dvb_frontend_ioctl_properties(struct file 
*file,
struct dvb_frontend *fe = dvbdev->priv;
struct dvb_frontend_private *fepriv = fe->frontend_priv;
struct dtv_frontend_properties *c = >dtv_property_cache;
-   int err = 0;
-
-   struct dtv_properties *tvps = parg;
-   struct dtv_property *tvp = NULL;
-   int i;
+   int err, i;
 
dev_dbg(fe->dvb->device, "%s:\n", __func__);
 
-   if (cmd == FE_SET_PROPERTY) {
-   dev_dbg(fe->dvb->device, "%s: properties.num = %d\n", __func__, 
tvps->num);
-   dev_dbg(fe->dvb->device, "%s: properties.props = %p\n", 
__func__, tvps->props);
+   switch(cmd) {
+   case FE_SET_PROPERTY: {
+   struct dtv_properties *tvps = parg;
+   struct dtv_property *tvp = NULL;
 
-   /* Put an arbitrary limit on the number of messages that can
-* be sent at once */
-   if ((tvps->num == 0) || (tvps->num > DTV_IOCTL_MAX_MSGS))
+   dev_dbg(fe->dvb->device, "%s: properties.num = %d\n",
+   __func__, tvps->num);
+   dev_dbg(fe->dvb->device, "%s: properties.props = %p\n",
+   __func__, tvps->props);
+
+   /*
+* Put an arbitrary limit on the number of messages that can
+* be sent at once
+*/
+   if (!tvps->num || (tvps->num > DTV_IOCTL_MAX_MSGS))
return -EINVAL;
 
tvp = memdup_user(tvps->props, tvps->num * sizeof(*tvp));
@@ -1994,23 +1998,34 @@ static int dvb_frontend_ioctl_properties(struct file 
*file,
 
for (i = 0; i < tvps->num; i++) {
err = dtv_property_process_set(fe, tvp + i, file);
-   if (err < 0)
-   goto out;
+   if (err < 0) {
+   kfree(tvp);
+   return err;
+   }
(tvp + i)->result = err;
}
 
if (c->state == DTV_TUNE)
dev_dbg(fe->dvb->device, "%s: Property cache is full, 
tuning\n", __func__);
 
-   } else if (cmd == FE_GET_PROPERTY) {
+   kfree(tvp);
+   break;
+   }
+   case FE_GET_PROPERTY: {
+   struct dtv_properties *tvps = parg;
+   struct dtv_property *tvp = NULL;
struct dtv_frontend_properties getp = fe->dtv_property_cache;
 
-   dev_dbg(fe->dvb->device, "%s: properties.num = %d\n", __func__, 
tvps->num);
-   dev_dbg(fe->dvb->device, "%s: properties.props = %p\n", 
__func__, tvps->props);
+   dev_dbg(fe->dvb->device, "%s: properties.num = %d\n",
+   __func__, tvps->num);
+   dev_dbg(fe->dvb->device, "%s: properties.props = %p\n",
+   __func__, tvps->props);
 
-   /* Put an arbitrary limit on the number of messages that can
-* be sent at once */
-   if ((tvps->num == 0) || (tvps->num > DTV_IOCTL_MAX_MSGS))
+   /*
+* Put an arbitrary limit on the number of messages that can
+* be sent at once
+*/
+   if (!tvps->num || (tvps->num > DTV_IOCTL_MAX_MSGS))
return -EINVAL;
 
tvp = memdup_user(tvps->props, tvps->num * sizeof(*tvp));
@@ -2025,28 +2040,32 @@ static int dvb_frontend_ioctl_properties(struct file 
*file,
 */
if (fepriv->state != FESTATE_IDLE) {
err = dtv_get_frontend(fe, , NULL);
-   if (err < 0)
-   goto out;
+   if (err < 0) {
+   kfree(tvp);
+   return err;
+   }
}
for (i = 0; i < tvps->num; i++) {
err = dtv_property_process_get(fe, , tvp + i, 
file);
-   if (err < 0)
-   goto out;
+   if (err < 0) {
+   kfree(tvp);
+   return err;
+   }
 

[PATCH v2 05/37] media: dvb_frontend: get rid of get_property() callback

[Mauro Carvalho Chehab]

Only lg2160 implement gets_property, but there's no need for that,
as no other driver calls this callback, as get_frontend() does the
same, and set_frontend() also calls lg2160 get_frontend().

So, get rid of it.

Signed-off-by: Mauro Carvalho Chehab 
Reviewed-by: Michael Ira Krufky 
---
 drivers/media/dvb-core/dvb_frontend.c |  9 +
 drivers/media/dvb-core/dvb_frontend.h |  3 ---
 drivers/media/dvb-frontends/lg2160.c  | 14 --
 3 files changed, 1 insertion(+), 25 deletions(-)

diff --git a/drivers/media/dvb-core/dvb_frontend.c 
b/drivers/media/dvb-core/dvb_frontend.c
index 9139d01ba7ed..5d00e46d9432 100644
--- a/drivers/media/dvb-core/dvb_frontend.c
+++ b/drivers/media/dvb-core/dvb_frontend.c
@@ -1325,7 +1325,7 @@ static int dtv_property_process_get(struct dvb_frontend 
*fe,
struct dtv_property *tvp,
struct file *file)
 {
-   int r, ncaps;
+   int ncaps;
 
switch(tvp->cmd) {
case DTV_ENUM_DELSYS:
@@ -1536,13 +1536,6 @@ static int dtv_property_process_get(struct dvb_frontend 
*fe,
return -EINVAL;
}
 
-   /* Allow the frontend to override outgoing properties */
-   if (fe->ops.get_property) {
-   r = fe->ops.get_property(fe, tvp);
-   if (r < 0)
-   return r;
-   }
-
dtv_property_dump(fe, false, tvp);
 
return 0;
diff --git a/drivers/media/dvb-core/dvb_frontend.h 
b/drivers/media/dvb-core/dvb_frontend.h
index 907a05bde162..4d05846f2c1c 100644
--- a/drivers/media/dvb-core/dvb_frontend.h
+++ b/drivers/media/dvb-core/dvb_frontend.h
@@ -403,8 +403,6 @@ struct dtv_frontend_properties;
  * @analog_ops:pointer to struct analog_demod_ops
  * @set_property:  callback function to allow the frontend to validade
  * incoming properties. Should not be used on new drivers.
- * @get_property:  callback function to allow the frontend to override
- * outcoming properties. Should not be used on new drivers.
  */
 struct dvb_frontend_ops {
 
@@ -468,7 +466,6 @@ struct dvb_frontend_ops {
struct analog_demod_ops analog_ops;
 
int (*set_property)(struct dvb_frontend* fe, struct dtv_property* tvp);
-   int (*get_property)(struct dvb_frontend* fe, struct dtv_property* tvp);
 };
 
 #ifdef __DVB_CORE__
diff --git a/drivers/media/dvb-frontends/lg2160.c 
b/drivers/media/dvb-frontends/lg2160.c
index 5798079add10..9854096839ae 100644
--- a/drivers/media/dvb-frontends/lg2160.c
+++ b/drivers/media/dvb-frontends/lg2160.c
@@ -1048,16 +1048,6 @@ static int lg216x_get_frontend(struct dvb_frontend *fe,
return ret;
 }
 
-static int lg216x_get_property(struct dvb_frontend *fe,
-  struct dtv_property *tvp)
-{
-   struct dtv_frontend_properties *c = >dtv_property_cache;
-
-   return (DTV_ATSCMH_FIC_VER == tvp->cmd) ?
-   lg216x_get_frontend(fe, c) : 0;
-}
-
-
 static int lg2160_set_frontend(struct dvb_frontend *fe)
 {
struct lg216x_state *state = fe->demodulator_priv;
@@ -1368,8 +1358,6 @@ static const struct dvb_frontend_ops lg2160_ops = {
.init = lg216x_init,
.sleep= lg216x_sleep,
 #endif
-   .get_property = lg216x_get_property,
-
.set_frontend = lg2160_set_frontend,
.get_frontend = lg216x_get_frontend,
.get_tune_settings= lg216x_get_tune_settings,
@@ -1396,8 +1384,6 @@ static const struct dvb_frontend_ops lg2161_ops = {
.init = lg216x_init,
.sleep= lg216x_sleep,
 #endif
-   .get_property = lg216x_get_property,
-
.set_frontend = lg2160_set_frontend,
.get_frontend = lg216x_get_frontend,
.get_tune_settings= lg216x_get_tune_settings,
-- 
2.13.5

[PATCH v2 15/37] media: dvb_frontend.h: improve kernel-doc markups

[Mauro Carvalho Chehab]

Several minor adjustments at the kernel-doc markups:

- some syntax fixes;
- some cross-references;
- add cross-references for the mentioned ioctls;
- some constants marked as such.

No functional changes.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-core/dvb_frontend.h | 94 +--
 1 file changed, 47 insertions(+), 47 deletions(-)

diff --git a/drivers/media/dvb-core/dvb_frontend.h 
b/drivers/media/dvb-core/dvb_frontend.h
index d273ed2f72c9..ace0c2fb26c2 100644
--- a/drivers/media/dvb-core/dvb_frontend.h
+++ b/drivers/media/dvb-core/dvb_frontend.h
@@ -180,8 +180,8 @@ enum dvbfe_search {
 /**
  * struct dvb_tuner_ops - Tuner information and callbacks
  *
- * @info:  embedded struct dvb_tuner_info with tuner properties
- * @release:   callback function called when frontend is dettached.
+ * @info:  embedded  dvb_tuner_info with tuner properties
+ * @release:   callback function called when frontend is detached.
  * drivers should free any allocated memory.
  * @init:  callback function used to initialize the tuner device.
  * @sleep: callback function used to put the tuner to sleep.
@@ -191,14 +191,14 @@ enum dvbfe_search {
  * resuming from suspend.
  * @set_params:callback function used to inform the tuner to 
tune
  * into a digital TV channel. The properties to be used
- * are stored at @dvb_frontend.dtv_property_cache;. The
- * tuner demod can change the parameters to reflect the
- * changes needed for the channel to be tuned, and
+ * are stored at  dvb_frontend.dtv_property_cache.
+ * The tuner demod can change the parameters to reflect
+ * the changes needed for the channel to be tuned, and
  * update statistics. This is the recommended way to set
  * the tuner parameters and should be used on newer
  * drivers.
  * @set_analog_params: callback function used to tune into an analog TV
- * channel on hybrid tuners. It passes @analog_parameters;
+ * channel on hybrid tuners. It passes @analog_parameters
  * to the driver.
  * @set_config:callback function used to send some 
tuner-specific
  * parameters.
@@ -207,9 +207,9 @@ enum dvbfe_search {
  * @get_if_frequency:  get the Intermediate Frequency, in Hz. For baseband,
  * should return 0.
  * @get_status:returns the frontend lock status
- * @get_rf_strength:   returns the RF signal strengh. Used mostly to support
+ * @get_rf_strength:   returns the RF signal strength. Used mostly to support
  * analog TV and radio. Digital TV should report, instead,
- * via DVBv5 API (@dvb_frontend.dtv_property_cache;).
+ * via DVBv5 API ( dvb_frontend.dtv_property_cache).
  * @get_afc:   Used only by analog TV core. Reports the frequency
  * drift due to AFC.
  * @calc_regs: callback function used to pass register data settings
@@ -217,7 +217,7 @@ enum dvbfe_search {
  * @set_frequency: Set a new frequency. Shouldn't be used on newer drivers.
  * @set_bandwidth: Set a new frequency. Shouldn't be used on newer drivers.
  *
- * NOTE: frequencies used on get_frequency and set_frequency are in Hz for
+ * NOTE: frequencies used on @get_frequency and @set_frequency are in Hz for
  * terrestrial/cable or kHz for satellite.
  *
  */
@@ -283,14 +283,14 @@ struct analog_demod_info {
  * @set_params:callback function used to inform the demod to 
set the
  * demodulator parameters needed to decode an analog or
  * radio channel. The properties are passed via
- * struct @analog_params;.
+ *  analog_params.
  * @has_signal:returns 0x if has signal, or 0 if it 
doesn't.
  * @get_afc:   Used only by analog TV core. Reports the frequency
  * drift due to AFC.
  * @tuner_status:  callback function that returns tuner status bits, e. g.
- * TUNER_STATUS_LOCKED and TUNER_STATUS_STEREO.
+ * %TUNER_STATUS_LOCKED and %TUNER_STATUS_STEREO.
  * @standby:   set the tuner to standby mode.
- * @release:   callback function called when frontend is dettached.
+ * @release:   callback function called when frontend is detached.
  * drivers should free any allocated memory.
  * @i2c_gate_ctrl: controls the I2C gate. Newer drivers should use I2C
  * mux support instead.
@@ -321,10 +321,10 @@ struct dtv_frontend_properties;
  * struct 

[PATCH v2 03/37] media: stv6110: get rid of a srate dead code

[Mauro Carvalho Chehab]

The stv6110 has a weird code that checks if get_property
and set_property ioctls are defined. If they're, it initializes
a "srate" var from properties cache. Otherwise, it sets to
15MBaud, with won't make any sense.

Thankfully, it seems that someone else discovered the issue in
the past, as "srate" is currently not used anywhere!

So, get rid of that really weird dead code logic.

Reported-by: Honza Petrous 
Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-frontends/stv6110.c | 9 -
 1 file changed, 9 deletions(-)

diff --git a/drivers/media/dvb-frontends/stv6110.c 
b/drivers/media/dvb-frontends/stv6110.c
index e4fd9c1b0560..6aad0efa3174 100644
--- a/drivers/media/dvb-frontends/stv6110.c
+++ b/drivers/media/dvb-frontends/stv6110.c
@@ -258,11 +258,9 @@ static int stv6110_get_frequency(struct dvb_frontend *fe, 
u32 *frequency)
 static int stv6110_set_frequency(struct dvb_frontend *fe, u32 frequency)
 {
struct stv6110_priv *priv = fe->tuner_priv;
-   struct dtv_frontend_properties *c = >dtv_property_cache;
u8 ret = 0x04;
u32 divider, ref, p, presc, i, result_freq, vco_freq;
s32 p_calc, p_calc_opt = 1000, r_div, r_div_opt = 0, p_val;
-   s32 srate;
 
dprintk("%s, freq=%d kHz, mclk=%d Hz\n", __func__,
frequency, priv->mclk);
@@ -273,13 +271,6 @@ static int stv6110_set_frequency(struct dvb_frontend *fe, 
u32 frequency)
priv->mclk / 100) - 16) & 0x1f) << 3);
 
/* BB_GAIN = db/2 */
-   if (fe->ops.set_property && fe->ops.get_property) {
-   srate = c->symbol_rate;
-   dprintk("%s: Get Frontend parameters: srate=%d\n",
-   __func__, srate);
-   } else
-   srate = 1500;
-
priv->regs[RSTV6110_CTRL2] &= ~0x0f;
priv->regs[RSTV6110_CTRL2] |= (priv->gain & 0x0f);
 
-- 
2.13.5

[PATCH v2 12/37] media: dvb_frontend: fix return values for FE_SET_PROPERTY

[Mauro Carvalho Chehab]

There are several problems with regards to the return of
FE_SET_PROPERTY. The original idea were to return per-property
return codes via tvp->result field, and to return an updated
set of values.

However, that never worked. What's actually implemented is:

- the FE_SET_PROPERTY implementation doesn't call .get_frontend
  callback in order to get the actual parameters after return;

- the tvp->result field is only filled if there's no error.
  So, it is always filled with zero;

- FE_SET_PROPERTY doesn't call memdup_user() nor any other
  copy_to_user() function. So, any changes to the properties
  will be lost;

- FE_SET_PROPERTY is declared as a write-only ioctl (IOW).

While we could fix the above, it could cause regressions.

So, let's just assume what the code really does, updating
the documentation accordingly and removing the logic that
would update the discarded tvp->result.

Reviewed-by: Shuah Khan 
Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/media/uapi/dvb/fe-get-property.rst | 7 +--
 drivers/media/dvb-core/dvb_frontend.c| 2 --
 include/uapi/linux/dvb/frontend.h| 2 +-
 3 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/Documentation/media/uapi/dvb/fe-get-property.rst 
b/Documentation/media/uapi/dvb/fe-get-property.rst
index 948d2ba84f2c..b69741d9cedf 100644
--- a/Documentation/media/uapi/dvb/fe-get-property.rst
+++ b/Documentation/media/uapi/dvb/fe-get-property.rst
@@ -48,8 +48,11 @@ depends on the delivery system and on the device:
 
-  This call requires read/write access to the device.
 
-   -  At return, the values are updated to reflect the actual parameters
-  used.
+.. note::
+
+   At return, the values aren't updated to reflect the actual
+   parameters used. If the actual parameters are needed, an explicit
+   call to ``FE_GET_PROPERTY`` is needed.
 
 -  ``FE_GET_PROPERTY:``
 
diff --git a/drivers/media/dvb-core/dvb_frontend.c 
b/drivers/media/dvb-core/dvb_frontend.c
index 2036cf1b7784..768d7703bdb3 100644
--- a/drivers/media/dvb-core/dvb_frontend.c
+++ b/drivers/media/dvb-core/dvb_frontend.c
@@ -2142,7 +2142,6 @@ static int dvb_frontend_handle_ioctl(struct file *file,
kfree(tvp);
return err;
}
-   (tvp + i)->result = err;
}
kfree(tvp);
break;
@@ -2187,7 +2186,6 @@ static int dvb_frontend_handle_ioctl(struct file *file,
kfree(tvp);
return err;
}
-   (tvp + i)->result = err;
}
 
if (copy_to_user((void __user *)tvps->props, tvp,
diff --git a/include/uapi/linux/dvb/frontend.h 
b/include/uapi/linux/dvb/frontend.h
index 861cacd5711f..6bc26f35217b 100644
--- a/include/uapi/linux/dvb/frontend.h
+++ b/include/uapi/linux/dvb/frontend.h
@@ -830,7 +830,7 @@ struct dtv_fe_stats {
  * @cmd:   Digital TV command.
  * @reserved:  Not used.
  * @u: Union with the values for the command.
- * @result:Result of the command set (currently unused).
+ * @result:Unused
  *
  * The @u union may have either one of the values below:
  *
-- 
2.13.5

[PATCH v2 26/37] media: dvb_demux: document dvb_demux_filter and dvb_demux_feed

[Mauro Carvalho Chehab]

Document those two structs using kernel-doc markups.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-core/dvb_demux.h | 49 --
 1 file changed, 47 insertions(+), 2 deletions(-)

diff --git a/drivers/media/dvb-core/dvb_demux.h 
b/drivers/media/dvb-core/dvb_demux.h
index c9e94bc3a2e5..5b05e6320e33 100644
--- a/drivers/media/dvb-core/dvb_demux.h
+++ b/drivers/media/dvb-core/dvb_demux.h
@@ -60,6 +60,21 @@ enum dvb_dmx_state {
 
 #define SPEED_PKTS_INTERVAL 5
 
+/**
+ * struct dvb_demux_filter - Describes a DVB demux section filter.
+ *
+ * @filter:Section filter as defined by  dmx_section_filter.
+ * @maskandmode:   logical ``and`` bit mask.
+ * @maskandnotmode:logical ``and not`` bit mask.
+ * @doneq: flag that indicates when a filter is ready.
+ * @next:  pointer to the next section filter.
+ * @feed:   dvb_demux_feed pointer.
+ * @index: index of the used demux filter.
+ * @state: state of the filter as described by  dvb_dmx_state.
+ * @type:  type of the filter as described
+ * by  dvb_dmx_filter_type.
+ */
+
 struct dvb_demux_filter {
struct dmx_section_filter filter;
u8 maskandmode[DMX_MAX_FILTER_SIZE];
@@ -72,9 +87,39 @@ struct dvb_demux_filter {
enum dvb_dmx_state state;
enum dvb_dmx_filter_type type;
 
+   /* private: used only by av7110 */
u16 hw_handle;
 };
 
+/**
+ * struct dvb_demux_feed - describes a DVB field
+ *
+ * @feed:  a digital TV feed. It can either be a TS or a section feed:
+ *   - if the feed is TS, it contains  dvb_ts_feed;
+ *   - if the feed is section, it contains
+ *  dmx_section_feed.
+ * @cb:digital TV callbacks. depending on the feed type, it 
can be:
+ *   - if the feed is TS, it contains a dmx_ts_cb() callback;
+ *   - if the feed is section, it contains a dmx_section_cb() 
callback.
+ *
+ * @demux: pointer to  dvb_demux.
+ * @priv:  private data for the filter handling routine.
+ * @type:  type of the filter, as defined by  dvb_dmx_filter_type.
+ * @state: state of the filter as defined by  dvb_dmx_state.
+ * @pid:   PID to be filtered.
+ * @timeout:   feed timeout.
+ * @filter:pointer to  dvb_demux_filter.
+ * @ts_type:   type of TS, as defined by  ts_filter_type.
+ * @pes_type:  type of PES, as defined by  dmx_ts_pes.
+ * @cc:MPEG-TS packet continuity counter
+ * @pusi_seen: if true, indicates that a discontinuity was detected.
+ * it is used to prevent feeding of garbage from previous section.
+ * @peslen:length of the PES (Packet Elementary Stream).
+ * @list_head: head for the list of digital TV demux feeds.
+ * @index: a unique index for each feed. Can be used as hardware
+ * pid filter index.
+ *
+ */
 struct dvb_demux_feed {
union {
struct dmx_ts_feed ts;
@@ -99,12 +144,12 @@ struct dvb_demux_feed {
enum dmx_ts_pes pes_type;
 
int cc;
-   bool pusi_seen; /* prevents feeding of garbage from previous 
section */
+   bool pusi_seen;
 
u16 peslen;
 
struct list_head list_head;
-   unsigned int index; /* a unique index for each feed (can be used as 
hardware pid filter index) */
+   unsigned int index;
 };
 
 struct dvb_demux {
-- 
2.13.5

[PATCH v2 21/37] media: dvb_demux.h: get rid of unused timer at struct dvb_demux_filter

[Mauro Carvalho Chehab]

This field is not used. So, get rid of it.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-core/dvb_demux.h | 1 -
 1 file changed, 1 deletion(-)

diff --git a/drivers/media/dvb-core/dvb_demux.h 
b/drivers/media/dvb-core/dvb_demux.h
index b24d69b5a20f..045f7fd1a8b1 100644
--- a/drivers/media/dvb-core/dvb_demux.h
+++ b/drivers/media/dvb-core/dvb_demux.h
@@ -73,7 +73,6 @@ struct dvb_demux_filter {
enum dvb_dmx_filter_type type;
 
u16 hw_handle;
-   struct timer_list timer;
 };
 
 #define DMX_FEED_ENTRY(pos) list_entry(pos, struct dvb_demux_feed, list_head)
-- 
2.13.5

[PATCH v2 31/37] media: dmxdev.h: add kernel-doc markups for data types and functions

[Mauro Carvalho Chehab]

Despite being used by DVB drivers, this header was not documented.

Document it.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-core/dmxdev.h | 90 -
 1 file changed, 88 insertions(+), 2 deletions(-)

diff --git a/drivers/media/dvb-core/dmxdev.h b/drivers/media/dvb-core/dmxdev.h
index 054fd4eb6192..9aa3ce3fc407 100644
--- a/drivers/media/dvb-core/dmxdev.h
+++ b/drivers/media/dvb-core/dmxdev.h
@@ -36,12 +36,33 @@
 #include "demux.h"
 #include "dvb_ringbuffer.h"
 
+/**
+ * enum dmxdev_type - type of demux filter type.
+ *
+ * @DMXDEV_TYPE_NONE:  no filter set.
+ * @DMXDEV_TYPE_SEC:   section filter.
+ * @DMXDEV_TYPE_PES:   Program Elementary Stream (PES) filter.
+ */
 enum dmxdev_type {
DMXDEV_TYPE_NONE,
DMXDEV_TYPE_SEC,
DMXDEV_TYPE_PES,
 };
 
+/**
+ * enum dmxdev_state - state machine for the dmxdev.
+ *
+ * @DMXDEV_STATE_FREE: indicates that the filter is freed.
+ * @DMXDEV_STATE_ALLOCATED:indicates that the filter was allocated
+ * to be used.
+ * @DMXDEV_STATE_SET:  indicates that the filter parameters are set.
+ * @DMXDEV_STATE_GO:   indicates that the filter is running.
+ * @DMXDEV_STATE_DONE: indicates that a packet was already filtered
+ * and the filter is now disabled.
+ * Set only if %DMX_ONESHOT. See
+ * _sct_filter_params.
+ * @DMXDEV_STATE_TIMEDOUT: Indicates a timeout condition.
+ */
 enum dmxdev_state {
DMXDEV_STATE_FREE,
DMXDEV_STATE_ALLOCATED,
@@ -51,12 +72,49 @@ enum dmxdev_state {
DMXDEV_STATE_TIMEDOUT
 };
 
+/**
+ * struct dmxdev_feed - digital TV dmxdev feed
+ *
+ * @pid:   Program ID to be filtered
+ * @ts:pointer to  dmx_ts_feed
+ * @next:   list_head pointing to the next feed.
+ */
+
 struct dmxdev_feed {
u16 pid;
struct dmx_ts_feed *ts;
struct list_head next;
 };
 
+/**
+ * struct dmxdev_filter - digital TV dmxdev filter
+ *
+ * @filter:a dmxdev filter. Currently used only for section filter:
+ * if the filter is Section, it contains a
+ *  dmx_section_filter @sec pointer.
+ * @feed:  a dmxdev feed. Depending on the feed type, it can be:
+ * for TS feed: a  list_head @ts list of TS and PES
+ * feeds;
+ * for section feed: a  dmx_section_feed @sec pointer.
+ * @params:dmxdev filter parameters. Depending on the feed type, it
+ * can be:
+ * for section filter: a  dmx_sct_filter_params @sec
+ * embedded struct;
+ * for a TS filter: a  dmx_pes_filter_params @pes
+ * embedded struct.
+ * @type:  type of the dmxdev filter, as defined by  dmxdev_type.
+ * @state: state of the dmxdev filter, as defined by  dmxdev_state.
+ * @dev:   pointer to  dmxdev.
+ * @buffer:an embedded  dvb_ringbuffer buffer.
+ * @mutex: protects the access to  dmxdev_filter.
+ * @timer:  timer_list embedded timer, used to check for
+ * feed timeouts.
+ * Only for section filter.
+ * @todo:  index for the @secheader.
+ * Only for section filter.
+ * @secheader: buffer cache to parse the section header.
+ * Only for section filter.
+ */
 struct dmxdev_filter {
union {
struct dmx_section_filter *sec;
@@ -86,7 +144,23 @@ struct dmxdev_filter {
u8 secheader[3];
 };
 
-
+/**
+ * struct dmxdev - Describes a digital TV demux device.
+ *
+ * @dvbdev:pointer to  dvb_device associated with
+ * the demux device node.
+ * @dvr_dvbdev:pointer to  dvb_device associated with
+ * the dvr device node.
+ * @filter:pointer to  dmxdev_filter.
+ * @demux: pointer to  dmx_demux.
+ * @filternum: number of filters.
+ * @capabilities:  demux capabilities as defined by  dmx_demux_caps.
+ * @exit:  flag to indicate that the demux is being released.
+ * @dvr_orig_fe:   pointer to  dmx_frontend.
+ * @dvr_buffer:embedded  dvb_ringbuffer for DVB output.
+ * @mutex: protects the usage of this structure.
+ * @lock:  protects access to >filter->data.
+ */
 struct dmxdev {
struct dvb_device *dvbdev;
struct dvb_device *dvr_dvbdev;
@@ -108,8 +182,20 @@ struct dmxdev {
spinlock_t lock;
 };
 
+/**
+ * dvb_dmxdev_init - initializes a digital TV demux and registers both demux
+ * and DVR devices.
+ *
+ * @dmxdev: pointer to  dmxdev.
+ * @adap: pointer to  dvb_adapter.
+ */
+int dvb_dmxdev_init(struct dmxdev *dmxdev, struct dvb_adapter *adap);
 
-int dvb_dmxdev_init(struct dmxdev *dmxdev, struct dvb_adapter *);
+/**
+ * dvb_dmxdev_release - releases a digital TV demux and unregisters it.
+ *
+ * @dmxdev: pointer to  

[PATCH v2 06/37] media: dvb_frontend: get rid of set_property() callback

[Mauro Carvalho Chehab]

Now that all clients of set_property() were removed, get rid
of this callback.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-core/dvb_frontend.c | 7 ---
 drivers/media/dvb-core/dvb_frontend.h | 5 -
 2 files changed, 12 deletions(-)

diff --git a/drivers/media/dvb-core/dvb_frontend.c 
b/drivers/media/dvb-core/dvb_frontend.c
index 5d00e46d9432..8abe4f541a36 100644
--- a/drivers/media/dvb-core/dvb_frontend.c
+++ b/drivers/media/dvb-core/dvb_frontend.c
@@ -1766,13 +1766,6 @@ static int dtv_property_process_set(struct dvb_frontend 
*fe,
int r = 0;
struct dtv_frontend_properties *c = >dtv_property_cache;
 
-   /* Allow the frontend to validate incoming properties */
-   if (fe->ops.set_property) {
-   r = fe->ops.set_property(fe, tvp);
-   if (r < 0)
-   return r;
-   }
-
dtv_property_dump(fe, true, tvp);
 
switch(tvp->cmd) {
diff --git a/drivers/media/dvb-core/dvb_frontend.h 
b/drivers/media/dvb-core/dvb_frontend.h
index 4d05846f2c1c..852b91ba49d2 100644
--- a/drivers/media/dvb-core/dvb_frontend.h
+++ b/drivers/media/dvb-core/dvb_frontend.h
@@ -401,11 +401,8 @@ struct dtv_frontend_properties;
  * @search:callback function used on some custom algo search algos.
  * @tuner_ops: pointer to struct dvb_tuner_ops
  * @analog_ops:pointer to struct analog_demod_ops
- * @set_property:  callback function to allow the frontend to validade
- * incoming properties. Should not be used on new drivers.
  */
 struct dvb_frontend_ops {
-
struct dvb_frontend_info info;
 
u8 delsys[MAX_DELSYS];
@@ -464,8 +461,6 @@ struct dvb_frontend_ops {
 
struct dvb_tuner_ops tuner_ops;
struct analog_demod_ops analog_ops;
-
-   int (*set_property)(struct dvb_frontend* fe, struct dtv_property* tvp);
 };
 
 #ifdef __DVB_CORE__
-- 
2.13.5

[PATCH v2 28/37] media: dvb_frontend: get rid of dtv_get_property_dump()

[Mauro Carvalho Chehab]

Simplify the get property handling and move it to the existing
code at dtv_property_process_get() directly.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-core/dvb_frontend.c | 43 ++-
 1 file changed, 12 insertions(+), 31 deletions(-)

diff --git a/drivers/media/dvb-core/dvb_frontend.c 
b/drivers/media/dvb-core/dvb_frontend.c
index 717b84e50a4a..5f69b2ba1173 100644
--- a/drivers/media/dvb-core/dvb_frontend.c
+++ b/drivers/media/dvb-core/dvb_frontend.c
@@ -1107,36 +1107,6 @@ static struct dtv_cmds_h dtv_cmds[DTV_MAX_COMMAND + 1] = 
{
_DTV_CMD(DTV_STAT_TOTAL_BLOCK_COUNT, 0, 0),
 };
 
-static void dtv_get_property_dump(struct dvb_frontend *fe,
- struct dtv_property *tvp)
-{
-   int i;
-
-   if (tvp->cmd <= 0 || tvp->cmd > DTV_MAX_COMMAND) {
-   dev_warn(fe->dvb->device, "%s: GET tvp.cmd = 0x%08x undefined\n"
-   , __func__,
-   tvp->cmd);
-   return;
-   }
-
-   dev_dbg(fe->dvb->device, "%s: GET tvp.cmd= 0x%08x (%s)\n", __func__,
-   tvp->cmd,
-   dtv_cmds[tvp->cmd].name);
-
-   if (dtv_cmds[tvp->cmd].buffer) {
-   dev_dbg(fe->dvb->device, "%s: tvp.u.buffer.len = 0x%02x\n",
-   __func__, tvp->u.buffer.len);
-
-   for(i = 0; i < tvp->u.buffer.len; i++)
-   dev_dbg(fe->dvb->device,
-   "%s: tvp.u.buffer.data[0x%02x] = 
0x%02x\n",
-   __func__, i, tvp->u.buffer.data[i]);
-   } else {
-   dev_dbg(fe->dvb->device, "%s: tvp.u.data = 0x%08x\n", __func__,
-   tvp->u.data);
-   }
-}
-
 /* Synchronise the legacy tuning parameters into the cache, so that demodulator
  * drivers can use a single set_frontend tuning function, regardless of whether
  * it's being used for the legacy or new API, reducing code and complexity.
@@ -1529,7 +1499,18 @@ static int dtv_property_process_get(struct dvb_frontend 
*fe,
return -EINVAL;
}
 
-   dtv_get_property_dump(fe, tvp);
+   if (!dtv_cmds[tvp->cmd].buffer)
+   dev_dbg(fe->dvb->device,
+   "%s: GET cmd 0x%08x (%s) = 0x%08x\n",
+   __func__, tvp->cmd, dtv_cmds[tvp->cmd].name,
+   tvp->u.data);
+   else
+   dev_dbg(fe->dvb->device,
+   "%s: GET cmd 0x%08x (%s) len %d: %*ph\n",
+   __func__,
+   tvp->cmd, dtv_cmds[tvp->cmd].name,
+   tvp->u.buffer.len,
+   tvp->u.buffer.len, tvp->u.buffer.data);
 
return 0;
 }
-- 
2.13.5

[PATCH v2 20/37] media: dvb_demux.h: add an enum for DMX_STATE_* and document

[Mauro Carvalho Chehab]

kernel-doc allows documenting enums. Also, it makes clearer
about the meaning of each field on structures.

So, convert DMX_STATE_* to an enum.

While here, get rid of the unused DMX_STATE_SET.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-core/dvb_demux.h | 25 ++---
 1 file changed, 18 insertions(+), 7 deletions(-)

diff --git a/drivers/media/dvb-core/dvb_demux.h 
b/drivers/media/dvb-core/dvb_demux.h
index 6bc4b27dbff3..b24d69b5a20f 100644
--- a/drivers/media/dvb-core/dvb_demux.h
+++ b/drivers/media/dvb-core/dvb_demux.h
@@ -37,11 +37,22 @@ enum dvb_dmx_filter_type {
DMX_TYPE_SEC,
 };
 
-#define DMX_STATE_FREE  0
-#define DMX_STATE_ALLOCATED 1
-#define DMX_STATE_SET   2
-#define DMX_STATE_READY 3
-#define DMX_STATE_GO4
+/**
+ * enum dvb_dmx_state - state machine for a demux filter.
+ *
+ * @DMX_STATE_FREE:indicates that the filter is freed.
+ * @DMX_STATE_ALLOCATED:   indicates that the filter was allocated
+ * to be used.
+ * @DMX_STATE_READY:   indicates that the filter is ready
+ * to be used.
+ * @DMX_STATE_GO:  indicates that the filter is running.
+ */
+enum dvb_dmx_state {
+   DMX_STATE_FREE,
+   DMX_STATE_ALLOCATED,
+   DMX_STATE_READY,
+   DMX_STATE_GO,
+};
 
 #define DVB_DEMUX_MASK_MAX 18
 
@@ -58,7 +69,7 @@ struct dvb_demux_filter {
struct dvb_demux_filter *next;
struct dvb_demux_feed *feed;
int index;
-   int state;
+   enum dvb_dmx_state state;
enum dvb_dmx_filter_type type;
 
u16 hw_handle;
@@ -81,7 +92,7 @@ struct dvb_demux_feed {
struct dvb_demux *demux;
void *priv;
enum dvb_dmx_filter_type type;
-   int state;
+   enum dvb_dmx_state state;
u16 pid;
 
ktime_t timeout;
-- 
2.13.5

[PATCH v2 04/37] media: friio-fe: get rid of set_property()

[Mauro Carvalho Chehab]

This callback is not actually doing anything but making it to
return an error depending on the DTV frontend command. Well,
that could break userspace for no good reason, and, if needed,
should be implemented, instead, at set_frontend() callback.

So, get rid of it.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/usb/dvb-usb/friio-fe.c | 24 
 1 file changed, 24 deletions(-)

diff --git a/drivers/media/usb/dvb-usb/friio-fe.c 
b/drivers/media/usb/dvb-usb/friio-fe.c
index 0251a4e91d47..41261317bd5c 100644
--- a/drivers/media/usb/dvb-usb/friio-fe.c
+++ b/drivers/media/usb/dvb-usb/friio-fe.c
@@ -261,28 +261,6 @@ static int jdvbt90502_read_signal_strength(struct 
dvb_frontend *fe,
return 0;
 }
 
-
-/* filter out un-supported properties to notify users */
-static int jdvbt90502_set_property(struct dvb_frontend *fe,
-  struct dtv_property *tvp)
-{
-   int r = 0;
-
-   switch (tvp->cmd) {
-   case DTV_DELIVERY_SYSTEM:
-   if (tvp->u.data != SYS_ISDBT)
-   r = -EINVAL;
-   break;
-   case DTV_CLEAR:
-   case DTV_TUNE:
-   case DTV_FREQUENCY:
-   break;
-   default:
-   r = -EINVAL;
-   }
-   return r;
-}
-
 static int jdvbt90502_set_frontend(struct dvb_frontend *fe)
 {
struct dtv_frontend_properties *p = >dtv_property_cache;
@@ -457,8 +435,6 @@ static const struct dvb_frontend_ops jdvbt90502_ops = {
.init = jdvbt90502_init,
.write = _jdvbt90502_write,
 
-   .set_property = jdvbt90502_set_property,
-
.set_frontend = jdvbt90502_set_frontend,
 
.read_status = jdvbt90502_read_status,
-- 
2.13.5

[PATCH v2 24/37] media: dvb_demux.h: get rid of DMX_FEED_ENTRY() macro

[Mauro Carvalho Chehab]

This isn't used anywere. Get rid of it.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-core/dvb_demux.h | 2 --
 1 file changed, 2 deletions(-)

diff --git a/drivers/media/dvb-core/dvb_demux.h 
b/drivers/media/dvb-core/dvb_demux.h
index 9db3c2b7c64e..d9b30d669bf3 100644
--- a/drivers/media/dvb-core/dvb_demux.h
+++ b/drivers/media/dvb-core/dvb_demux.h
@@ -75,8 +75,6 @@ struct dvb_demux_filter {
u16 hw_handle;
 };
 
-#define DMX_FEED_ENTRY(pos) list_entry(pos, struct dvb_demux_feed, list_head)
-
 struct dvb_demux_feed {
union {
struct dmx_ts_feed ts;
-- 
2.13.5

[PATCH v2 19/37] media: dvb_demux.h: add an enum for DMX_TYPE_* and document

[Mauro Carvalho Chehab]

kernel-doc allows documenting enums. Also, it makes clearer
about the meaning of each field on structures.

So, convert DMX_TYPE_* to an enum.

While here, get rid of the unused DMX_TYPE_PES.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-core/dvb_demux.h | 17 -
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/drivers/media/dvb-core/dvb_demux.h 
b/drivers/media/dvb-core/dvb_demux.h
index 6f572ca8d339..6bc4b27dbff3 100644
--- a/drivers/media/dvb-core/dvb_demux.h
+++ b/drivers/media/dvb-core/dvb_demux.h
@@ -26,9 +26,16 @@
 
 #include "demux.h"
 
-#define DMX_TYPE_TS  0
-#define DMX_TYPE_SEC 1
-#define DMX_TYPE_PES 2
+/**
+ * enum dvb_dmx_filter_type - type of demux feed.
+ *
+ * @DMX_TYPE_TS:   feed is in TS mode.
+ * @DMX_TYPE_SEC:  feed is in Section mode.
+ */
+enum dvb_dmx_filter_type {
+   DMX_TYPE_TS,
+   DMX_TYPE_SEC,
+};
 
 #define DMX_STATE_FREE  0
 #define DMX_STATE_ALLOCATED 1
@@ -52,7 +59,7 @@ struct dvb_demux_filter {
struct dvb_demux_feed *feed;
int index;
int state;
-   int type;
+   enum dvb_dmx_filter_type type;
 
u16 hw_handle;
struct timer_list timer;
@@ -73,7 +80,7 @@ struct dvb_demux_feed {
 
struct dvb_demux *demux;
void *priv;
-   int type;
+   enum dvb_dmx_filter_type type;
int state;
u16 pid;
 
-- 
2.13.5

[PATCH v2 32/37] media: dtv-demux.rst: parse other demux headers with kernel-doc

[Mauro Carvalho Chehab]

Now that we have kernel-doc markups at dvb_demux.h and dmxdev.h,
parse them.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/media/kapi/dtv-demux.rst | 14 --
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/Documentation/media/kapi/dtv-demux.rst 
b/Documentation/media/kapi/dtv-demux.rst
index 3ee69266e206..7aa865a2b43f 100644
--- a/Documentation/media/kapi/dtv-demux.rst
+++ b/Documentation/media/kapi/dtv-demux.rst
@@ -66,7 +66,17 @@ function call directly from a hardware interrupt.
 This mechanism is implemented by :c:func:`dmx_ts_cb()` and 
:c:func:`dmx_section_cb()`
 callbacks.
 
-Digital TV Demux functions and types
-
+Digital TV Demux device registration functions and data structures
+~~
+
+.. kernel-doc:: drivers/media/dvb-core/dmxdev.h
+
+High-level Digital TV demux interface
+~
+
+.. kernel-doc:: drivers/media/dvb-core/dvb_demux.h
+
+Driver-internal low-level hardware specific driver demux interface
+~~
 
 .. kernel-doc:: drivers/media/dvb-core/demux.h
-- 
2.13.5

[PATCH v2 11/37] media: dvb_frontend: better document the -EPERM condition

[Mauro Carvalho Chehab]

Two readonly ioctls can't be allowed if the frontend device
is opened in read only mode. Explain why.

Reviewed by: Shuah Khan 
Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-core/dvb_frontend.c | 20 +---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/drivers/media/dvb-core/dvb_frontend.c 
b/drivers/media/dvb-core/dvb_frontend.c
index 01bd19fd4c57..2036cf1b7784 100644
--- a/drivers/media/dvb-core/dvb_frontend.c
+++ b/drivers/media/dvb-core/dvb_frontend.c
@@ -1940,9 +1940,23 @@ static int dvb_frontend_ioctl(struct file *file, 
unsigned int cmd, void *parg)
return -ENODEV;
}
 
-   if ((file->f_flags & O_ACCMODE) == O_RDONLY &&
-   (_IOC_DIR(cmd) != _IOC_READ || cmd == FE_GET_EVENT ||
-cmd == FE_DISEQC_RECV_SLAVE_REPLY)) {
+   /*
+* If the frontend is opened in read-only mode, only the ioctls
+* that don't interfere with the tune logic should be accepted.
+* That allows an external application to monitor the DVB QoS and
+* statistics parameters.
+*
+* That matches all _IOR() ioctls, except for two special cases:
+*   - FE_GET_EVENT is part of the tuning logic on a DVB application;
+*   - FE_DISEQC_RECV_SLAVE_REPLY is part of DiSEqC 2.0
+* setup
+* So, those two ioctls should also return -EPERM, as otherwise
+* reading from them would interfere with a DVB tune application
+*/
+   if ((file->f_flags & O_ACCMODE) == O_RDONLY
+   && (_IOC_DIR(cmd) != _IOC_READ
+   || cmd == FE_GET_EVENT
+   || cmd == FE_DISEQC_RECV_SLAVE_REPLY)) {
up(>sem);
return -EPERM;
}
-- 
2.13.5

[PATCH v2 33/37] media: dvb-net.rst: document DVB network kAPI interface

[Mauro Carvalho Chehab]

That's the last DVB kAPI that misses documentation.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/media/kapi/dtv-core.rst  |  1 +
 Documentation/media/kapi/dtv-net.rst   |  4 
 Documentation/media/uapi/dvb/net-types.rst |  2 +-
 drivers/media/dvb-core/dvb_net.h   | 34 --
 4 files changed, 38 insertions(+), 3 deletions(-)
 create mode 100644 Documentation/media/kapi/dtv-net.rst

diff --git a/Documentation/media/kapi/dtv-core.rst 
b/Documentation/media/kapi/dtv-core.rst
index 8ee384f61fa0..bca743dc6b43 100644
--- a/Documentation/media/kapi/dtv-core.rst
+++ b/Documentation/media/kapi/dtv-core.rst
@@ -34,3 +34,4 @@ I2C bus.
 dtv-frontend
 dtv-demux
 dtv-ca
+dtv-net
diff --git a/Documentation/media/kapi/dtv-net.rst 
b/Documentation/media/kapi/dtv-net.rst
new file mode 100644
index ..ced991b73d69
--- /dev/null
+++ b/Documentation/media/kapi/dtv-net.rst
@@ -0,0 +1,4 @@
+Digital TV Network kABI
+---
+
+.. kernel-doc:: drivers/media/dvb-core/dvb_net.h
diff --git a/Documentation/media/uapi/dvb/net-types.rst 
b/Documentation/media/uapi/dvb/net-types.rst
index e1177bdcd623..8fa3292eaa42 100644
--- a/Documentation/media/uapi/dvb/net-types.rst
+++ b/Documentation/media/uapi/dvb/net-types.rst
@@ -1,6 +1,6 @@
 .. -*- coding: utf-8; mode: rst -*-
 
-.. _dmx_types:
+.. _net_types:
 
 **
 Net Data Types
diff --git a/drivers/media/dvb-core/dvb_net.h b/drivers/media/dvb-core/dvb_net.h
index e9b18aa03e02..1eae8bad7cc1 100644
--- a/drivers/media/dvb-core/dvb_net.h
+++ b/drivers/media/dvb-core/dvb_net.h
@@ -30,6 +30,22 @@
 
 #ifdef CONFIG_DVB_NET
 
+/**
+ * struct dvb_net - describes a DVB network interface
+ *
+ * @dvbdev:pointer to  dvb_device.
+ * @device:array of pointers to  net_device.
+ * @state: array of integers to each net device. A value
+ * different than zero means that the interface is
+ * in usage.
+ * @exit:  flag to indicate when the device is being removed.
+ * @demux: pointer to  dmx_demux.
+ * @ioctl_mutex:   protect access to this struct.
+ *
+ * Currently, the core supports up to %DVB_NET_DEVICES_MAX (10) network
+ * devices.
+ */
+
 struct dvb_net {
struct dvb_device *dvbdev;
struct net_device *device[DVB_NET_DEVICES_MAX];
@@ -39,8 +55,22 @@ struct dvb_net {
struct mutex ioctl_mutex;
 };
 
-void dvb_net_release(struct dvb_net *);
-int  dvb_net_init(struct dvb_adapter *, struct dvb_net *, struct dmx_demux *);
+/**
+ * dvb_net_init - nitializes a digital TV network device and registers it.
+ *
+ * @adap:  pointer to  dvb_adapter.
+ * @dvbnet:pointer to  dvb_net.
+ * @dmxdemux:  pointer to  dmx_demux.
+ */
+int dvb_net_init(struct dvb_adapter *adap, struct dvb_net *dvbnet,
+ struct dmx_demux *dmxdemux);
+
+/**
+ * dvb_net_release - releases a digital TV network device and unregisters it.
+ *
+ * @dvbnet:pointer to  dvb_net.
+ */
+void dvb_net_release(struct dvb_net *dvbnet);
 
 #else
 
-- 
2.13.5

[PATCH v2 02/37] media: stv0288: get rid of set_property boilerplate

[Mauro Carvalho Chehab]

This driver doesn't implement support for set_property(). Yet,
it implements a boilerplate for it. Get rid of it.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-frontends/stv0288.c | 7 ---
 1 file changed, 7 deletions(-)

diff --git a/drivers/media/dvb-frontends/stv0288.c 
b/drivers/media/dvb-frontends/stv0288.c
index 45cbc898ad25..67f91814b9f7 100644
--- a/drivers/media/dvb-frontends/stv0288.c
+++ b/drivers/media/dvb-frontends/stv0288.c
@@ -447,12 +447,6 @@ static int stv0288_read_ucblocks(struct dvb_frontend *fe, 
u32 *ucblocks)
return 0;
 }
 
-static int stv0288_set_property(struct dvb_frontend *fe, struct dtv_property 
*p)
-{
-   dprintk("%s(..)\n", __func__);
-   return 0;
-}
-
 static int stv0288_set_frontend(struct dvb_frontend *fe)
 {
struct stv0288_state *state = fe->demodulator_priv;
@@ -567,7 +561,6 @@ static const struct dvb_frontend_ops stv0288_ops = {
.set_tone = stv0288_set_tone,
.set_voltage = stv0288_set_voltage,
 
-   .set_property = stv0288_set_property,
.set_frontend = stv0288_set_frontend,
 };
 
-- 
2.13.5

[PATCH v2 36/37] media: dvb_demux: use the newly nested kernel-doc support

[Mauro Carvalho Chehab]

Now that kernel-doc supports nested structs/unions, use it.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-core/dvb_demux.h | 23 ++-
 1 file changed, 14 insertions(+), 9 deletions(-)

diff --git a/drivers/media/dvb-core/dvb_demux.h 
b/drivers/media/dvb-core/dvb_demux.h
index 15ee2ea23efe..97bf5ee7ef57 100644
--- a/drivers/media/dvb-core/dvb_demux.h
+++ b/drivers/media/dvb-core/dvb_demux.h
@@ -94,15 +94,20 @@ struct dvb_demux_filter {
 /**
  * struct dvb_demux_feed - describes a DVB field
  *
- * @feed:  a digital TV feed. It can either be a TS or a section feed:
- * if the feed is TS, it contains  dvb_ts_feed @ts;
- * if the feed is section, it contains
- *  dmx_section_feed @sec.
- * @cb:digital TV callbacks. depending on the feed type, it 
can be:
- * if the feed is TS, it contains a dmx_ts_cb() @ts callback;
- * if the feed is section, it contains a dmx_section_cb() @sec
- * callback.
- *
+ * @feed:  a union describing a digital TV feed.
+ * Depending on the feed type, it can be either
+ * @feed.ts or @feed.sec.
+ * @feed.ts:   a  dmx_ts_feed pointer.
+ * For TS feed only.
+ * @feed.sec:  a  dmx_section_feed pointer.
+ * For section feed only.
+ * @cb:a union describing digital TV callbacks.
+ * Depending on the feed type, it can be either
+ * @cb.ts or @cb.sec.
+ * @cb.ts: a dmx_ts_cb() calback function pointer.
+ * For TS feed only.
+ * @cb.sec:a dmx_section_cb() callback function pointer.
+ * For section feed only.
  * @demux: pointer to  dvb_demux.
  * @priv:  private data that can optionally be used by a DVB driver.
  * @type:  type of the filter, as defined by  dvb_dmx_filter_type.
-- 
2.13.5

[PATCH v2 00/37] DVB cleanups and documentation improvements

[Mauro Carvalho Chehab]

This patch series merges a 6 patches series I sent earlier, and a 25 patch
series.

It comes after the patch series with add support for nexted structs/enums
on kernel-doc.

I"m pushing it on my experimental tree:

https://git.linuxtv.org/mchehab/experimental.git/log/?h=dvb-fixes-v5

It is mainly focused on improving the DVB kAPI documentation, making
it (finally!) in sync with the current implementation. It also contains
a patch getting rid of the legacy (non-working) uAPI examples.

While reviewing the code implementation, I noticed some struct fields
that aren't used at all by any DVB driver or core. So, the series gets
rid of them. Others are used only on av7110, and are documented as
such.

After this patch series, both DVB uAPI and kAPI are fully documented
(except for the legacy video/audio/osd uAPI, that doesn't have any
kAPI associated to them).

Granted, some things could be improved at the documentation, but at
least it doesn't carry anymore any big gap or conflict!

Please review and test.

---

v2:

  - merged with a previous 6 patch series;
  - added patches at the end adding support for nexted structs/enums.


Mauro Carvalho Chehab (36):
  media: dvb_frontend: only use kref after initialized
  media: stv0288: get rid of set_property boilerplate
  media: stv6110: get rid of a srate dead code
  media: friio-fe: get rid of set_property()
  media: dvb_frontend: get rid of get_property() callback
  media: dvb_frontend: get rid of set_property() callback
  media: dvb_frontend: cleanup dvb_frontend_ioctl_properties()
  media: dvb_frontend: cleanup ioctl handling logic
  media: dvb_frontend: get rid of property cache's state
  media: dvb_frontend.h: fix alignment at the cache properties
  media: dvb_frontend: better document the -EPERM condition
  media: dvb_frontend: fix return values for FE_SET_PROPERTY
  media: dvbdev: convert DVB device types into an enum
  media: dvbdev: fully document its functions
  media: dvb_frontend.h: improve kernel-doc markups
  media: dtv-core.rst: add chapters and introductory tests for common
parts
  media: dtv-core.rst: split into multiple files
  media: dtv-demux.rst: minor markup improvements
  media: dvb_demux.h: add an enum for DMX_TYPE_* and document
  media: dvb_demux.h: add an enum for DMX_STATE_* and document
  media: dvb_demux.h: get rid of unused timer at struct dvb_demux_filter
  media: dvb_demux: mark a boolean field as such
  media: dvb_demux: dvb_demux_feed.pusi_seen is boolean
  media: dvb_demux.h: get rid of DMX_FEED_ENTRY() macro
  media: dvb_demux: fix type of dvb_demux_feed.ts_type
  media: dvb_demux: document dvb_demux_filter and dvb_demux_feed
  media: dvb_frontend: get rid of dtv_get_property_dump()
  media: dvb_demux.h: document structs defined on it
  media: dvb_demux.h: document functions
  media: dmxdev.h: add kernel-doc markups for data types and functions
  media: dtv-demux.rst: parse other demux headers with kernel-doc
  media: dvb-net.rst: document DVB network kAPI interface
  media: dvb uAPI docs: get rid of examples section
  media: dmxdev: use the newly nested kernel-doc support
  media: dvb_demux: use the newly nested kernel-doc support
  media: frontend: use the newly nested kernel-doc support

Satendra Singh Thakur (1):
  media: dvb_frontend: dtv_property_process_set() cleanups

 Documentation/media/kapi/dtv-ca.rst  |   4 +
 Documentation/media/kapi/dtv-common.rst  |  55 +++
 Documentation/media/kapi/dtv-core.rst| 574 +--
 Documentation/media/kapi/dtv-demux.rst   |  82 
 Documentation/media/kapi/dtv-frontend.rst| 443 +
 Documentation/media/kapi/dtv-net.rst |   4 +
 Documentation/media/uapi/dvb/examples.rst| 378 +--
 Documentation/media/uapi/dvb/fe-get-property.rst |   7 +-
 Documentation/media/uapi/dvb/net-types.rst   |   2 +-
 drivers/media/dvb-core/dmxdev.h  |  95 +++-
 drivers/media/dvb-core/dvb_demux.c   |  17 +-
 drivers/media/dvb-core/dvb_demux.h   | 253 +-
 drivers/media/dvb-core/dvb_frontend.c| 534 +++--
 drivers/media/dvb-core/dvb_frontend.h| 117 ++---
 drivers/media/dvb-core/dvb_net.h |  34 +-
 drivers/media/dvb-core/dvbdev.c  |  34 +-
 drivers/media/dvb-core/dvbdev.h  | 137 +-
 drivers/media/dvb-frontends/lg2160.c |  14 -
 drivers/media/dvb-frontends/stv0288.c|   7 -
 drivers/media/dvb-frontends/stv6110.c|   9 -
 drivers/media/pci/ttpci/av7110.c |   2 +-
 drivers/media/pci/ttpci/budget-core.c|   2 +-
 drivers/media/usb/dvb-usb/friio-fe.c |  24 -
 include/uapi/linux/dvb/frontend.h|  35 +-
 24 files changed, 1457 insertions(+), 1406 deletions(-)
 create mode 100644 Documentation/media/kapi/dtv-ca.rst
 create mode 100644 Documentation/media/kapi/dtv-common.rst
 

[PATCH v2 37/37] media: frontend: use the newly nested kernel-doc support

[Mauro Carvalho Chehab]

Now that kernel-doc supports nested structs/unions, use it.

Signed-off-by: Mauro Carvalho Chehab 
---
 include/uapi/linux/dvb/frontend.h | 35 +--
 1 file changed, 17 insertions(+), 18 deletions(-)

diff --git a/include/uapi/linux/dvb/frontend.h 
b/include/uapi/linux/dvb/frontend.h
index 6bc26f35217b..44b90a0a0079 100644
--- a/include/uapi/linux/dvb/frontend.h
+++ b/include/uapi/linux/dvb/frontend.h
@@ -755,16 +755,15 @@ enum fecap_scale_params {
 /**
  * struct dtv_stats - Used for reading a DTV status property
  *
- * @scale: Filled with enum fecap_scale_params - the scale
- * in usage for that parameter
+ * @scale:
+ * Filled with enum fecap_scale_params - the scale in usage
+ * for that parameter
  *
- * The ``{unnamed_union}`` may have either one of the values below:
- *
- * %svalue
+ * @svalue:
  * integer value of the measure, for %FE_SCALE_DECIBEL,
  * used for dB measures. The unit is 0.001 dB.
  *
- * %uvalue
+ * @uvalue:
  * unsigned integer value of the measure, used when @scale is
  * either %FE_SCALE_RELATIVE or %FE_SCALE_COUNTER.
  *
@@ -827,19 +826,19 @@ struct dtv_fe_stats {
 /**
  * struct dtv_property - store one of frontend command and its value
  *
- * @cmd:   Digital TV command.
- * @reserved:  Not used.
- * @u: Union with the values for the command.
- * @result:Unused
+ * @cmd:   Digital TV command.
+ * @reserved:  Not used.
+ * @u: Union with the values for the command.
+ * @u.data:A unsigned 32 bits integer with command value.
+ * @u.buffer:  Struct to store bigger properties.
+ * Currently unused.
+ * @u.buffer.data: an unsigned 32-bits array.
+ * @u.buffer.len:  number of elements of the buffer.
+ * @u.buffer.reserved1:Reserved.
+ * @u.buffer.reserved2:Reserved.
+ * @u.st:  a  dtv_fe_stats array of statistics.
+ * @result:Currently unused.
  *
- * The @u union may have either one of the values below:
- *
- * %data
- * an unsigned 32-bits number.
- * %st
- * a  dtv_fe_stats array of statistics.
- * %buffer
- * a buffer of up to 32 characters (currently unused).
  */
 struct dtv_property {
__u32 cmd;
-- 
2.13.5

[PATCH v2 10/37] media: dvb_frontend.h: fix alignment at the cache properties

[Mauro Carvalho Chehab]

There are too much tabs on several properties, for no good
reason. That sounds confusing while reading the struct, so
adjust them.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-core/dvb_frontend.h | 10 +-
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/drivers/media/dvb-core/dvb_frontend.h 
b/drivers/media/dvb-core/dvb_frontend.h
index 1bdeb10f0d78..d273ed2f72c9 100644
--- a/drivers/media/dvb-core/dvb_frontend.h
+++ b/drivers/media/dvb-core/dvb_frontend.h
@@ -557,15 +557,15 @@ struct dtv_frontend_properties {
 
enum fe_sec_voltage voltage;
enum fe_sec_tone_mode   sectone;
-   enum fe_spectral_inversion  inversion;
-   enum fe_code_rate   fec_inner;
+   enum fe_spectral_inversion inversion;
+   enum fe_code_rate   fec_inner;
enum fe_transmit_mode   transmission_mode;
u32 bandwidth_hz;   /* 0 = AUTO */
enum fe_guard_interval  guard_interval;
-   enum fe_hierarchy   hierarchy;
+   enum fe_hierarchy   hierarchy;
u32 symbol_rate;
-   enum fe_code_rate   code_rate_HP;
-   enum fe_code_rate   code_rate_LP;
+   enum fe_code_rate   code_rate_HP;
+   enum fe_code_rate   code_rate_LP;
 
enum fe_pilot   pilot;
enum fe_rolloff rolloff;
-- 
2.13.5

[PATCH v2 35/37] media: dmxdev: use the newly nested kernel-doc support

[Mauro Carvalho Chehab]

Now that kernel-doc supports nested structs/unions, use it.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-core/dmxdev.h | 31 ++-
 1 file changed, 18 insertions(+), 13 deletions(-)

diff --git a/drivers/media/dvb-core/dmxdev.h b/drivers/media/dvb-core/dmxdev.h
index 9aa3ce3fc407..2ef0a3b54de6 100644
--- a/drivers/media/dvb-core/dmxdev.h
+++ b/drivers/media/dvb-core/dmxdev.h
@@ -89,19 +89,24 @@ struct dmxdev_feed {
 /**
  * struct dmxdev_filter - digital TV dmxdev filter
  *
- * @filter:a dmxdev filter. Currently used only for section filter:
- * if the filter is Section, it contains a
- *  dmx_section_filter @sec pointer.
- * @feed:  a dmxdev feed. Depending on the feed type, it can be:
- * for TS feed: a  list_head @ts list of TS and PES
- * feeds;
- * for section feed: a  dmx_section_feed @sec pointer.
- * @params:dmxdev filter parameters. Depending on the feed type, it
- * can be:
- * for section filter: a  dmx_sct_filter_params @sec
- * embedded struct;
- * for a TS filter: a  dmx_pes_filter_params @pes
- * embedded struct.
+ * @filter:a union describing a dmxdev filter.
+ * Currently used only for section filters.
+ * @filter.sec: a  dmx_section_filter pointer.
+ * For section filter only.
+ * @feed:  an union describing a dmxdev feed.
+ * Depending on the filter type, it can be either
+ * @feed.ts or @feed.sec.
+ * @feed.ts:   a  list_head list.
+ * For TS and PES feeds.
+ * @feed.sec:  a  dmx_section_feed pointer.
+ * For section feed only.
+ * @params:a union describing dmxdev filter parameters.
+ * Depending on the filter type, it can be either
+ * @params.sec or @params.pes.
+ * @params.sec:a  dmx_sct_filter_params embedded struct.
+ * For section filter only.
+ * @params.pes:a  dmx_pes_filter_params embedded struct.
+ * For PES filter only.
  * @type:  type of the dmxdev filter, as defined by  dmxdev_type.
  * @state: state of the dmxdev filter, as defined by  dmxdev_state.
  * @dev:   pointer to  dmxdev.
-- 
2.13.5

[PATCH v2 16/37] media: dtv-core.rst: add chapters and introductory tests for common parts

[Mauro Carvalho Chehab]

Better document the DVB common parts by adding two sections
and an introductory text for each.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/media/kapi/dtv-core.rst | 12 
 1 file changed, 12 insertions(+)

diff --git a/Documentation/media/kapi/dtv-core.rst 
b/Documentation/media/kapi/dtv-core.rst
index de9a228aca8a..4cf9cf63bafd 100644
--- a/Documentation/media/kapi/dtv-core.rst
+++ b/Documentation/media/kapi/dtv-core.rst
@@ -29,8 +29,20 @@ I2C bus.
 Digital TV Common functions
 ---
 
+Math functions
+~~
+
+Provide some commonly-used math functions, usually required in order to
+estimate signal strength and signal to noise measurements in dB.
+
 .. kernel-doc:: drivers/media/dvb-core/dvb_math.h
 
+
+DVB devices
+~~~
+
+Those functions are responsible for handling the DVB device nodes.
+
 .. kernel-doc:: drivers/media/dvb-core/dvbdev.h
 
 Digital TV Ring buffer
-- 
2.13.5

[PATCH v2 29/37] media: dvb_demux.h: document structs defined on it

[Mauro Carvalho Chehab]

There are three structs defined inside dvb_demux.h. None
of them are currently documented.

Add documentation for them.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-core/dvb_demux.c |  1 +
 drivers/media/dvb-core/dvb_demux.h | 58 --
 2 files changed, 50 insertions(+), 9 deletions(-)

diff --git a/drivers/media/dvb-core/dvb_demux.c 
b/drivers/media/dvb-core/dvb_demux.c
index b9360cbc3519..acade7543b82 100644
--- a/drivers/media/dvb-core/dvb_demux.c
+++ b/drivers/media/dvb-core/dvb_demux.c
@@ -367,6 +367,7 @@ static inline void dvb_dmx_swfilter_packet_type(struct 
dvb_demux_feed *feed,
else
feed->cb.ts(buf, 188, NULL, 0, >feed.ts);
}
+   /* Used only on full-featured devices */
if (feed->ts_type & TS_DECODER)
if (feed->demux->write_to_decoder)
feed->demux->write_to_decoder(feed, buf, 188);
diff --git a/drivers/media/dvb-core/dvb_demux.h 
b/drivers/media/dvb-core/dvb_demux.h
index 5b05e6320e33..43b0cab2e932 100644
--- a/drivers/media/dvb-core/dvb_demux.h
+++ b/drivers/media/dvb-core/dvb_demux.h
@@ -95,15 +95,16 @@ struct dvb_demux_filter {
  * struct dvb_demux_feed - describes a DVB field
  *
  * @feed:  a digital TV feed. It can either be a TS or a section feed:
- *   - if the feed is TS, it contains  dvb_ts_feed;
- *   - if the feed is section, it contains
- *  dmx_section_feed.
+ * if the feed is TS, it contains  dvb_ts_feed @ts;
+ * if the feed is section, it contains
+ *  dmx_section_feed @sec.
  * @cb:digital TV callbacks. depending on the feed type, it 
can be:
- *   - if the feed is TS, it contains a dmx_ts_cb() callback;
- *   - if the feed is section, it contains a dmx_section_cb() 
callback.
+ * if the feed is TS, it contains a dmx_ts_cb() @ts callback;
+ * if the feed is section, it contains a dmx_section_cb() @sec
+ * callback.
  *
  * @demux: pointer to  dvb_demux.
- * @priv:  private data for the filter handling routine.
+ * @priv:  private data that can optionally be used by a DVB driver.
  * @type:  type of the filter, as defined by  dvb_dmx_filter_type.
  * @state: state of the filter as defined by  dvb_dmx_state.
  * @pid:   PID to be filtered.
@@ -118,7 +119,6 @@ struct dvb_demux_filter {
  * @list_head: head for the list of digital TV demux feeds.
  * @index: a unique index for each feed. Can be used as hardware
  * pid filter index.
- *
  */
 struct dvb_demux_feed {
union {
@@ -152,6 +152,44 @@ struct dvb_demux_feed {
unsigned int index;
 };
 
+/**
+ * struct dvb_demux - represents a digital TV demux
+ * @dmx:   embedded  dmx_demux with demux capabilities
+ * and callbacks.
+ * @priv:  private data that can optionally be used by
+ * a DVB driver.
+ * @filternum: maximum amount of DVB filters.
+ * @feednum:   maximum amount of DVB feeds.
+ * @start_feed:callback routine to be called in order to start
+ * a DVB feed.
+ * @stop_feed: callback routine to be called in order to stop
+ * a DVB feed.
+ * @write_to_decoder:  callback routine to be called if the feed is TS and
+ * it is routed to an A/V decoder, when a new TS packet
+ * is received.
+ * Used only on av7110-av.c.
+ * @check_crc32:   callback routine to check CRC. If not initialized,
+ * dvb_demux will use an internal one.
+ * @memcopy:   callback routine to memcopy received data.
+ * If not initialized, dvb_demux will default to memcpy().
+ * @users: counter for the number of demux opened file descriptors.
+ * Currently, it is limited to 10 users.
+ * @filter:pointer to  dvb_demux_filter.
+ * @feed:  pointer to  dvb_demux_feed.
+ * @frontend_list:  list_head with frontends used by the demux.
+ * @pesfilter: array of  dvb_demux_feed with the PES types
+ * that will be filtered.
+ * @pids:  list of filtered program IDs.
+ * @feed_list:  list_head with feeds.
+ * @tsbuf: temporary buffer used internally to store TS packets.
+ * @tsbufp:temporary buffer index used internally.
+ * @mutex: pointer to  mutex used to protect feed set
+ * logic.
+ * @lock:  pointer to _t, used to protect buffer handling.
+ * @cnt_storage:   buffer used for TS/TEI continuity check.
+ * @speed_last_time:   _t used for TS speed check.
+ * @speed_pkts_cnt:packets count used for TS speed 

[PATCH v2 25/37] media: dvb_demux: fix type of dvb_demux_feed.ts_type

[Mauro Carvalho Chehab]

Just like pes_type, this field represents an enum. Properly
identify it as such.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-core/dvb_demux.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/media/dvb-core/dvb_demux.h 
b/drivers/media/dvb-core/dvb_demux.h
index d9b30d669bf3..c9e94bc3a2e5 100644
--- a/drivers/media/dvb-core/dvb_demux.h
+++ b/drivers/media/dvb-core/dvb_demux.h
@@ -95,7 +95,7 @@ struct dvb_demux_feed {
ktime_t timeout;
struct dvb_demux_filter *filter;
 
-   int ts_type;
+   enum ts_filter_type ts_type;
enum dmx_ts_pes pes_type;
 
int cc;
-- 
2.13.5

[PATCH v2 34/37] media: dvb uAPI docs: get rid of examples section

[Mauro Carvalho Chehab]

That section is too outdated and got superseded by DVBv5 and
by libdvbv5.

Maybe some day we'll end adding updated examples there, but
while nobody has time or interest of doing that, just mention
that there and get rid of the current examples for good.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/media/uapi/dvb/examples.rst | 378 +-
 1 file changed, 6 insertions(+), 372 deletions(-)

diff --git a/Documentation/media/uapi/dvb/examples.rst 
b/Documentation/media/uapi/dvb/examples.rst
index e0f627ca2e4d..16dd90fa9e94 100644
--- a/Documentation/media/uapi/dvb/examples.rst
+++ b/Documentation/media/uapi/dvb/examples.rst
@@ -6,377 +6,11 @@
 Examples
 
 
-In this section we would like to present some examples for using the Digital
-TV API.
+In the past, we used to have a set of examples here. However, those
+examples got out of date and doesn't even compile nowadays.
 
-.. note::
+Also, nowadays, the best is to use the libdvbv5 DVB API nowadays,
+with is fully documented.
 
-   This section is out of date, and the code below won't even
-   compile. Please refer to the
-   `libdvbv5 `__ for
-   updated/recommended examples.
-
-
-.. _tuning:
-
-Example: Tuning
-===
-
-We will start with a generic tuning subroutine that uses the frontend
-and SEC, as well as the demux devices. The example is given for QPSK
-tuners, but can easily be adjusted for QAM.
-
-
-.. code-block:: c
-
- #include 
- #include 
- #include 
- #include 
- #include 
- #include 
- #include 
- #include 
-
- #include 
- #include 
- #include 
- #include 
-
- #define DMX "/dev/dvb/adapter0/demux1"
- #define FRONT "/dev/dvb/adapter0/frontend1"
- #define SEC "/dev/dvb/adapter0/sec1"
-
- /* routine for checking if we have a signal and other status information*/
- int FEReadStatus(int fd, fe_status_t *stat)
- {
-int ans;
-
-if ( (ans = ioctl(fd,FE_READ_STATUS,stat) < 0)){
-perror("FE READ STATUS: ");
-return -1;
-}
-
-if (*stat & FE_HAS_POWER)
-printf("FE HAS POWER\\n");
-
-if (*stat & FE_HAS_SIGNAL)
-printf("FE HAS SIGNAL\\n");
-
-if (*stat & FE_SPECTRUM_INV)
-printf("SPEKTRUM INV\\n");
-
-return 0;
- }
-
-
- /* tune qpsk */
- /* freq: frequency of transponder  */
- /* vpid, apid, tpid: PIDs of video, audio and teletext TS packets  */
- /* diseqc:   DiSEqC address of the used LNB*/
- /* pol:  Polarisation  */
- /* srate:Symbol Rate   */
- /* fec.  FEC   */
- /* lnb_lof1: local frequency of lower LNB band */
- /* lnb_lof2: local frequency of upper LNB band */
- /* lnb_slof: switch frequency of LNB   */
-
- int set_qpsk_channel(int freq, int vpid, int apid, int tpid,
-int diseqc, int pol, int srate, int fec, int lnb_lof1,
-int lnb_lof2, int lnb_slof)
- {
-struct secCommand scmd;
-struct secCmdSequence scmds;
-struct dmx_pes_filter_params pesFilterParams;
-FrontendParameters frp;
-struct pollfd pfd[1];
-FrontendEvent event;
-int demux1, demux2, demux3, front;
-
-frequency = (uint32_t) freq;
-symbolrate = (uint32_t) srate;
-
-if((front = open(FRONT,O_RDWR)) < 0){
-perror("FRONTEND DEVICE: ");
-return -1;
-}
-
-if((sec = open(SEC,O_RDWR)) < 0){
-perror("SEC DEVICE: ");
-return -1;
-}
-
-if (demux1 < 0){
-if ((demux1=open(DMX, O_RDWR|O_NONBLOCK))
-< 0){
-perror("DEMUX DEVICE: ");
-return -1;
-}
-}
-
-if (demux2 < 0){
-if ((demux2=open(DMX, O_RDWR|O_NONBLOCK))
-< 0){
-perror("DEMUX DEVICE: ");
-return -1;
-}
-}
-
-if (demux3 < 0){
-if ((demux3=open(DMX, O_RDWR|O_NONBLOCK))
-< 0){
-perror("DEMUX DEVICE: ");
-return -1;
-}
-}
-
-if (freq < lnb_slof) {
-frp.Frequency = (freq - lnb_lof1);
-scmds.continuousTone = SEC_TONE_OFF;
-} else {
-frp.Frequency = (freq - lnb_lof2);
-scmds.continuousTone = SEC_TONE_ON;
-}
-frp.Inversion = INVERSION_AUTO;
-if (pol) scmds.voltage = SEC_VOLTAGE_18;
-else scmds.voltage = SEC_VOLTAGE_13;
-
-scmd.type=0;
-scmd.u.diseqc.addr=0x10;
-scmd.u.diseqc.cmd=0x38;
-

[PATCH v2 30/37] media: dvb_demux.h: document functions

[Mauro Carvalho Chehab]

The functions used on dvb_demux.h are largely used on DVB drivers.
Yet, none of them are documented.

No functional changes.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/dvb-core/dvb_demux.h | 106 +++--
 1 file changed, 103 insertions(+), 3 deletions(-)

diff --git a/drivers/media/dvb-core/dvb_demux.h 
b/drivers/media/dvb-core/dvb_demux.h
index 43b0cab2e932..15ee2ea23efe 100644
--- a/drivers/media/dvb-core/dvb_demux.h
+++ b/drivers/media/dvb-core/dvb_demux.h
@@ -232,13 +232,113 @@ struct dvb_demux {
int recording;
 };
 
-int dvb_dmx_init(struct dvb_demux *dvbdemux);
-void dvb_dmx_release(struct dvb_demux *dvbdemux);
-void dvb_dmx_swfilter_packets(struct dvb_demux *dvbdmx, const u8 *buf,
+/**
+ * dvb_dmx_init - initialize a digital TV demux struct.
+ *
+ * @demux:  dvb_demux to be initialized.
+ *
+ * Before being able to register a digital TV demux struct, drivers
+ * should call this routine. On its typical usage, some fields should
+ * be initialized at the driver before calling it.
+ *
+ * A typical usecase is::
+ *
+ * dvb->demux.dmx.capabilities =
+ * DMX_TS_FILTERING | DMX_SECTION_FILTERING |
+ * DMX_MEMORY_BASED_FILTERING;
+ * dvb->demux.priv   = dvb;
+ * dvb->demux.filternum  = 256;
+ * dvb->demux.feednum= 256;
+ * dvb->demux.start_feed = driver_start_feed;
+ * dvb->demux.stop_feed  = driver_stop_feed;
+ * ret = dvb_dmx_init(>demux);
+ * if (ret < 0)
+ * return ret;
+ */
+int dvb_dmx_init(struct dvb_demux *demux);
+
+/**
+ * dvb_dmx_release - releases a digital TV demux internal buffers.
+ *
+ * @demux:  dvb_demux to be released.
+ *
+ * The DVB core internally allocates data at @demux. This routine
+ * releases those data. Please notice that the struct itelf is not
+ * released, as it can be embedded on other structs.
+ */
+void dvb_dmx_release(struct dvb_demux *demux);
+
+/**
+ * dvb_dmx_swfilter_packets - use dvb software filter for a buffer with
+ * multiple MPEG-TS packets with 188 bytes each.
+ *
+ * @demux: pointer to  dvb_demux
+ * @buf: buffer with data to be filtered
+ * @count: number of MPEG-TS packets with size of 188.
+ *
+ * The routine will discard a DVB packet that don't start with 0x47.
+ *
+ * Use this routine if the DVB demux fills MPEG-TS buffers that are
+ * already aligned.
+ *
+ * NOTE: The @buf size should have size equal to ``count * 188``.
+ */
+void dvb_dmx_swfilter_packets(struct dvb_demux *demux, const u8 *buf,
  size_t count);
+
+/**
+ * dvb_dmx_swfilter -  use dvb software filter for a buffer with
+ * multiple MPEG-TS packets with 188 bytes each.
+ *
+ * @demux: pointer to  dvb_demux
+ * @buf: buffer with data to be filtered
+ * @count: number of MPEG-TS packets with size of 188.
+ *
+ * If a DVB packet doesn't start with 0x47, it will seek for the first
+ * byte that starts with 0x47.
+ *
+ * Use this routine if the DVB demux fill buffers that may not start with
+ * a packet start mark (0x47).
+ *
+ * NOTE: The @buf size should have size equal to ``count * 188``.
+ */
 void dvb_dmx_swfilter(struct dvb_demux *demux, const u8 *buf, size_t count);
+
+/**
+ * dvb_dmx_swfilter_204 -  use dvb software filter for a buffer with
+ * multiple MPEG-TS packets with 204 bytes each.
+ *
+ * @demux: pointer to  dvb_demux
+ * @buf: buffer with data to be filtered
+ * @count: number of MPEG-TS packets with size of 204.
+ *
+ * If a DVB packet doesn't start with 0x47, it will seek for the first
+ * byte that starts with 0x47.
+ *
+ * Use this routine if the DVB demux fill buffers that may not start with
+ * a packet start mark (0x47).
+ *
+ * NOTE: The @buf size should have size equal to ``count * 204``.
+ */
 void dvb_dmx_swfilter_204(struct dvb_demux *demux, const u8 *buf,
  size_t count);
+
+/**
+ * dvb_dmx_swfilter_raw -  make the raw data available to userspace without
+ * filtering
+ *
+ * @demux: pointer to  dvb_demux
+ * @buf: buffer with data
+ * @count: number of packets to be passed. The actual size of each packet
+ * depends on the _demux->feed->cb.ts logic.
+ *
+ * Use it if the driver needs to deliver the raw payload to userspace without
+ * passing through the kernel demux. That is meant to support some
+ * delivery systems that aren't based on MPEG-TS.
+ *
+ * This function relies on _demux->feed->cb.ts to actually handle the
+ * buffer.
+ */
 void dvb_dmx_swfilter_raw(struct dvb_demux *demux, const u8 *buf,
  size_t count);
 
-- 
2.13.5

[PATCH v2 17/37] media: dtv-core.rst: split into multiple files

[Mauro Carvalho Chehab]

Instead of document all kAPI into a single file, split it
on multiple ones. That makes easier to maintain each part.

As a side effect, it will produce multiple html pages, with
is a good idea.

No changes at the text. Just some chapter levels changed.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/media/kapi/dtv-ca.rst   |   4 +
 Documentation/media/kapi/dtv-common.rst   |  55 +++
 Documentation/media/kapi/dtv-core.rst | 585 +-
 Documentation/media/kapi/dtv-demux.rst|  71 
 Documentation/media/kapi/dtv-frontend.rst | 443 ++
 5 files changed, 579 insertions(+), 579 deletions(-)
 create mode 100644 Documentation/media/kapi/dtv-ca.rst
 create mode 100644 Documentation/media/kapi/dtv-common.rst
 create mode 100644 Documentation/media/kapi/dtv-demux.rst
 create mode 100644 Documentation/media/kapi/dtv-frontend.rst

diff --git a/Documentation/media/kapi/dtv-ca.rst 
b/Documentation/media/kapi/dtv-ca.rst
new file mode 100644
index ..a4dd700189b0
--- /dev/null
+++ b/Documentation/media/kapi/dtv-ca.rst
@@ -0,0 +1,4 @@
+Digital TV Conditional Access kABI
+--
+
+.. kernel-doc:: drivers/media/dvb-core/dvb_ca_en50221.h
diff --git a/Documentation/media/kapi/dtv-common.rst 
b/Documentation/media/kapi/dtv-common.rst
new file mode 100644
index ..40cf1033b5e1
--- /dev/null
+++ b/Documentation/media/kapi/dtv-common.rst
@@ -0,0 +1,55 @@
+Digital TV Common functions
+---
+
+Math functions
+~~
+
+Provide some commonly-used math functions, usually required in order to
+estimate signal strength and signal to noise measurements in dB.
+
+.. kernel-doc:: drivers/media/dvb-core/dvb_math.h
+
+
+DVB devices
+~~~
+
+Those functions are responsible for handling the DVB device nodes.
+
+.. kernel-doc:: drivers/media/dvb-core/dvbdev.h
+
+Digital TV Ring buffer
+~~
+
+Those routines implement ring buffers used to handle digital TV data and
+copy it from/to userspace.
+
+.. note::
+
+  1) For performance reasons read and write routines don't check buffer sizes
+ and/or number of bytes free/available. This has to be done before these
+ routines are called. For example:
+
+   .. code-block:: c
+
+/* write @buflen: bytes */
+free = dvb_ringbuffer_free(rbuf);
+if (free >= buflen)
+count = dvb_ringbuffer_write(rbuf, buffer, buflen);
+else
+/* do something */
+
+/* read min. 1000, max. @bufsize: bytes */
+avail = dvb_ringbuffer_avail(rbuf);
+if (avail >= 1000)
+count = dvb_ringbuffer_read(rbuf, buffer, min(avail, bufsize));
+else
+/* do something */
+
+  2) If there is exactly one reader and one writer, there is no need
+ to lock read or write operations.
+ Two or more readers must be locked against each other.
+ Flushing the buffer counts as a read operation.
+ Resetting the buffer counts as a read and write operation.
+ Two or more writers must be locked against each other.
+
+.. kernel-doc:: drivers/media/dvb-core/dvb_ringbuffer.h
diff --git a/Documentation/media/kapi/dtv-core.rst 
b/Documentation/media/kapi/dtv-core.rst
index 4cf9cf63bafd..8ee384f61fa0 100644
--- a/Documentation/media/kapi/dtv-core.rst
+++ b/Documentation/media/kapi/dtv-core.rst
@@ -26,584 +26,11 @@ I2C bus.
abandoned standard, not used anymore) and ATSC version 3.0 current
proposals. Currently, the DVB subsystem doesn't implement those standards.
 
-Digital TV Common functions

 
-Math functions
-~~
+.. toctree::
+:maxdepth: 1
 
-Provide some commonly-used math functions, usually required in order to
-estimate signal strength and signal to noise measurements in dB.
-
-.. kernel-doc:: drivers/media/dvb-core/dvb_math.h
-
-
-DVB devices
-~~~
-
-Those functions are responsible for handling the DVB device nodes.
-
-.. kernel-doc:: drivers/media/dvb-core/dvbdev.h
-
-Digital TV Ring buffer
---
-
-Those routines implement ring buffers used to handle digital TV data and
-copy it from/to userspace.
-
-.. note::
-
-  1) For performance reasons read and write routines don't check buffer sizes
- and/or number of bytes free/available. This has to be done before these
- routines are called. For example:
-
-   .. code-block:: c
-
-/* write @buflen: bytes */
-free = dvb_ringbuffer_free(rbuf);
-if (free >= buflen)
-count = dvb_ringbuffer_write(rbuf, buffer, buflen);
-else
-/* do something */
-
-/* read min. 1000, max. @bufsize: bytes */
-avail = dvb_ringbuffer_avail(rbuf);
-if (avail >= 1000)
-count = dvb_ringbuffer_read(rbuf, buffer, min(avail, bufsize));
-else
-/* do something */
-
-  2) If there is exactly 

Re: [PATCH v6 2/2] media:imx274 V4l2 driver for Sony imx274 CMOS sensor

[Sakari Ailus]

Hi Leon,

Thanks for the update. A couple of more comments below; I think we're soon
done here.

On Sun, Sep 24, 2017 at 12:53:29AM -0700, Leon Luo wrote:
> The imx274 is a Sony CMOS image sensor that has 1/2.5 image size.
> It supports up to 3840x2160 (4K) 60fps, 1080p 120fps. The interface
> is 4-lane MIPI CSI-2 running at 1.44Gbps each.
> 
> This driver has been tested on Xilinx ZCU102 platform with a Leopard
> LI-IMX274MIPI-FMC camera board.
> 
> Support for the following features:
> -Resolutions: 3840x2160, 1920x1080, 1280x720
> -Frame rate: 3840x2160 : 5 – 60fps
> 1920x1080 : 5 – 120fps
> 1280x720 : 5 – 120fps
> -Exposure time: 16 – (frame interval) micro-seconds
> -Gain: 1x - 180x
> -VFLIP: enable/disabledrivers/media/i2c/imx274.c
> -Test pattern: 12 test patterns
> 
> Signed-off-by: Leon Luo 
> Tested-by: Sören Brinkmann 
> ---
> v6:
> - remove media/v4l2-image-sizes.h from include header
> - make the header file alphabetical order
> - remove fmt->pad check in imx274_get_fmt,
>   the V4L2 subdev framework does it already
> - change 'struct reg_8 *regs' to 'struct reg_8 regs[n]',
>   where n is the exact numbers needed for this function
> - move MODULE_DEVICE_TABLE(of, imx274_of_id_table); closer
>   to imx274_of_id_table definition
> - remove return check of imx274_write_table in imx274_remove,
>   because it should remove all resources even i2c fails here
> - move imx274_load_default before v4l2_async_register_subdev
> v5:
>  - no changes
> v4:
>  - use 32-bit data type to avoid __divdi3 compile error for i386
>  - clean up OR together error codes
> v3:
>  - clean up header files
>  - use struct directly instead of alias #define
>  - use v4l2_ctrl_s_ctrl instead of v4l2_s_ctrl
>  - revise debug output
>  - move static helpers closer to their call site
>  - don't OR toegether error codes
>  - use closest valid gain value instead of erroring out
>  - assigne lock to the control handler and omit explicit locking
>  - acquire mutex lock for imx274_get_fmt
>  - remove format->pad check in imx274_set_fmt since the pad is always 0
>  - pass struct v4l2_ctrl pointer in gain/exposure/vlip/test pattern controls
>  - remove priv->ctrls.vflip->val = val in imx274_set_vflip()
>  - remove priv->ctrls.test_pattern->val = val in imx274_set_test_pattern()
>  - remove empty open/close callbacks
>  - remove empty core ops
>  - add more error labels in probe
>  - use v4l2_async_unregister_subdev instead of v4l2_device_unregister_subdev
>  - use dynamic debug
>  - split start_stream to two steps: imx274_mode_regs() and 
> imx274_start_stream()
>frame rate & exposure can be updated
>between imx274_mode_regs() & imx274_start_stream()
> 
> v2:
>  - Fix Kconfig to not remove existing options
> ---
>  drivers/media/i2c/Kconfig  |7 +
>  drivers/media/i2c/Makefile |1 +
>  drivers/media/i2c/imx274.c | 1804 
> 
>  3 files changed, 1812 insertions(+)
>  create mode 100644 drivers/media/i2c/imx274.c
> 
> diff --git a/drivers/media/i2c/Kconfig b/drivers/media/i2c/Kconfig
> index 47113774a297..9659849e33a0 100644
> --- a/drivers/media/i2c/Kconfig
> +++ b/drivers/media/i2c/Kconfig
> @@ -555,6 +555,13 @@ config VIDEO_APTINA_PLL
>  config VIDEO_SMIAPP_PLL
>   tristate
>  
> +config VIDEO_IMX274
> + tristate "Sony IMX274 sensor support"
> + depends on I2C && VIDEO_V4L2 && VIDEO_V4L2_SUBDEV_API
> + ---help---
> +   This is a V4L2 sensor-level driver for the Sony IMX274
> +   CMOS image sensor.
> +
>  config VIDEO_OV2640
>   tristate "OmniVision OV2640 sensor support"
>   depends on VIDEO_V4L2 && I2C
> diff --git a/drivers/media/i2c/Makefile b/drivers/media/i2c/Makefile
> index c843c181dfb9..f8d57e453936 100644
> --- a/drivers/media/i2c/Makefile
> +++ b/drivers/media/i2c/Makefile
> @@ -92,5 +92,6 @@ obj-$(CONFIG_VIDEO_IR_I2C)  += ir-kbd-i2c.o
>  obj-$(CONFIG_VIDEO_ML86V7667)+= ml86v7667.o
>  obj-$(CONFIG_VIDEO_OV2659)   += ov2659.o
>  obj-$(CONFIG_VIDEO_TC358743) += tc358743.o
> +obj-$(CONFIG_VIDEO_IMX274)   += imx274.o
>  
>  obj-$(CONFIG_SDR_MAX2175) += max2175.o
> diff --git a/drivers/media/i2c/imx274.c b/drivers/media/i2c/imx274.c
> new file mode 100644
> index ..924d543682b0
> --- /dev/null
> +++ b/drivers/media/i2c/imx274.c
> @@ -0,0 +1,1804 @@
> +/*
> + * imx274.c - IMX274 CMOS Image Sensor driver
> + *
> + * Copyright (C) 2017, Leopard Imaging, Inc.
> + *
> + * Leon Luo 
> + * Edwin Zou 
> + *
> + * This program is free software; you can redistribute it and/or modify it
> + * under the terms and conditions of the GNU General Public License,
> + * version 2, as published by the Free Software Foundation.
> + *
> + * This program is distributed in the hope it will be useful, but WITHOUT
> + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
> + * FITNESS FOR A PARTICULAR 

Re: [PATCH v2 07/13] docs: kernel-doc.rst: add documentation about man pages

[Randy Dunlap]

On 09/27/17 14:10, Mauro Carvalho Chehab wrote:
> kernel-doc-nano-HOWTO.txt has a chapter about man pages

  kernel-doc.rst has a chapter (or section)

> production. While we don't have a working  "make manpages"
> target, add it.
> 
> Signed-off-by: Mauro Carvalho Chehab 
> ---
>  Documentation/doc-guide/kernel-doc.rst | 34 
> ++
>  1 file changed, 34 insertions(+)
> 
> diff --git a/Documentation/doc-guide/kernel-doc.rst 
> b/Documentation/doc-guide/kernel-doc.rst
> index 0923c8bd5769..96012f9e314d 100644
> --- a/Documentation/doc-guide/kernel-doc.rst
> +++ b/Documentation/doc-guide/kernel-doc.rst


-- 
~Randy

[PATCH v2 00/13] kernel-doc: add supported to document nested structs/$

[Mauro Carvalho Chehab]

Right now, it is not possible to document nested struct and nested unions.
kernel-doc simply ignore them.

Add support to document them.

Patch 1 gets rid of the now unused output formats for kernel-doc: since 
we got rid of all DocBook stuff, we should not need them anymore. The
reason for dropping it (despite cleaning up), is that it doesn't make 
sense to invest time on adding new features for formats that aren't
used anymore.

Patches 2 to 7 improve kernel-doc documentation to reflect what
kernel-doc currently supports and import some stuff from the
old kernel-doc-nano-HOWTO.txt.

Patch 8 gets rid of the old documentation (kernel-doc-nano-HOWTO.txt).

Patch 9 is the most interesting one in this series: it adds support for
nested structures and unions.

Patch 10 does a cleanup, removing $nexted parameter at the
routines that handle structs.

Patch 11 Improves warning output by printing the identifier where
the warning occurred.

Patch 12 complements patch 9, by adding support for function
definitions inside nested structures. It is needed by some media
docs with use such kind of things.

Patch 13 is just an example from a random header with kernel-doc
markups. There's no special reason for selecting this file, and the
comments there are likely wrong. So, please use it only as a way to test
the new parser logic from patch 9. The real usage (for me, will
be at the media patches, but this is on a 30+ patch series, together
with a bunch of other stuff.

--

v2:
  - solved some issues that Randy pointed;
  - added patch 10 as suggested by Markus;
  - Fixed some bugs on patch 9, after parsing nested structs
   on media subsystem;
  - added patch 11 with a warning improvement fixup;
  - added patch 12 in order to handle function parameters
   on nested structures, due to DVB demux kAPI.

Mauro Carvalho Chehab (13):
  scripts: kernel-doc: get rid of unused output formats
  docs: kernel-doc.rst: better describe kernel-doc arguments
  docs: kernel-doc.rst: improve private members description
  docs: kernel-doc.rst: improve function documentation section
  docs: kernel-doc.rst: improve structs chapter
  docs: kernel-doc.rst: improve typedef documentation
  docs: kernel-doc.rst: add documentation about man pages
  docs: get rid of kernel-doc-nano-HOWTO.txt
  scripts: kernel-doc: parse next structs/unions
  scripts: kernel-doc: get rid of $nested parameter
  scripts: kernel-doc: print the declaration name on warnings
  scripts: kernel-doc: handle nested struct function arguments
  [RFC] w1_netlink.h: add support for nested structs

 Documentation/00-INDEX  |2 -
 Documentation/doc-guide/kernel-doc.rst  |  360 +---
 Documentation/kernel-doc-nano-HOWTO.txt |  322 
 drivers/w1/w1_netlink.h |4 +
 scripts/kernel-doc  | 1376 +++
 5 files changed, 369 insertions(+), 1695 deletions(-)
 delete mode 100644 Documentation/kernel-doc-nano-HOWTO.txt

-- 
2.13.5

[PATCH v2 05/13] docs: kernel-doc.rst: improve structs chapter

[Mauro Carvalho Chehab]

There is a mess on this chapter: it suggests that even
enums and unions should be documented with "struct". That's
not the way it should be ;-)

Fix it and move it to happen earlier.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/doc-guide/kernel-doc.rst | 48 +-
 1 file changed, 24 insertions(+), 24 deletions(-)

diff --git a/Documentation/doc-guide/kernel-doc.rst 
b/Documentation/doc-guide/kernel-doc.rst
index ad0fb487e423..b330234a3601 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -258,6 +258,30 @@ named ``Return``.
  as a new section heading, with probably won't produce the desired
  effect.
 
+Structure, union, and enumeration documentation
+---
+
+The general format of a struct, union, and enum kernel-doc comment is::
+
+  /**
+   * struct struct_name - Brief description.
+   * @argument: Description of member member_name.
+   *
+   * Description of the structure.
+   */
+
+On the above, ``struct`` is used to mean structs. You can also use ``union``
+and ``enum``  to describe unions and enums. ``argument`` is used
+to mean struct and union member names as well as enumerations in an enum.
+
+The brief description following the structure name may span multiple lines, and
+ends with a member description, a blank comment line, or the end of the
+comment block.
+
+The kernel-doc data structure comments describe each member of the structure,
+in order, with the member descriptions.
+
+
 
 Highlights and cross-references
 ---
@@ -331,30 +355,6 @@ cross-references.
 For further details, please refer to the `Sphinx C Domain`_ documentation.
 
 
-Structure, union, and enumeration documentation

-
-The general format of a struct, union, and enum kernel-doc comment is::
-
-  /**
-   * struct struct_name - Brief description.
-   * @member_name: Description of member member_name.
-   *
-   * Description of the structure.
-   */
-
-Below, "struct" is used to mean structs, unions and enums, and "member" is used
-to mean struct and union members as well as enumerations in an enum.
-
-The brief description following the structure name may span multiple lines, and
-ends with a ``@member:`` description, a blank comment line, or the end of the
-comment block.
-
-The kernel-doc data structure comments describe each member of the structure, 
in
-order, with the ``@member:`` descriptions. The ``@member:`` descriptions must
-begin on the very next line following the opening brief function description
-line, with no intervening blank comment lines. The ``@member:`` descriptions 
may
-span multiple lines. The continuation lines may contain indentation.
 
 In-line member documentation comments
 ~
-- 
2.13.5

[PATCH v2 04/13] docs: kernel-doc.rst: improve function documentation section

[Mauro Carvalho Chehab]

Move its contents to happen earlier and improve the description
of return values, adding a subsection to it. Most of the contents
there came from kernel-doc-nano-HOWTO.txt.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/doc-guide/kernel-doc.rst | 100 -
 1 file changed, 61 insertions(+), 39 deletions(-)

diff --git a/Documentation/doc-guide/kernel-doc.rst 
b/Documentation/doc-guide/kernel-doc.rst
index 146041fc494a..ad0fb487e423 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -197,6 +197,67 @@ Example::
   int d;
   };
 
+Function documentation
+--
+
+The general format of a function and function-like macro kernel-doc comment 
is::
+
+  /**
+   * function_name() - Brief description of function.
+   * @arg1: Describe the first argument.
+   * @arg2: Describe the second argument.
+   *One can provide multiple line descriptions
+   *for arguments.
+   *
+   * A longer description, with more discussion of the function function_name()
+   * that might be useful to those using or modifying it. Begins with an
+   * empty comment line, and may include additional embedded empty
+   * comment lines.
+   *
+   * The longer description may have multiple paragraphs.
+   *
+   * Return: Describe the return value of foobar.
+   *
+   * The return value description can also have multiple paragraphs, and should
+   * be placed at the end of the comment block.
+   */
+
+The brief description following the function name may span multiple lines, and
+ends with an argument description, a blank comment line, or the end of the
+comment block.
+
+Return values
+~
+
+The return value, if any, should be described in a dedicated section
+named ``Return``.
+
+.. note::
+
+  #) The multi-line descriptive text you provide does *not* recognize
+ line breaks, so if you try to format some text nicely, as in::
+
+   * Return:
+   * 0 - OK
+   * -EINVAL - invalid argument
+   * -ENOMEM - out of memory
+
+ this will all run together and produce::
+
+   Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory
+
+ So, in order to produce the desired line breaks, you need to use a
+ ReST list, e. g.::
+
+  * Return:
+  * * 0- OK to runtime suspend the device
+  * * -EBUSY   - Device should not be runtime suspended
+
+  #) If the descriptive text you provide has lines that begin with
+ some phrase followed by a colon, each of those phrases will be taken
+ as a new section heading, with probably won't produce the desired
+ effect.
+
 
 Highlights and cross-references
 ---
@@ -269,45 +330,6 @@ cross-references.
 
 For further details, please refer to the `Sphinx C Domain`_ documentation.
 
-Function documentation
---
-
-The general format of a function and function-like macro kernel-doc comment 
is::
-
-  /**
-   * function_name() - Brief description of function.
-   * @arg1: Describe the first argument.
-   * @arg2: Describe the second argument.
-   *One can provide multiple line descriptions
-   *for arguments.
-   *
-   * A longer description, with more discussion of the function function_name()
-   * that might be useful to those using or modifying it. Begins with an
-   * empty comment line, and may include additional embedded empty
-   * comment lines.
-   *
-   * The longer description may have multiple paragraphs.
-   *
-   * Return: Describe the return value of foobar.
-   *
-   * The return value description can also have multiple paragraphs, and should
-   * be placed at the end of the comment block.
-   */
-
-The brief description following the function name may span multiple lines, and
-ends with an ``@argument:`` description, a blank comment line, or the end of 
the
-comment block.
-
-The kernel-doc function comments describe each parameter to the function, in
-order, with the ``@argument:`` descriptions. The ``@argument:`` descriptions
-must begin on the very next line following the opening brief function
-description line, with no intervening blank comment lines. The ``@argument:``
-descriptions may span multiple lines. The continuation lines may contain
-indentation. If a function parameter is ``...`` (varargs), it should be listed
-in kernel-doc notation as: ``@...:``.
-
-The return value, if any, should be described in a dedicated section at the end
-of the comment starting with "Return:".
 
 Structure, union, and enumeration documentation
 ---
-- 
2.13.5

[PATCH v2 08/13] docs: get rid of kernel-doc-nano-HOWTO.txt

[Mauro Carvalho Chehab]

Everything there is already described at
Documentation/doc-guide/kernel-doc.rst. So, there's no reason why
to keep it anymore.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/00-INDEX  |   2 -
 Documentation/kernel-doc-nano-HOWTO.txt | 322 
 scripts/kernel-doc  |   2 +-
 3 files changed, 1 insertion(+), 325 deletions(-)
 delete mode 100644 Documentation/kernel-doc-nano-HOWTO.txt

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 3bec49c33bbb..aca4f00ec69b 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -228,8 +228,6 @@ isdn/
- directory with info on the Linux ISDN support, and supported cards.
 kbuild/
- directory with info about the kernel build process.
-kernel-doc-nano-HOWTO.txt
-   - outdated info about kernel-doc documentation.
 kdump/
- directory with mini HowTo on getting the crash dump code to work.
 doc-guide/
diff --git a/Documentation/kernel-doc-nano-HOWTO.txt 
b/Documentation/kernel-doc-nano-HOWTO.txt
deleted file mode 100644
index c23e2c5ab80d..
--- a/Documentation/kernel-doc-nano-HOWTO.txt
+++ /dev/null
@@ -1,322 +0,0 @@
-NOTE: this document is outdated and will eventually be removed.  See
-Documentation/doc-guide/ for current information.
-
-kernel-doc nano-HOWTO
-=
-
-How to format kernel-doc comments
--
-
-In order to provide embedded, 'C' friendly, easy to maintain,
-but consistent and extractable documentation of the functions and
-data structures in the Linux kernel, the Linux kernel has adopted
-a consistent style for documenting functions and their parameters,
-and structures and their members.
-
-The format for this documentation is called the kernel-doc format.
-It is documented in this Documentation/kernel-doc-nano-HOWTO.txt file.
-
-This style embeds the documentation within the source files, using
-a few simple conventions.  The scripts/kernel-doc perl script, the
-Documentation/sphinx/kerneldoc.py Sphinx extension and other tools understand
-these conventions, and are used to extract this embedded documentation
-into various documents.
-
-In order to provide good documentation of kernel functions and data
-structures, please use the following conventions to format your
-kernel-doc comments in Linux kernel source.
-
-We definitely need kernel-doc formatted documentation for functions
-that are exported to loadable modules using EXPORT_SYMBOL.
-
-We also look to provide kernel-doc formatted documentation for
-functions externally visible to other kernel files (not marked
-"static").
-
-We also recommend providing kernel-doc formatted documentation
-for private (file "static") routines, for consistency of kernel
-source code layout.  But this is lower priority and at the
-discretion of the MAINTAINER of that kernel source file.
-
-Data structures visible in kernel include files should also be
-documented using kernel-doc formatted comments.
-
-The opening comment mark "/**" is reserved for kernel-doc comments.
-Only comments so marked will be considered by the kernel-doc scripts,
-and any comment so marked must be in kernel-doc format.  Do not use
-"/**" to be begin a comment block unless the comment block contains
-kernel-doc formatted comments.  The closing comment marker for
-kernel-doc comments can be either "*/" or "**/", but "*/" is
-preferred in the Linux kernel tree.
-
-Kernel-doc comments should be placed just before the function
-or data structure being described.
-
-Example kernel-doc function comment:
-
-/**
- * foobar() - short function description of foobar
- * @arg1:  Describe the first argument to foobar.
- * @arg2:  Describe the second argument to foobar.
- * One can provide multiple line descriptions
- * for arguments.
- *
- * A longer description, with more discussion of the function foobar()
- * that might be useful to those using or modifying it.  Begins with
- * empty comment line, and may include additional embedded empty
- * comment lines.
- *
- * The longer description can have multiple paragraphs.
- *
- * Return: Describe the return value of foobar.
- */
-
-The short description following the subject can span multiple lines
-and ends with an @argument description, an empty line or the end of
-the comment block.
-
-The @argument descriptions must begin on the very next line following
-this opening short function description line, with no intervening
-empty comment lines.
-
-If a function parameter is "..." (varargs), it should be listed in
-kernel-doc notation as:
- * @...: description
-
-The return value, if any, should be described in a dedicated section
-named "Return".
-
-Example kernel-doc data structure comment.
-
-/**
- * struct blah - the basic blah structure
- * @mem1:  describe the first member of struct blah
- * @mem2:  describe the second member of struct blah,
- * 

[PATCH v2 03/13] docs: kernel-doc.rst: improve private members description

[Mauro Carvalho Chehab]

The private members section can now be moved to be together
with the arguments section. Move it there and add an example
about the usage of public:

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/doc-guide/kernel-doc.rst | 56 ++
 1 file changed, 30 insertions(+), 26 deletions(-)

diff --git a/Documentation/doc-guide/kernel-doc.rst 
b/Documentation/doc-guide/kernel-doc.rst
index 662755f830d5..146041fc494a 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -167,6 +167,36 @@ notation as::
 
   * @...: description
 
+Private members
+~~~
+
+Inside a struct or union description, you can use the ``private:`` and
+``public:`` comment tags. Structure fields that are inside a ``private:``
+area are not listed in the generated output documentation.
+
+The ``private:`` and ``public:`` tags must begin immediately following a
+``/*`` comment marker.  They may optionally include comments between the
+``:`` and the ending ``*/`` marker.
+
+Example::
+
+  /**
+   * struct my_struct - short description
+   * @a: first member
+   * @b: second member
+   * @d: fourth member
+   *
+   * Longer description
+   */
+  struct my_struct {
+  int a;
+  int b;
+  /* private: internal use only */
+  int c;
+  /* public: the next one is public */
+  int d;
+  };
+
 
 Highlights and cross-references
 ---
@@ -332,32 +362,6 @@ on a line of their own, like all other kernel-doc 
comments::
 int foobar;
   }
 
-Private members
-~~~
-
-Inside a struct description, you can use the "private:" and "public:" comment
-tags. Structure fields that are inside a "private:" area are not listed in the
-generated output documentation.  The "private:" and "public:" tags must begin
-immediately following a ``/*`` comment marker.  They may optionally include
-comments between the ``:`` and the ending ``*/`` marker.
-
-Example::
-
-  /**
-   * struct my_struct - short description
-   * @a: first member
-   * @b: second member
-   *
-   * Longer description
-   */
-  struct my_struct {
-  int a;
-  int b;
-  /* private: internal use only */
-  int c;
-  };
-
-
 Typedef documentation
 -
 
-- 
2.13.5

[PATCH v2 11/13] scripts: kernel-doc: print the declaration name on warnings

[Mauro Carvalho Chehab]

The logic at create_parameterlist()'s ancillary push_parameter()
function has already a way to output the declaration name, with
would help to discover what declaration is missing.

However, currently, the logic is utterly broken, as it uses
the var $type with a wrong meaning. With the current code,
it will never print anything. I suspect that originally
it was using the second argument of output_declaration().

I opted to not rely on a globally defined $declaration_name,
but, instead, to pass it explicitly as a parameter.

While here, I removed a unaligned check for !$anon_struct_union.
This is not needed, as, if $anon_struct_union is not zero,
$parameterdescs{$param} will be defined.

Signed-off-by: Mauro Carvalho Chehab 
---
 scripts/kernel-doc | 38 --
 1 file changed, 16 insertions(+), 22 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 28c5fe63fb58..713608046d3a 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1037,7 +1037,7 @@ sub dump_struct($$) {
# Ignore other nested elements, like enums
$members =~ s/({[^\{\}]*})//g;
 
-   create_parameterlist($members, ';', $file);
+   create_parameterlist($members, ';', $file, $declaration_name);
check_sections($file, $declaration_name, "struct", $sectcheck, 
$struct_actual);
 
# Adjust declaration for better display
@@ -1137,7 +1137,7 @@ sub dump_typedef($$) {
$declaration_name = $2;
my $args = $3;
 
-   create_parameterlist($args, ',', $file);
+   create_parameterlist($args, ',', $file, $declaration_name);
 
output_declaration($declaration_name,
   'function',
@@ -1186,10 +1186,11 @@ sub save_struct_actual($) {
 $struct_actual = $struct_actual . $actual . " ";
 }
 
-sub create_parameterlist($$$) {
+sub create_parameterlist() {
 my $args = shift;
 my $splitter = shift;
 my $file = shift;
+my $declaration_name = shift;
 my $type;
 my $param;
 
@@ -1219,7 +1220,7 @@ sub create_parameterlist($$$) {
$type = $arg;
$type =~ s/([^\(]+\(\*?)\s*$param/$1/;
save_struct_actual($param);
-   push_parameter($param, $type, $file);
+   push_parameter($param, $type, $file, $declaration_name);
} elsif ($arg) {
$arg =~ s/\s*:\s*/:/g;
$arg =~ s/\s*\[/\[/g;
@@ -1244,27 +1245,28 @@ sub create_parameterlist($$$) {
foreach $param (@args) {
if ($param =~ m/^(\*+)\s*(.*)/) {
save_struct_actual($2);
-   push_parameter($2, "$type $1", $file);
+   push_parameter($2, "$type $1", $file, $declaration_name);
}
elsif ($param =~ m/(.*?):(\d+)/) {
if ($type ne "") { # skip unnamed bit-fields
save_struct_actual($1);
-   push_parameter($1, "$type:$2", $file)
+   push_parameter($1, "$type:$2", $file, $declaration_name)
}
}
else {
save_struct_actual($param);
-   push_parameter($param, $type, $file);
+   push_parameter($param, $type, $file, $declaration_name);
}
}
}
 }
 }
 
-sub push_parameter($$$) {
+sub push_parameter() {
my $param = shift;
my $type = shift;
my $file = shift;
+   my $declaration_name = shift;
 
if (($anon_struct_union == 1) && ($type eq "") &&
($param eq "}")) {
@@ -1301,21 +1303,13 @@ sub push_parameter($$$) {
# warn if parameter has no description
# (but ignore ones starting with # as these are not parameters
# but inline preprocessor statements);
-   # also ignore unnamed structs/unions;
-   if (!$anon_struct_union) {
+   # Note: It will also ignore void params and unnamed structs/unions
if (!defined $parameterdescs{$param} && $param !~ /^#/) {
+   $parameterdescs{$param} = $undescribed;
 
-   $parameterdescs{$param} = $undescribed;
-
-   if (($type eq 'function') || ($type eq 'enum')) {
-   print STDERR "${file}:$.: warning: Function parameter ".
-   "or member '$param' not " .
-   "described in '$declaration_name'\n";
-   }
-   print STDERR "${file}:$.: warning:" .
-" No description found for parameter '$param'\n";
-   ++$warnings;
-   }
+   print STDERR
+ "${file}:$.: warning: Function parameter or member 
'$param' not described in '$declaration_name'\n";
+   ++$warnings;
}
 
$param = xml_escape($param);
@@ -1472,7 +1466,7 @@ sub dump_function($$) {
$declaration_name = $2;
my $args = $3;
 
-   create_parameterlist($args, ',', $file);
+   

[PATCH v2 13/13] [RFC] w1_netlink.h: add support for nested structs

[Mauro Carvalho Chehab]

Describe nested struct/union fields

NOTE: This is a pure test patch, meant to validate if the
parsing logic for nested structs is working properly.

I've no idea if the random text I added there is correct!

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/w1/w1_netlink.h | 4 
 1 file changed, 4 insertions(+)

diff --git a/drivers/w1/w1_netlink.h b/drivers/w1/w1_netlink.h
index a36661cd1f05..e781d1109cd7 100644
--- a/drivers/w1/w1_netlink.h
+++ b/drivers/w1/w1_netlink.h
@@ -60,6 +60,10 @@ enum w1_netlink_message_types {
  * @status: kernel feedback for success 0 or errno failure value
  * @len: length of data following w1_netlink_msg
  * @id: union holding master bus id (msg.id) and slave device id (id[8]).
+ * @id.id: Slave ID (8 bytes)
+ * @id.mst: master bus identification
+ * @id.mst.id: master bus ID
+ * @id.mst.res: master bus reserved
  * @data: start address of any following data
  *
  * The base message structure for w1 messages over netlink.
-- 
2.13.5

[PATCH v2 09/13] scripts: kernel-doc: parse next structs/unions

[Mauro Carvalho Chehab]

There are several places within the Kernel tree with nested
structs/unions, like this one:

  struct ingenic_cgu_clk_info {
const char *name;
enum {
  CGU_CLK_NONE = 0,
  CGU_CLK_EXT = BIT(0),
  CGU_CLK_PLL = BIT(1),
  CGU_CLK_GATE = BIT(2),
  CGU_CLK_MUX = BIT(3),
  CGU_CLK_MUX_GLITCHFREE = BIT(4),
  CGU_CLK_DIV = BIT(5),
  CGU_CLK_FIXDIV = BIT(6),
  CGU_CLK_CUSTOM = BIT(7),
} type;
int parents[4];
union {
  struct ingenic_cgu_pll_info pll;
  struct {
struct ingenic_cgu_gate_info gate;
struct ingenic_cgu_mux_info mux;
struct ingenic_cgu_div_info div;
struct ingenic_cgu_fixdiv_info fixdiv;
  };
  struct ingenic_cgu_custom_info custom;
};
  };

Currently, such struct is documented as:

**Definition**

::
struct ingenic_cgu_clk_info {
const char * name;
};

**Members**

``name``
  name of the clock

With is obvioulsy wrong. It also generates an error:
drivers/clk/ingenic/cgu.h:169: warning: No description found for 
parameter 'enum'

However, there's nothing wrong with this kernel-doc markup: everything
is documented there.

It makes sense to document all fields there. So, add a
way for the core to parse those structs.

With this patch, all documented fields will properly generate
documentation.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/doc-guide/kernel-doc.rst |  46 
 scripts/kernel-doc | 123 ++---
 2 files changed, 115 insertions(+), 54 deletions(-)

diff --git a/Documentation/doc-guide/kernel-doc.rst 
b/Documentation/doc-guide/kernel-doc.rst
index 96012f9e314d..9e63a18cceea 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -281,6 +281,52 @@ comment block.
 The kernel-doc data structure comments describe each member of the structure,
 in order, with the member descriptions.
 
+Nested structs/unions
+~
+
+It is possible to document nested structs unions, like::
+
+  /**
+   * struct nested_foobar - a struct with nested unions and structs
+   * @arg1: - first argument of anonymous union/anonymous struct
+   * @arg2: - second argument of anonymous union/anonymous struct
+   * @arg3: - third argument of anonymous union/anonymous struct
+   * @arg4: - fourth argument of anonymous union/anonymous struct
+   * @bar.st1.arg1 - first argument of struct st1 on union bar
+   * @bar.st1.arg2 - second argument of struct st1 on union bar
+   * @bar.st2.arg1 - first argument of struct st2 on union bar
+   * @bar.st2.arg2 - second argument of struct st2 on union bar
+  struct nested_foobar {
+/* Anonymous union/struct*/
+union {
+  struct {
+int arg1;
+int arg2;
+ }
+  struct {
+void *arg3;
+int arg4;
+ }
+   }
+   union {
+  struct {
+int arg1;
+int arg2;
+ } st1;
+  struct {
+void *arg1;
+int arg2;
+ } st2;
+   } bar;
+  };
+
+.. note::
+
+   #) When documenting nested structs or unions, if the struct/union ``foo``
+  is named, the argument ``bar`` inside it should be documented as
+  ``@foo.bar:``
+   #) When the nested struct/union is anonymous, the argument ``bar`` on it
+  should be documented as ``@bar:``
 
 Typedef documentation
 -
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index b6f3f6962897..63aa9f85d635 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -210,7 +210,7 @@ my $anon_struct_union = 0;
 my $type_constant = '\b``([^\`]+)``\b';
 my $type_constant2 = '\%([-_\w]+)';
 my $type_func = '(\w+)\(\)';
-my $type_param = '\@(\w+(\.\.\.)?)';
+my $type_param = '\@(\w*(\.\w+)*(\.\.\.)?)';
 my $type_fp_param = '\@(\w+)\(\)';  # Special RST handling for func ptr params
 my $type_env = '(\$\w+)';
 my $type_enum = '\&(enum\s*([_\w]+))';
@@ -663,32 +663,12 @@ sub output_struct_man(%) {
 print ".SH NAME\n";
 print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . 
"\n";
 
+my $declaration = $args{'definition'};
+$declaration =~ s/\t/  /g;
+$declaration =~ s/\n/"\n.br\n.BI \"/g;
 print ".SH SYNOPSIS\n";
 print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
-
-foreach my $parameter (@{$args{'parameterlist'}}) {
-   if ($parameter =~ /^#/) {
-   print ".BI \"$parameter\"\n.br\n";
-   next;
-   }
-   my $parameter_name = $parameter;
-   $parameter_name =~ s/\[.*//;
-
-   ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
-   $type = $args{'parametertypes'}{$parameter};
-   if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
-   # pointer-to-function
-   print 

[PATCH v2 02/13] docs: kernel-doc.rst: better describe kernel-doc arguments

[Mauro Carvalho Chehab]

Add a new section to describe kernel-doc arguments,
adding examples about how identation should happen, as failing
to do that causes Sphinx to do the wrong thing.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/doc-guide/kernel-doc.rst | 44 +++---
 1 file changed, 41 insertions(+), 3 deletions(-)

diff --git a/Documentation/doc-guide/kernel-doc.rst 
b/Documentation/doc-guide/kernel-doc.rst
index b24854b5d6be..662755f830d5 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -112,16 +112,17 @@ Example kernel-doc function comment::
 
   /**
* foobar() - Brief description of foobar.
-   * @arg: Description of argument of foobar.
+   * @argument1: Description of parameter argument1 of foobar.
+   * @argument2: Description of parameter argument2 of foobar.
*
* Longer description of foobar.
*
* Return: Description of return value of foobar.
*/
-  int foobar(int arg)
+  int foobar(int argument1, char *argument2)
 
 The format is similar for documentation for structures, enums, paragraphs,
-etc. See the sections below for details.
+etc. See the sections below for specific details of each type.
 
 The kernel-doc structure is extracted from the comments, and proper `Sphinx C
 Domain`_ function and type descriptions with anchors are generated for them. 
The
@@ -130,6 +131,43 @@ cross-references. See below for details.
 
 .. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
 
+
+Parameters and member arguments
+---
+
+The kernel-doc function comments describe each parameter to the function and
+function typedefs or each member of struct/union, in order, with the
+``@argument:`` descriptions. For each non-private member argument, one
+``@argument`` definition is needed.
+
+The ``@argument:`` descriptions begin on the very next line following
+the opening brief function description line, with no intervening blank
+comment lines.
+
+The ``@argument:`` descriptions may span multiple lines.
+
+.. note::
+
+   If the ``@argument`` description has multiple lines, the continuation
+   of the description should be starting exactly at the same column as
+   the previous line, e. g.::
+
+  * @argument: some long description
+  *   that continues on next lines
+
+   or::
+
+  * @argument:
+  *some long description
+  *that continues on next lines
+
+If a function or typedef parameter argument is ``...`` (e. g. a variable
+number of arguments), its description should be listed in kernel-doc
+notation as::
+
+  * @...: description
+
+
 Highlights and cross-references
 ---
 
-- 
2.13.5

[PATCH v2 12/13] scripts: kernel-doc: handle nested struct function arguments

[Mauro Carvalho Chehab]

Function arguments are different than usual ones. So, an
special logic is needed in order to handle such arguments
on nested structs.

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

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 713608046d3a..376365d41718 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1015,18 +1015,32 @@ sub dump_struct($$) {
$id =~ s/^\*+//;
foreach my $arg (split /;/, $content) {
next if ($arg =~ m/^\s*$/);
-   my $type = $arg;
-   my $name = $arg;
-   $type =~ s/\s\S+$//;
-   $name =~ s/.*\s//;
-   $name =~ s/[:\[].*//;
-   $name =~ s/^\*+//;
-   next if (($name =~ m/^\s*$/));
-   if ($id =~ m/^\s*$/) {
-   # anonymous struct/union
-   $newmember .= "$type $name;";
+   if ($arg =~ 
m/^([^\(]+\(\*?\s*)([\w\.]*)(\s*\).*)/) {
+   # pointer-to-function
+   my $type = $1;
+   my $name = $2;
+   my $extra = $3;
+   next if (!$name);
+   if ($id =~ m/^\s*$/) {
+   # anonymous struct/union
+   $newmember .= 
"$type$name$extra;";
+   } else {
+   $newmember .= 
"$type$id.$name$extra;";
+   }
} else {
-   $newmember .= "$type $id.$name;";
+   my $type = $arg;
+   my $name = $arg;
+   $type =~ s/\s\S+$//;
+   $name =~ s/.*\s+//;
+   $name =~ s/[:\[].*//;
+   $name =~ s/^\*+//;
+   next if (($name =~ m/^\s*$/));
+   if ($id =~ m/^\s*$/) {
+   # anonymous struct/union
+   $newmember .= "$type $name;";
+   } else {
+   $newmember .= "$type 
$id.$name;";
+   }
}
}
$members =~ 
s/(struct|union)([^{};]+){([^{}]*)}([^{}\;]*)\;/$newmember/;
@@ -1215,7 +1229,7 @@ sub create_parameterlist() {
} elsif ($arg =~ m/\(.+\)\s*\(/) {
# pointer-to-function
$arg =~ tr/#/,/;
-   $arg =~ m/[^\(]+\(\*?\s*(\w*)\s*\)/;
+   $arg =~ m/[^\(]+\(\*?\s*([\w\.]*)\s*\)/;
$param = $1;
$type = $arg;
$type =~ s/([^\(]+\(\*?)\s*$param/$1/;
-- 
2.13.5

[PATCH v2 10/13] scripts: kernel-doc: get rid of $nested parameter

[Mauro Carvalho Chehab]

The check_sections() function has a $nested parameter, meant
to identify when a nested struct is present. As we now have
a logic that handles it, get rid of such parameter.

Suggested-by: Markus Heiser 
Signed-off-by: Mauro Carvalho Chehab 
---
 scripts/kernel-doc | 19 ---
 1 file changed, 4 insertions(+), 15 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 63aa9f85d635..28c5fe63fb58 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -979,7 +979,6 @@ sub dump_union($$) {
 sub dump_struct($$) {
 my $x = shift;
 my $file = shift;
-my $nested;
 
 if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {
my $decl_type = $1;
@@ -1037,11 +1036,9 @@ sub dump_struct($$) {
 
# Ignore other nested elements, like enums
$members =~ s/({[^\{\}]*})//g;
-   $nested = $decl_type;
-   $nested =~ s/\/\*.*?\*\///gos;
 
create_parameterlist($members, ';', $file);
-   check_sections($file, $declaration_name, "struct", $sectcheck, 
$struct_actual, $nested);
+   check_sections($file, $declaration_name, "struct", $sectcheck, 
$struct_actual);
 
# Adjust declaration for better display
$declaration =~ s/([{;])/$1\n/g;
@@ -1337,8 +1334,8 @@ sub push_parameter($$$) {
$parametertypes{$param} = $type;
 }
 
-sub check_sections($$) {
-   my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck, $nested) = 
@_;
+sub check_sections($) {
+   my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck) = @_;
my @sects = split ' ', $sectcheck;
my @prms = split ' ', $prmscheck;
my $err;
@@ -1372,14 +1369,6 @@ sub check_sections($$) {
"'$sects[$sx]' " .
"description in '$decl_name'\n";
++$warnings;
-   } else {
-   if ($nested !~ m/\Q$sects[$sx]\E/) {
-   print STDERR "${file}:$.: warning: " .
-   "Excess struct/union/enum/typedef 
member " .
-   "'$sects[$sx]' " .
-   "description in '$decl_name'\n";
-   ++$warnings;
-   }
}
}
}
@@ -1490,7 +1479,7 @@ sub dump_function($$) {
 }
 
my $prms = join " ", @parameterlist;
-   check_sections($file, $declaration_name, "function", $sectcheck, $prms, 
"");
+   check_sections($file, $declaration_name, "function", $sectcheck, $prms);
 
 # This check emits a lot of warnings at the moment, because many
 # functions don't have a 'Return' doc section. So until the number
-- 
2.13.5

[PATCH v2 01/13] scripts: kernel-doc: get rid of unused output formats

[Mauro Carvalho Chehab]

Since there isn't any docbook code anymore upstream,
we can get rid of several output formats:

- docbook/xml, html, html5 and list formats were used by
  the old build system;
- As ReST is text, there's not much sense on outputting
  on a different text format.

After this patch, only man and rst output formats are
supported.

Signed-off-by: Mauro Carvalho Chehab 
Acked-by: Jani Nikula 
---
 scripts/kernel-doc | 1182 +---
 1 file changed, 4 insertions(+), 1178 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 9d3eafea58f0..69757ee9db4c 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -51,13 +51,8 @@ The documentation comments are identified by "/**" opening 
comment mark. See
 Documentation/kernel-doc-nano-HOWTO.txt for the documentation comment syntax.
 
 Output format selection (mutually exclusive):
-  -docbook Output DocBook format.
-  -htmlOutput HTML format.
-  -html5   Output HTML5 format.
-  -listOutput symbol list format. This is for use by 
docproc.
   -man Output troff manual page format. This is the default.
   -rst Output reStructuredText format.
-  -textOutput plain text format.
 
 Output selection (mutually exclusive):
   -export  Only output documentation for symbols that have been
@@ -224,84 +219,11 @@ my $type_typedef = '\&(typedef\s*([_\w]+))';
 my $type_union = '\&(union\s*([_\w]+))';
 my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
 my $type_fallback = '\&([_\w]+)';
-my $type_enum_xml = '\(enum\s*([_\w]+))';
-my $type_struct_xml = '\(struct\s*([_\w]+))';
-my $type_typedef_xml = '\(typedef\s*([_\w]+))';
-my $type_union_xml = '\(union\s*([_\w]+))';
-my $type_member_xml = '\([_\w]+)(\.|-\)([_\w]+)';
-my $type_fallback_xml = '\([_\w]+)';
 my $type_member_func = $type_member . '\(\)';
 
 # Output conversion substitutions.
 #  One for each output format
 
-# these work fairly well
-my @highlights_html = (
-   [$type_constant, "\$1"],
-   [$type_constant2, "\$1"],
-   [$type_func, "\$1"],
-   [$type_enum_xml, "\$1"],
-   [$type_struct_xml, "\$1"],
-   [$type_typedef_xml, "\$1"],
-   [$type_union_xml, "\$1"],
-   [$type_env, "\$1"],
-   [$type_param, "\$1"],
-   [$type_member_xml, "\$1\$2\$3"],
-   [$type_fallback_xml, "\$1"]
-  );
-my $local_lt = "lt:";
-my $local_gt = "gt:";
-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"],
-[$type_typedef_xml, "\$1"],
-[$type_union_xml, "\$1"],
-[$type_env, "\$1"],
-[$type_param, "\$1]"],
-[$type_member_xml, "\$1\$2\$3"],
-[$type_fallback_xml, "\$1"]
-  );
-my $blankline_html5 = $local_lt . "br /" . $local_gt;
-
-# XML, docbook format
-my @highlights_xml = (
-  ["([^=])\\\"([^\\\"<]+)\\\"", "\$1\$2"],
-  [$type_constant, "\$1"],
-  [$type_constant2, "\$1"],
-  [$type_enum_xml, "\$1"],
-  [$type_struct_xml, "\$1"],
-  [$type_typedef_xml, "\$1"],
-  [$type_union_xml, "\$1"],
-  [$type_param, "\$1"],
-  [$type_func, "\$1"],
-  [$type_env, "\$1"],
-  [$type_member_xml, 
"\$1\$2\$3"],
-  [$type_fallback_xml, "\$1"]
-);
-my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . 
$local_gt . "\n";
-
-# gnome, docbook format
-my @highlights_gnome = (
-[$type_constant, "\$1"],
-[$type_constant2, "\$1"],
-[$type_func, "\$1"],
-[$type_enum, "\$1"],
-[$type_struct, "\$1"],
-[$type_typedef, "\$1"],
-[$type_union, "\$1"],
-[$type_env, "\$1"],
-[$type_param, "\$1" ],
-[$type_member, 
"\$1\$2\$3"],
-[$type_fallback, "\$1"]
-  );
-my $blankline_gnome = "\n";
-
 # these are pretty rough
 my @highlights_man = (
   

[PATCH v2 07/13] docs: kernel-doc.rst: add documentation about man pages

[Mauro Carvalho Chehab]

kernel-doc-nano-HOWTO.txt has a chapter about man pages
production. While we don't have a working  "make manpages"
target, add it.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/doc-guide/kernel-doc.rst | 34 ++
 1 file changed, 34 insertions(+)

diff --git a/Documentation/doc-guide/kernel-doc.rst 
b/Documentation/doc-guide/kernel-doc.rst
index 0923c8bd5769..96012f9e314d 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -452,3 +452,37 @@ file.
 
 Data structures visible in kernel include files should also be documented using
 kernel-doc formatted comments.
+
+How to use kernel-doc to generate man pages
+---
+
+If you just want to use kernel-doc to generate man pages you can do this
+from the Kernel git tree::
+
+  $ scripts/kernel-doc -man $(git grep -l '/\*\*' |grep -v Documentation/) | 
./split-man.pl /tmp/man
+
+Using the small ``split-man.pl`` script below::
+
+
+  #!/usr/bin/perl
+
+  if ($#ARGV < 0) {
+ die "where do I put the results?\n";
+  }
+
+  mkdir $ARGV[0],0777;
+  $state = 0;
+  while () {
+  if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) {
+   if ($state == 1) { close OUT }
+   $state = 1;
+   $fn = "$ARGV[0]/$1.9";
+   print STDERR "Creating $fn\n";
+   open OUT, ">$fn" or die "can't open $fn: $!\n";
+   print OUT $_;
+  } elsif ($state != 0) {
+   print OUT $_;
+  }
+  }
+
+  close OUT;
-- 
2.13.5

[PATCH v2 06/13] docs: kernel-doc.rst: improve typedef documentation

[Mauro Carvalho Chehab]

Add documentation about typedefs for function prototypes and
move it to happen earlier.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/doc-guide/kernel-doc.rst | 32 ++--
 1 file changed, 22 insertions(+), 10 deletions(-)

diff --git a/Documentation/doc-guide/kernel-doc.rst 
b/Documentation/doc-guide/kernel-doc.rst
index b330234a3601..0923c8bd5769 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -282,6 +282,28 @@ The kernel-doc data structure comments describe each 
member of the structure,
 in order, with the member descriptions.
 
 
+Typedef documentation
+-
+
+The general format of a typedef kernel-doc comment is::
+
+  /**
+   * typedef type_name - Brief description.
+   *
+   * Description of the type.
+   */
+
+Typedefs with function prototypes can also be documented::
+
+  /**
+   * typedef type_name - Brief description.
+   * @arg1: description of arg1
+   * @arg2: description of arg2
+   *
+   * Description of the type.
+   */
+   typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);
+
 
 Highlights and cross-references
 ---
@@ -384,16 +406,6 @@ on a line of their own, like all other kernel-doc 
comments::
 int foobar;
   }
 
-Typedef documentation
--
-
-The general format of a typedef kernel-doc comment is::
-
-  /**
-   * typedef type_name - Brief description.
-   *
-   * Description of the type.
-   */
 
 Overview documentation comments
 ---
-- 
2.13.5

Re: [PATCH 01/10] scripts: kernel-doc: get rid of unused output formats

[Mauro Carvalho Chehab]

Em Wed, 27 Sep 2017 17:36:59 +0300
Jani Nikula  escreveu:

> On Tue, 26 Sep 2017, Mauro Carvalho Chehab  wrote:
> > Since there isn't any docbook code anymore upstream,
> > we can get rid of several output formats:
> >
> > - docbook/xml, html, html5 and list formats were used by
> >   the old build system;
> > - As ReST is text, there's not much sense on outputting
> >   on a different text format.
> >
> > After this patch, only man and rst output formats are
> > supported.  
> 
> FWIW,
> 
> Acked-by: Jani Nikula 

Thanks!

> Please do keep at least two output formats going forward. Otherwise the
> mechanisms of having more than one output format will bitrot and get
> conflated into the one output format.

Yeah, if we leave just one output format, some extra cleanup would be
needed.

Anyway, as we currently doesn't have other ways to generate manpages,
we should be keeping both ReST and man for now.

Thanks,
Mauro

Re: [media] vimc: API proposal, configuring the topology from user space

[Helen Koike]

Hi Hans,

Thanks for your review.

On 2017-07-28 10:39 AM, Hans Verkuil wrote:
> Hi Helen,
> 
> Finally after way too long I found some time to review this. See my comments
> below.
> 
> On 04/11/2017 12:53 AM, Helen Koike wrote:
>>
>> Hi,
>>
>> Continuing the discussion about the API of the vimc driver, I made some 
>> changes
>> based on the previous comments, please see below and let me know your 
>> opinion about it.
>>
>> Helen
>>
>> /***
>> Configfs considerations:
>> /
>> Informal definitions:
>>  subsystem: the root driver folder in user space (/configfs/vimc)
>>  item: aka a folder in user space
>>  attributes: aka files in the folder
>>  group: aka a folder that can contain subfolders (parent and child 
>> relation)
>>  default group: aka a subfolder that is created automatically when the 
>> "parent" folder is created
>>  it is not considered a child in terms of rmdir
>>
>> * Performing rmdir in a group will fail if it contain children that are 
>> not default groups, i.e, if the
>> folder contain subfolders that are default group, then it can be removed 
>> with rmdir, if the
>> subfolders were created with mkdir, then rmdir in the parent will fail.
>>
>> * Configfs has the notion of committable item but it is not implemented 
>> yet. A committable item is an item
>> that can be in one of two parent folders called: live and pending. The 
>> idea is to create and modify the item
>> in the pending directory and then to move the item through a rename to 
>> the live directory where
>> it can't be modified. This seems to be a nice feature for vimc, but as 
>> it is not available yet the
>> proposal below won't be based on this.
>>
>> * Groups can be dynamically created/destroyed by the driver whenever it 
>> wants. Afaik attributes can only
>> be created when the group or item is created and symlinks can only be 
>> create from user space, i.e, the
>> driver don't know how to create/destroy attributes or symlinks in anytime.
>>
>> /***
>> The API:
>> /
>>
>> In short, a topology like this one: http://goo.gl/Y7eUfu
>> Would look like this filesystem tree: https://goo.gl/mEOmOf
> 
> This mentions 'Yellow' lines, but since you dropped symlinks these no
> longer exist. You probably need to update the legend.
> 

Yes, thanks for noticing, I'll update when including it in the docs of
the API.

>>
>> v3 core changes:
>> - I removed the use of symlinks as I wans't able to see how to do it nicely.
>> - I use the names of the folders created by user space to retrieve 
>> information at mkdir time
>> - hotplug file in each entity
>> - hotplug file in each device
>> - reset file in each device
>>
>> * The /configfs/vimc subsystem
>> empty when the driver is loaded
> 
> I'm not sure about that. I think it would make sense that vimc when loaded
> would make one instance, unless otherwise told via a module option.

I don't think it really matters, the instance would be in unplugged
state anyway and it would need to be configured, but sure, we can add a
n_devs param as you proposed, no problem.

> 
> Something like this (taken from vivid):
> 
> parm:   n_devs: number of driver instances to create (uint)
> 
> By default this is 1, but can also be 0, 2, 3, etc.
> 
>>
>> * Create a device
>> Userspace can create a new vimc device with:
>>
>>  $ mkdir /configfs/vimc/any_name
>>  Example:
>>  $ mkdir /configfs/vimc/vimc0
>>  $ ls -l /configfs/vimc/vimc0
>>  hotplug
>>  reset
>>  entities/
>>  links/
>>
>> entities/ and links/ folder are default groups, thus they don't prevent 
>> rmdir vimc0/, but
>> rmdir will fail if it has any child inside entities/ or links/.
>> hotplug is used to plug and unplug the device, it can read "plugged" or 
>> "unplugged" and user can
>> write "plug" or "unplug" to change its state.
> 
> I would also support writing "plugged" and "unplugged". I.e. support both 
> variants.
> 

So it matches the values that you can read from the file, thanks for
this suggestion.

>> Changing hotplug state will never fail as the configfs tree will always 
>> be in a valid state.
>> reset is used to easily destroy all the topology without the need to 
>> walk through all the children
>> to perform rmdir, writing 1 to reset file will set hotplug to 
>> "unplugged" and erase all folders
>> under entities/ and links/.
>>
>> * Create an entity
>> Userspace can create a new entity with:
>>
>>  $ mkdir /configfs/vimc/vimc0/entities/:
>>  Example:
>>  $ mkdir /configfs/vimc/vimc0/entities/sensor:SensorA
>>  $ ls -l /configfs/vimc/vimc0/entities/sensor:SensorA
>>  hotplug
>>  pad:source:0/
>>
>> The name of the folder needs to be in the format : or it 
>> will be rejected, this allows the
>> creation of the right pads according to its role at mkdir time, 
>> eliminating the previously proposed role
>> and name files.
>> hotplug is 

Re: [RFT] [media] siano: FIX use-after-free in worker_thread

[Andrey Konovalov]

On Wed, Sep 27, 2017 at 8:38 PM, arvind  wrote:
>
>
> On Wednesday 27 September 2017 05:47 PM, Andrey Konovalov wrote:
>
> On Wed, Sep 27, 2017 at 2:00 PM, Andrey Konovalov 
> wrote:
>
> On Wed, Sep 27, 2017 at 11:21 AM, Arvind Yadav
>  wrote:
>
> If CONFIG_MEDIA_CONTROLLER_DVB is enable, We are not releasing
> media device and memory on any failure or disconnect a device.
>
> Adding structure media_device 'mdev' as part of 'smsusb_device_t'
> structure to make proper handle for media device.
> Now releasing a media device and memory on failure. It's allocate
> first in siano_media_device_register() and it should be freed last
> in smsusb_disconnect().
>
> Signed-off-by: Arvind Yadav 
>
> Hi Arvind,
>
> I've tried your patch and still see a crash.
>
> My guess is that here the issue is similar to the one in lan78xx,
> surb->wq work isn't shutdown properly.
>
> Hi Andrey,
>
> Yes, You are right. We have not flush work which is initialized in
> smsusb_onresponse(). I have send one more patch to you. I hope this will fix
> this issue. Thanks for your suggestion. :)

Hi Arvind,

Replied in the patch thread.

Thanks!

>
> ~arvind
>
> Thanks!
>
> gadgetfs: bound to dummy_udc driver
> usb 1-1: new full-speed USB device number 2 using dummy_hcd
> gadgetfs: connected
> gadgetfs: disconnected
> gadgetfs: connected
> usb 1-1: config 189 interface 0 altsetting 0 endpoint 0x9 has an
> invalid bInterval 0, changing to 4
> usb 1-1: New USB device found, idVendor=187f, idProduct=0100
> usb 1-1: New USB device strings: Mfr=0, Product=0, SerialNumber=0
> gadgetfs: configuration #189
> smsusb:smsusb_probe: board id=1, interface number 0
> smsusb:siano_media_device_register: media controller created
> smsusb:smsusb1_detectmode: product string not found
> smsmdtv:smscore_set_device_mode: return error code -22.
> smsmdtv:smscore_start_device: set device mode failed , rc -22
> smsusb:smsusb_init_device: smscore_start_device(...) failed
> smsusb:smsusb_onresponse: error, urb status -2, 0 bytes
> smsusb:smsusb_onresponse: error, urb status -71, 0 bytes
> smsusb:smsusb_onresponse: error, urb status -71, 0 bytes
> smsusb:smsusb_onresponse: error, urb status -71, 0 bytes
> smsusb:smsusb_onresponse: error, urb status -71, 0 bytes
> smsusb:smsusb_onresponse: error, urb status -71, 0 bytes
> smsusb:smsusb_onresponse: error, urb status -71, 0 bytes
> smsusb:smsusb_onresponse: error, urb status -71, 0 bytes
> smsusb:smsusb_onresponse: error, urb status -71, 0 bytes
> smsusb:smsusb_onresponse: error, urb status -71, 0 bytes
> smsusb:smsusb_probe: Device initialized with return code -22
> ==
> BUG: KASAN: use-after-free in worker_thread+0x1468/0x1850
> Read of size 8 at addr 88006a2b80f0 by task kworker/0:1/24
>
> CPU: 0 PID: 24 Comm: kworker/0:1 Not tainted
> 4.14.0-rc2-42660-g24b7bd59eec0-dirty #273
> Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS Bochs 01/01/2011
> Call Trace:
>  __dump_stack lib/dump_stack.c:16
>  dump_stack+0x292/0x395 lib/dump_stack.c:52
>  print_address_description+0x78/0x280 mm/kasan/report.c:252
>  kasan_report_error mm/kasan/report.c:351
>  kasan_report+0x23d/0x350 mm/kasan/report.c:409
>  __asan_report_load8_noabort+0x19/0x20 mm/kasan/report.c:430
>  worker_thread+0x1468/0x1850 kernel/workqueue.c:2251
>  kthread+0x3a1/0x470 kernel/kthread.c:231
>  ret_from_fork+0x2a/0x40 arch/x86/entry/entry_64.S:431
>
> Allocated by task 1846:
>  save_stack_trace+0x1b/0x20 arch/x86/kernel/stacktrace.c:59
>  save_stack+0x43/0xd0 mm/kasan/kasan.c:447
>  set_track mm/kasan/kasan.c:459
>  kasan_kmalloc+0xad/0xe0 mm/kasan/kasan.c:551
>  kmem_cache_alloc_trace+0x11e/0x2d0 mm/slub.c:2772
>  kmalloc ./include/linux/slab.h:493
>  kzalloc ./include/linux/slab.h:666
>  smsusb_init_device+0xd5/0xe40 drivers/media/usb/siano/smsusb.c:418
>  smsusb_probe+0x4f5/0xdc0 drivers/media/usb/siano/smsusb.c:580
>  usb_probe_interface+0x35d/0x8e0 drivers/usb/core/driver.c:361
>  really_probe drivers/base/dd.c:413
>  driver_probe_device+0x610/0xa00 drivers/base/dd.c:557
>  __device_attach_driver+0x230/0x290 drivers/base/dd.c:653
>  bus_for_each_drv+0x161/0x210 drivers/base/bus.c:463
>  __device_attach+0x26e/0x3d0 drivers/base/dd.c:710
>  device_initial_probe+0x1f/0x30 drivers/base/dd.c:757
>  bus_probe_device+0x1eb/0x290 drivers/base/bus.c:523
>  device_add+0xd0b/0x1660 drivers/base/core.c:1835
>  usb_set_configuration+0x104e/0x1870 drivers/usb/core/message.c:1932
>  generic_probe+0x73/0xe0 drivers/usb/core/generic.c:174
>  usb_probe_device+0xaf/0xe0 drivers/usb/core/driver.c:266
>  really_probe drivers/base/dd.c:413
>  driver_probe_device+0x610/0xa00 drivers/base/dd.c:557
>  __device_attach_driver+0x230/0x290 drivers/base/dd.c:653
>  bus_for_each_drv+0x161/0x210 drivers/base/bus.c:463
>  __device_attach+0x26e/0x3d0 drivers/base/dd.c:710
>  device_initial_probe+0x1f/0x30 

Re: [RFT v2] [media] siano: FIX use-after-free in worker_thread

[Andrey Konovalov]

On Wed, Sep 27, 2017 at 8:32 PM, Arvind Yadav  wrote:
> Call flush_work() on failure and disconnect. Work initialize and schedule
> in smsusb_onresponse(). it should be freed in smsusb_stop_streaming().
>
> Signed-off-by: Arvind Yadav 

Hi Arvind,

This patch fixes the issue with flush_work() missing, but exposes
another one. smsusb_init_device() initializes urbs and submits them in
smsusb_start_streaming(). However if smscore_start_device() fails,
smsusb_term_device() frees the urbs by freeing smsusb_device_t. The
urbs however still remain submitted, which causes another
use-after-free.

==
BUG: KASAN: use-after-free in dummy_timer+0x3076/0x3970
Read of size 4 at addr 88006b86b348 by task swapper/1/0

CPU: 1 PID: 0 Comm: swapper/1 Not tainted
4.14.0-rc2-42664-gaf7d1481b3cb-dirty #292
Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS Bochs 01/01/2011
Call Trace:
 
 __dump_stack lib/dump_stack.c:16
 dump_stack+0x292/0x395 lib/dump_stack.c:52
 print_address_description+0x78/0x280 mm/kasan/report.c:252
 kasan_report_error mm/kasan/report.c:351
 kasan_report+0x23d/0x350 mm/kasan/report.c:409
 __asan_report_load4_noabort+0x19/0x20 mm/kasan/report.c:429
 dummy_timer+0x3076/0x3970 drivers/usb/gadget/udc/dummy_hcd.c:1791
 call_timer_fn+0x2a2/0x940 kernel/time/timer.c:1281
 expire_timers kernel/time/timer.c:1320
 __run_timers+0x87f/0xd40 kernel/time/timer.c:1620
 run_timer_softirq+0x83/0x140 kernel/time/timer.c:1646
 __do_softirq+0x2ee/0xc0f kernel/softirq.c:284
 invoke_softirq kernel/softirq.c:364
 irq_exit+0x171/0x1a0 kernel/softirq.c:405
 exiting_irq ./arch/x86/include/asm/apic.h:638
 smp_apic_timer_interrupt+0x2b9/0x8d0 arch/x86/kernel/apic/apic.c:1048
 apic_timer_interrupt+0x9d/0xb0
 
RIP: 0010:native_safe_halt+0x6/0x10 ./arch/x86/include/asm/irqflags.h:53
RSP: 0018:88006be87b90 EFLAGS: 0282 ORIG_RAX: ff10
RAX: dc20 RBX: 11000d7d0f76 RCX: 
RDX:  RSI: 0001 RDI: 88006be6ba64
RBP: 88006be87b90 R08: 813d3301 R09: 
R10:  R11:  R12: 11000d7d0f82
R13: 88006be87cd0 R14: 86fc59c8 R15: 
 arch_safe_halt ./arch/x86/include/asm/paravirt.h:93
 default_idle+0x127/0x690 arch/x86/kernel/process.c:341
 arch_cpu_idle+0xf/0x20 arch/x86/kernel/process.c:332
 default_idle_call+0x3b/0x60 kernel/sched/idle.c:98
 cpuidle_idle_call kernel/sched/idle.c:156
 do_idle+0x33a/0x410 kernel/sched/idle.c:246
 cpu_startup_entry+0x1d/0x20 kernel/sched/idle.c:351
 start_secondary+0x3de/0x500 arch/x86/kernel/smpboot.c:278
 secondary_startup_64+0xa5/0xa5 arch/x86/kernel/head_64.S:235

Allocated by task 40:
 save_stack_trace+0x1b/0x20 arch/x86/kernel/stacktrace.c:59
 save_stack+0x43/0xd0 mm/kasan/kasan.c:447
 set_track mm/kasan/kasan.c:459
 kasan_kmalloc+0xad/0xe0 mm/kasan/kasan.c:551
 kmem_cache_alloc_trace+0x11e/0x2d0 mm/slub.c:2772
 kmalloc ./include/linux/slab.h:493
 kzalloc ./include/linux/slab.h:666
 smsusb_init_device+0xd5/0xd10 drivers/media/usb/siano/smsusb.c:409
 smsusb_probe+0x4f5/0xdc0 drivers/media/usb/siano/smsusb.c:573
 usb_probe_interface+0x35d/0x8e0 drivers/usb/core/driver.c:361
 really_probe drivers/base/dd.c:413
 driver_probe_device+0x610/0xa00 drivers/base/dd.c:557
 __device_attach_driver+0x230/0x290 drivers/base/dd.c:653
 bus_for_each_drv+0x161/0x210 drivers/base/bus.c:463
 __device_attach+0x26e/0x3d0 drivers/base/dd.c:710
 device_initial_probe+0x1f/0x30 drivers/base/dd.c:757
 bus_probe_device+0x1eb/0x290 drivers/base/bus.c:523
 device_add+0xd0b/0x1660 drivers/base/core.c:1835
 usb_set_configuration+0x104e/0x1870 drivers/usb/core/message.c:1932
 generic_probe+0x73/0xe0 drivers/usb/core/generic.c:174
 usb_probe_device+0xaf/0xe0 drivers/usb/core/driver.c:266
 really_probe drivers/base/dd.c:413
 driver_probe_device+0x610/0xa00 drivers/base/dd.c:557
 __device_attach_driver+0x230/0x290 drivers/base/dd.c:653
 bus_for_each_drv+0x161/0x210 drivers/base/bus.c:463
 __device_attach+0x26e/0x3d0 drivers/base/dd.c:710
 device_initial_probe+0x1f/0x30 drivers/base/dd.c:757
 bus_probe_device+0x1eb/0x290 drivers/base/bus.c:523
 device_add+0xd0b/0x1660 drivers/base/core.c:1835
 usb_new_device+0x7b8/0x1020 drivers/usb/core/hub.c:2457
 hub_port_connect drivers/usb/core/hub.c:4903
 hub_port_connect_change drivers/usb/core/hub.c:5009
 port_event drivers/usb/core/hub.c:5115
 hub_event+0x194d/0x3740 drivers/usb/core/hub.c:5195
 process_one_work+0xc7f/0x1db0 kernel/workqueue.c:2119
 worker_thread+0x221/0x1850 kernel/workqueue.c:2253
 kthread+0x3a1/0x470 kernel/kthread.c:231
 ret_from_fork+0x2a/0x40 arch/x86/entry/entry_64.S:431

Freed by task 40:
 save_stack_trace+0x1b/0x20 arch/x86/kernel/stacktrace.c:59
 save_stack+0x43/0xd0 mm/kasan/kasan.c:447
 set_track mm/kasan/kasan.c:459
 kasan_slab_free+0x72/0xc0 mm/kasan/kasan.c:524
 slab_free_hook 

[RFT v2] [media] siano: FIX use-after-free in worker_thread

[Arvind Yadav]

Call flush_work() on failure and disconnect. Work initialize and schedule
in smsusb_onresponse(). it should be freed in smsusb_stop_streaming().

Signed-off-by: Arvind Yadav 
---
This bug report by Andrey Konovalov "usb/media/smsusb: use-after-free in
worker_thread".
changes in v2 : 
  call flush_work() in smsusb_stop_streaming().

 drivers/media/usb/siano/smsusb.c | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/drivers/media/usb/siano/smsusb.c b/drivers/media/usb/siano/smsusb.c
index 8c1f926..8142ba4 100644
--- a/drivers/media/usb/siano/smsusb.c
+++ b/drivers/media/usb/siano/smsusb.c
@@ -192,6 +192,8 @@ static void smsusb_stop_streaming(struct smsusb_device_t 
*dev)
for (i = 0; i < MAX_URBS; i++) {
usb_kill_urb(>surbs[i].urb);
 
+   flush_work(>surbs[i].wq);
+
if (dev->surbs[i].cb) {
smscore_putbuffer(dev->coredev, dev->surbs[i].cb);
dev->surbs[i].cb = NULL;
-- 
2.7.4

Re: [PATCH] vimc: add test_pattern and h/vflip controls to the sensor

[Helen Koike]

Hi Hans,

Thanks for your patch and sorry for my late reply.
Please see my comments and questions below

On 2017-07-28 07:23 AM, Hans Verkuil wrote:
> Add support for the test_pattern control and the h/vflip controls.
> 
> This makes it possible to switch to more interesting test patterns and to
> test control handling in v4l-subdevs.
> 
> There are more tpg-related controls that can be added, but this is a good
> start.
> 
> Signed-off-by: Hans Verkuil 
> ---
> diff --git a/drivers/media/platform/vimc/vimc-common.h 
> b/drivers/media/platform/vimc/vimc-common.h
> index dca528a316e7..2e9981b18166 100644
> --- a/drivers/media/platform/vimc/vimc-common.h
> +++ b/drivers/media/platform/vimc/vimc-common.h
> @@ -22,6 +22,11 @@
>  #include 
>  #include 
> 
> +/* VIMC-specific controls */
> +#define VIMC_CID_VIMC_BASE   (0x00f0 | 0xf000)
> +#define VIMC_CID_VIMC_CLASS  (0x00f0 | 1)

Why this values, shouldn't we use a derivative from
V4L2_CID_PRIVATE_BASE for custom controls? Or can we use random values?

> +#define VIMC_CID_TEST_PATTERN(VIMC_CID_VIMC_BASE + 0)
> +
>  #define VIMC_FRAME_MAX_WIDTH 4096
>  #define VIMC_FRAME_MAX_HEIGHT 2160
>  #define VIMC_FRAME_MIN_WIDTH 16
> diff --git a/drivers/media/platform/vimc/vimc-sensor.c 
> b/drivers/media/platform/vimc/vimc-sensor.c
> index 615c2b18dcfc..532097566b27 100644
> --- a/drivers/media/platform/vimc/vimc-sensor.c
> +++ b/drivers/media/platform/vimc/vimc-sensor.c
> @@ -22,6 +22,7 @@
>  #include 
>  #include 
>  #include 
> +#include 
>  #include 
>  #include 
> 
> @@ -38,6 +39,7 @@ struct vimc_sen_device {
>   u8 *frame;
>   /* The active format */
>   struct v4l2_mbus_framefmt mbus_format;
> + struct v4l2_ctrl_handler hdl;
>  };
> 
>  static const struct v4l2_mbus_framefmt fmt_default = {
> @@ -291,6 +293,31 @@ static const struct v4l2_subdev_ops vimc_sen_ops = {
>   .video = _sen_video_ops,
>  };
> 
> +static int vimc_sen_s_ctrl(struct v4l2_ctrl *ctrl)
> +{
> + struct vimc_sen_device *vsen =
> + container_of(ctrl->handler, struct vimc_sen_device, hdl);
> +
> + switch (ctrl->id) {
> + case VIMC_CID_TEST_PATTERN:
> + tpg_s_pattern(>tpg, ctrl->val);
> + break;
> + case V4L2_CID_HFLIP:
> + tpg_s_hflip(>tpg, ctrl->val);
> + break;
> + case V4L2_CID_VFLIP:
> + tpg_s_vflip(>tpg, ctrl->val);
> + break;
> + default:
> + return -EINVAL;
> + }
> + return 0;
> +}
> +
> +static const struct v4l2_ctrl_ops vimc_sen_ctrl_ops = {
> + .s_ctrl = vimc_sen_s_ctrl,
> +};
> +
>  static void vimc_sen_comp_unbind(struct device *comp, struct device *master,
>void *master_data)
>  {
> @@ -299,10 +326,29 @@ static void vimc_sen_comp_unbind(struct device *comp, 
> struct device *master,
>   container_of(ved, struct vimc_sen_device, ved);
> 
>   vimc_ent_sd_unregister(ved, >sd);
> + v4l2_ctrl_handler_free(>hdl);
>   tpg_free(>tpg);
>   kfree(vsen);
>  }
> 
> +/* Image Processing Controls */
> +static const struct v4l2_ctrl_config vimc_sen_ctrl_class = {
> + .ops = _sen_ctrl_ops,
> + .flags = V4L2_CTRL_FLAG_READ_ONLY | V4L2_CTRL_FLAG_WRITE_ONLY,

I was wondering if it is really necessary to specify the ops and flags
in the class, as this is seems to me a meta control for the other
controls to be grouped in a class.

> + .id = VIMC_CID_VIMC_CLASS,
> + .name = "VIMC Controls",
> + .type = V4L2_CTRL_TYPE_CTRL_CLASS,
> +};
> +
> +static const struct v4l2_ctrl_config vimc_sen_ctrl_test_pattern = {
> + .ops = _sen_ctrl_ops,
> + .id = VIMC_CID_TEST_PATTERN,
> + .name = "Test Pattern",
> + .type = V4L2_CTRL_TYPE_MENU,
> + .max = TPG_PAT_NOISE,
> + .qmenu = tpg_pattern_strings,
> +};
> +
>  static int vimc_sen_comp_bind(struct device *comp, struct device *master,
> void *master_data)
>  {
> @@ -316,6 +362,20 @@ static int vimc_sen_comp_bind(struct device *comp, 
> struct device *master,
>   if (!vsen)
>   return -ENOMEM;
> 
> + v4l2_ctrl_handler_init(>hdl, 4);
> +
> + v4l2_ctrl_new_custom(>hdl, _sen_ctrl_class, NULL);
> + v4l2_ctrl_new_custom(>hdl, _sen_ctrl_test_pattern, NULL);
> + v4l2_ctrl_new_std(>hdl, _sen_ctrl_ops,
> + V4L2_CID_VFLIP, 0, 1, 1, 0);
> + v4l2_ctrl_new_std(>hdl, _sen_ctrl_ops,
> + V4L2_CID_HFLIP, 0, 1, 1, 0);

Shouldn't we test the return values of the above functions? Or maybe not
because we should know what we are doing and this doesn't depend on the
user space.

> + vsen->sd.ctrl_handler = >hdl;
> + if (vsen->hdl.error) {
> + ret = vsen->hdl.error;
> + goto err_free_vsen;
> + }
> +
>   /* Initialize ved and sd */
>   ret = vimc_ent_sd_register(>ved, >sd, v4l2_dev,
>  

[PATCH v1 08/13] staging: atomisp: Remove ->power_ctrl() callback

[Andy Shevchenko]

There is redundant callback which does nothing in upstreamed version of
the driver.

Remove it along with user call places.

Mostly done with help of coccinelle.

Signed-off-by: Andy Shevchenko 
---
 drivers/staging/media/atomisp/i2c/gc0310.c | 4 
 drivers/staging/media/atomisp/i2c/gc2235.c | 4 
 drivers/staging/media/atomisp/i2c/mt9m114.c| 4 
 drivers/staging/media/atomisp/i2c/ov2680.c | 4 
 drivers/staging/media/atomisp/i2c/ov2722.c | 4 
 drivers/staging/media/atomisp/i2c/ov5693/ov5693.c  | 4 
 drivers/staging/media/atomisp/i2c/ov8858.c | 4 
 drivers/staging/media/atomisp/include/linux/atomisp_platform.h | 8 
 8 files changed, 4 insertions(+), 32 deletions(-)

diff --git a/drivers/staging/media/atomisp/i2c/gc0310.c 
b/drivers/staging/media/atomisp/i2c/gc0310.c
index 672a28c060f6..b6b1956293c0 100644
--- a/drivers/staging/media/atomisp/i2c/gc0310.c
+++ b/drivers/staging/media/atomisp/i2c/gc0310.c
@@ -737,10 +737,6 @@ static int power_ctrl(struct v4l2_subdev *sd, bool flag)
if (!dev || !dev->platform_data)
return -ENODEV;
 
-   /* Non-gmin platforms use the legacy callback */
-   if (dev->platform_data->power_ctrl)
-   return dev->platform_data->power_ctrl(sd, flag);
-
if (flag) {
/* The upstream module driver (written to Crystal
 * Cove) had this logic to pulse the rails low first.
diff --git a/drivers/staging/media/atomisp/i2c/gc2235.c 
b/drivers/staging/media/atomisp/i2c/gc2235.c
index 81b23b55f73a..46e063dcdc19 100644
--- a/drivers/staging/media/atomisp/i2c/gc2235.c
+++ b/drivers/staging/media/atomisp/i2c/gc2235.c
@@ -547,10 +547,6 @@ static int power_ctrl(struct v4l2_subdev *sd, bool flag)
if (!dev || !dev->platform_data)
return -ENODEV;
 
-   /* Non-gmin platforms use the legacy callback */
-   if (dev->platform_data->power_ctrl)
-   return dev->platform_data->power_ctrl(sd, flag);
-
if (flag) {
ret = dev->platform_data->v1p8_ctrl(sd, 1);
usleep_range(60, 90);
diff --git a/drivers/staging/media/atomisp/i2c/mt9m114.c 
b/drivers/staging/media/atomisp/i2c/mt9m114.c
index 4968deae2525..950627efa977 100644
--- a/drivers/staging/media/atomisp/i2c/mt9m114.c
+++ b/drivers/staging/media/atomisp/i2c/mt9m114.c
@@ -454,10 +454,6 @@ static int power_ctrl(struct v4l2_subdev *sd, bool flag)
if (!dev || !dev->platform_data)
return -ENODEV;
 
-   /* Non-gmin platforms use the legacy callback */
-   if (dev->platform_data->power_ctrl)
-   return dev->platform_data->power_ctrl(sd, flag);
-
if (flag) {
ret = dev->platform_data->v2p8_ctrl(sd, 1);
if (ret == 0) {
diff --git a/drivers/staging/media/atomisp/i2c/ov2680.c 
b/drivers/staging/media/atomisp/i2c/ov2680.c
index 162150055770..9279246cf0b1 100644
--- a/drivers/staging/media/atomisp/i2c/ov2680.c
+++ b/drivers/staging/media/atomisp/i2c/ov2680.c
@@ -846,10 +846,6 @@ static int power_ctrl(struct v4l2_subdev *sd, bool flag)
if (!dev || !dev->platform_data)
return -ENODEV;
 
-   /* Non-gmin platforms use the legacy callback */
-   if (dev->platform_data->power_ctrl)
-   return dev->platform_data->power_ctrl(sd, flag);
-
if (flag) {
ret |= dev->platform_data->v1p8_ctrl(sd, 1);
ret |= dev->platform_data->v2p8_ctrl(sd, 1);
diff --git a/drivers/staging/media/atomisp/i2c/ov2722.c 
b/drivers/staging/media/atomisp/i2c/ov2722.c
index 6c1057542aea..39296a784162 100644
--- a/drivers/staging/media/atomisp/i2c/ov2722.c
+++ b/drivers/staging/media/atomisp/i2c/ov2722.c
@@ -650,10 +650,6 @@ static int power_ctrl(struct v4l2_subdev *sd, bool flag)
if (!dev || !dev->platform_data)
return -ENODEV;
 
-   /* Non-gmin platforms use the legacy callback */
-   if (dev->platform_data->power_ctrl)
-   return dev->platform_data->power_ctrl(sd, flag);
-
if (flag) {
ret = dev->platform_data->v1p8_ctrl(sd, 1);
if (ret == 0) {
diff --git a/drivers/staging/media/atomisp/i2c/ov5693/ov5693.c 
b/drivers/staging/media/atomisp/i2c/ov5693/ov5693.c
index 8d5b4c3ea55d..33651ec0218f 100644
--- a/drivers/staging/media/atomisp/i2c/ov5693/ov5693.c
+++ b/drivers/staging/media/atomisp/i2c/ov5693/ov5693.c
@@ -1297,10 +1297,6 @@ static int power_ctrl(struct v4l2_subdev *sd, bool flag)
if (!dev || !dev->platform_data)
return -ENODEV;
 
-   /* Non-gmin platforms use the legacy callback */
-   if (dev->platform_data->power_ctrl)
-   return dev->platform_data->power_ctrl(sd, flag);
-
/* This driver assumes "internal DVDD, PWDNB tied to DOVDD".
 * In 

[PATCH v1 07/13] staging: atomisp: Remove ->gpio_ctrl() callback

[Andy Shevchenko]

There is redundant callback which does nothing in upstreamed version of
the driver.

Remove it along with user call places.

Mostly done with help of coccinelle.

Signed-off-by: Andy Shevchenko 
---
 drivers/staging/media/atomisp/i2c/gc0310.c | 4 
 drivers/staging/media/atomisp/i2c/gc2235.c | 4 
 drivers/staging/media/atomisp/i2c/mt9m114.c| 4 
 drivers/staging/media/atomisp/i2c/ov2680.c | 4 
 drivers/staging/media/atomisp/i2c/ov2722.c | 4 
 drivers/staging/media/atomisp/i2c/ov5693/ov5693.c  | 4 
 drivers/staging/media/atomisp/i2c/ov8858.c | 4 
 drivers/staging/media/atomisp/include/linux/atomisp_platform.h | 2 --
 8 files changed, 30 deletions(-)

diff --git a/drivers/staging/media/atomisp/i2c/gc0310.c 
b/drivers/staging/media/atomisp/i2c/gc0310.c
index 0e6fcf44b656..672a28c060f6 100644
--- a/drivers/staging/media/atomisp/i2c/gc0310.c
+++ b/drivers/staging/media/atomisp/i2c/gc0310.c
@@ -771,10 +771,6 @@ static int gpio_ctrl(struct v4l2_subdev *sd, bool flag)
if (!dev || !dev->platform_data)
return -ENODEV;
 
-   /* Non-gmin platforms use the legacy callback */
-   if (dev->platform_data->gpio_ctrl)
-   return dev->platform_data->gpio_ctrl(sd, flag);
-
/* GPIO0 == "reset" (active low), GPIO1 == "power down" */
if (flag) {
/* Pulse reset, then release power down */
diff --git a/drivers/staging/media/atomisp/i2c/gc2235.c 
b/drivers/staging/media/atomisp/i2c/gc2235.c
index 94b93ccc6aeb..81b23b55f73a 100644
--- a/drivers/staging/media/atomisp/i2c/gc2235.c
+++ b/drivers/staging/media/atomisp/i2c/gc2235.c
@@ -571,10 +571,6 @@ static int gpio_ctrl(struct v4l2_subdev *sd, bool flag)
if (!dev || !dev->platform_data)
return -ENODEV;
 
-   /* Non-gmin platforms use the legacy callback */
-   if (dev->platform_data->gpio_ctrl)
-   return dev->platform_data->gpio_ctrl(sd, flag);
-
ret |= dev->platform_data->gpio1_ctrl(sd, !flag);
usleep_range(60, 90);
return dev->platform_data->gpio0_ctrl(sd, flag);
diff --git a/drivers/staging/media/atomisp/i2c/mt9m114.c 
b/drivers/staging/media/atomisp/i2c/mt9m114.c
index 4ac1ad045283..4968deae2525 100644
--- a/drivers/staging/media/atomisp/i2c/mt9m114.c
+++ b/drivers/staging/media/atomisp/i2c/mt9m114.c
@@ -480,10 +480,6 @@ static int gpio_ctrl(struct v4l2_subdev *sd, bool flag)
if (!dev || !dev->platform_data)
return -ENODEV;
 
-   /* Non-gmin platforms use the legacy callback */
-   if (dev->platform_data->gpio_ctrl)
-   return dev->platform_data->gpio_ctrl(sd, flag);
-
/* Note: current modules wire only one GPIO signal (RESET#),
 * but the schematic wires up two to the connector.  BIOS
 * versions have been unfortunately inconsistent with which
diff --git a/drivers/staging/media/atomisp/i2c/ov2680.c 
b/drivers/staging/media/atomisp/i2c/ov2680.c
index a42adeeb748c..162150055770 100644
--- a/drivers/staging/media/atomisp/i2c/ov2680.c
+++ b/drivers/staging/media/atomisp/i2c/ov2680.c
@@ -871,10 +871,6 @@ static int gpio_ctrl(struct v4l2_subdev *sd, bool flag)
if (!dev || !dev->platform_data)
return -ENODEV;
 
-   /* Non-gmin platforms use the legacy callback */
-   if (dev->platform_data->gpio_ctrl)
-   return dev->platform_data->gpio_ctrl(sd, flag);
-
/* The OV2680 documents only one GPIO input (#XSHUTDN), but
 * existing integrations often wire two (reset/power_down)
 * because that is the way other sensors work.  There is no
diff --git a/drivers/staging/media/atomisp/i2c/ov2722.c 
b/drivers/staging/media/atomisp/i2c/ov2722.c
index 1b7012f47303..6c1057542aea 100644
--- a/drivers/staging/media/atomisp/i2c/ov2722.c
+++ b/drivers/staging/media/atomisp/i2c/ov2722.c
@@ -677,10 +677,6 @@ static int gpio_ctrl(struct v4l2_subdev *sd, bool flag)
if (!dev || !dev->platform_data)
return -ENODEV;
 
-   /* Non-gmin platforms use the legacy callback */
-   if (dev->platform_data->gpio_ctrl)
-   return dev->platform_data->gpio_ctrl(sd, flag);
-
/* Note: the GPIO order is asymmetric: always RESET#
 * before PWDN# when turning it on or off.
 */
diff --git a/drivers/staging/media/atomisp/i2c/ov5693/ov5693.c 
b/drivers/staging/media/atomisp/i2c/ov5693/ov5693.c
index 357821af4db0..8d5b4c3ea55d 100644
--- a/drivers/staging/media/atomisp/i2c/ov5693/ov5693.c
+++ b/drivers/staging/media/atomisp/i2c/ov5693/ov5693.c
@@ -1332,10 +1332,6 @@ static int gpio_ctrl(struct v4l2_subdev *sd, bool flag)
if (!dev || !dev->platform_data)
return -ENODEV;
 
-   /* Non-gmin platforms use the legacy callback */
-   if (dev->platform_data->gpio_ctrl)
-  

[PATCH v1 10/13] staging: atomisp: Remove Gmin dead code #1

[Andy Shevchenko]

struct camera_af_platform_data and bound functions are not used anywhere.

Signed-off-by: Andy Shevchenko 
---
 .../media/atomisp/include/linux/atomisp_platform.h |  6 --
 .../platform/intel-mid/atomisp_gmin_platform.c | 22 --
 2 files changed, 28 deletions(-)

diff --git a/drivers/staging/media/atomisp/include/linux/atomisp_platform.h 
b/drivers/staging/media/atomisp/include/linux/atomisp_platform.h
index a8c1825e1d0d..2dae4935ed75 100644
--- a/drivers/staging/media/atomisp/include/linux/atomisp_platform.h
+++ b/drivers/staging/media/atomisp/include/linux/atomisp_platform.h
@@ -221,12 +221,6 @@ struct camera_sensor_platform_data {
char *module_id);
 };
 
-struct camera_af_platform_data {
-   int (*power_ctrl)(struct v4l2_subdev *subdev, int flag);
-};
-
-const struct camera_af_platform_data *camera_get_af_platform_data(void);
-
 struct camera_mipi_info {
enum atomisp_camera_portport;
unsigned intnum_lanes;
diff --git 
a/drivers/staging/media/atomisp/platform/intel-mid/atomisp_gmin_platform.c 
b/drivers/staging/media/atomisp/platform/intel-mid/atomisp_gmin_platform.c
index 3f7814a3a5a4..d9db0b13f506 100644
--- a/drivers/staging/media/atomisp/platform/intel-mid/atomisp_gmin_platform.c
+++ b/drivers/staging/media/atomisp/platform/intel-mid/atomisp_gmin_platform.c
@@ -126,28 +126,6 @@ static int af_power_ctrl(struct v4l2_subdev *subdev, int 
flag)
return 0;
 }
 
-/*
- * Used in a handful of modules.  Focus motor control, I think.  Note
- * that there is no configurability in the API, so this needs to be
- * fixed where it is used.
- *
- * struct camera_af_platform_data {
- * int (*power_ctrl)(struct v4l2_subdev *subdev, int flag);
- * };
- *
- * Note that the implementation in MCG platform_camera.c is stubbed
- * out anyway (i.e. returns zero from the callback) on BYT.  So
- * neither needed on gmin platforms or supported upstream.
- */
-const struct camera_af_platform_data *camera_get_af_platform_data(void)
-{
-   static struct camera_af_platform_data afpd = {
-   .power_ctrl = af_power_ctrl,
-   };
-   return 
-}
-EXPORT_SYMBOL_GPL(camera_get_af_platform_data);
-
 int atomisp_register_i2c_module(struct v4l2_subdev *subdev,
struct camera_sensor_platform_data *plat_data,
enum intel_v4l2_subdev_type type)
-- 
2.14.1

[PATCH v1 03/13] staging: atomisp: Use module_i2c_driver() macro

[Andy Shevchenko]

This is done using coccinelle semantic patch:

//
@a@
identifier f, x;
@@
-static f(...) { return i2c_add_driver(); }

@b depends on a@
identifier e, a.x;
@@
-static e(...) { i2c_del_driver(); }

@c depends on a && b@
identifier a.f;
declarer name module_init;
@@
-module_init(f);

@d depends on a && b && c@
identifier b.e, a.x;
declarer name module_exit;
declarer name module_i2c_driver;
@@
-module_exit(e);
+module_i2c_driver(x);
//

Signed-off-by: Andy Shevchenko 
---
 drivers/staging/media/atomisp/i2c/gc0310.c| 15 +--
 drivers/staging/media/atomisp/i2c/gc2235.c| 15 +--
 drivers/staging/media/atomisp/i2c/lm3554.c| 13 +
 drivers/staging/media/atomisp/i2c/mt9m114.c   | 14 +-
 drivers/staging/media/atomisp/i2c/ov2680.c| 16 +---
 drivers/staging/media/atomisp/i2c/ov2722.c| 15 +--
 drivers/staging/media/atomisp/i2c/ov5693/ov5693.c | 15 +--
 drivers/staging/media/atomisp/i2c/ov8858.c| 14 +-
 8 files changed, 8 insertions(+), 109 deletions(-)

diff --git a/drivers/staging/media/atomisp/i2c/gc0310.c 
b/drivers/staging/media/atomisp/i2c/gc0310.c
index 35ed51ffe944..730fa5dd80f5 100644
--- a/drivers/staging/media/atomisp/i2c/gc0310.c
+++ b/drivers/staging/media/atomisp/i2c/gc0310.c
@@ -1470,20 +1470,7 @@ static struct i2c_driver gc0310_driver = {
.remove = gc0310_remove,
.id_table = gc0310_id,
 };
-
-static int init_gc0310(void)
-{
-   return i2c_add_driver(_driver);
-}
-
-static void exit_gc0310(void)
-{
-
-   i2c_del_driver(_driver);
-}
-
-module_init(init_gc0310);
-module_exit(exit_gc0310);
+module_i2c_driver(gc0310_driver);
 
 MODULE_AUTHOR("Lai, Angie ");
 MODULE_DESCRIPTION("A low-level driver for GalaxyCore GC0310 sensors");
diff --git a/drivers/staging/media/atomisp/i2c/gc2235.c 
b/drivers/staging/media/atomisp/i2c/gc2235.c
index e43d31ea9676..6d4a432b6bae 100644
--- a/drivers/staging/media/atomisp/i2c/gc2235.c
+++ b/drivers/staging/media/atomisp/i2c/gc2235.c
@@ -1199,20 +1199,7 @@ static struct i2c_driver gc2235_driver = {
.remove = gc2235_remove,
.id_table = gc2235_id,
 };
-
-static int init_gc2235(void)
-{
-   return i2c_add_driver(_driver);
-}
-
-static void exit_gc2235(void)
-{
-
-   i2c_del_driver(_driver);
-}
-
-module_init(init_gc2235);
-module_exit(exit_gc2235);
+module_i2c_driver(gc2235_driver);
 
 MODULE_AUTHOR("Shuguang Gong ");
 MODULE_DESCRIPTION("A low-level driver for GC2235 sensors");
diff --git a/drivers/staging/media/atomisp/i2c/lm3554.c 
b/drivers/staging/media/atomisp/i2c/lm3554.c
index 679176f7c542..5424685eb447 100644
--- a/drivers/staging/media/atomisp/i2c/lm3554.c
+++ b/drivers/staging/media/atomisp/i2c/lm3554.c
@@ -991,19 +991,8 @@ static struct i2c_driver lm3554_driver = {
.remove = lm3554_remove,
.id_table = lm3554_id,
 };
+module_i2c_driver(lm3554_driver);
 
-static __init int init_lm3554(void)
-{
-   return i2c_add_driver(_driver);
-}
-
-static __exit void exit_lm3554(void)
-{
-   i2c_del_driver(_driver);
-}
-
-module_init(init_lm3554);
-module_exit(exit_lm3554);
 MODULE_AUTHOR("Jing Tao ");
 MODULE_DESCRIPTION("LED flash driver for LM3554");
 MODULE_LICENSE("GPL");
diff --git a/drivers/staging/media/atomisp/i2c/mt9m114.c 
b/drivers/staging/media/atomisp/i2c/mt9m114.c
index 3c837cb8859c..14fe39f9feb6 100644
--- a/drivers/staging/media/atomisp/i2c/mt9m114.c
+++ b/drivers/staging/media/atomisp/i2c/mt9m114.c
@@ -1945,19 +1945,7 @@ static struct i2c_driver mt9m114_driver = {
.remove = mt9m114_remove,
.id_table = mt9m114_id,
 };
-
-static __init int init_mt9m114(void)
-{
-   return i2c_add_driver(_driver);
-}
-
-static __exit void exit_mt9m114(void)
-{
-   i2c_del_driver(_driver);
-}
-
-module_init(init_mt9m114);
-module_exit(exit_mt9m114);
+module_i2c_driver(mt9m114_driver);
 
 MODULE_AUTHOR("Shuguang Gong ");
 MODULE_LICENSE("GPL");
diff --git a/drivers/staging/media/atomisp/i2c/ov2680.c 
b/drivers/staging/media/atomisp/i2c/ov2680.c
index 51b7d61df0f5..0dce3c03b2cd 100644
--- a/drivers/staging/media/atomisp/i2c/ov2680.c
+++ b/drivers/staging/media/atomisp/i2c/ov2680.c
@@ -1527,7 +1527,6 @@ MODULE_DEVICE_TABLE(acpi, ov2680_acpi_match);
 MODULE_DEVICE_TABLE(i2c, ov2680_id);
 static struct i2c_driver ov2680_driver = {
.driver = {
-   .owner = THIS_MODULE,
.name = OV2680_NAME,
.acpi_match_table = ACPI_PTR(ov2680_acpi_match),
 
@@ -1536,20 +1535,7 @@ static struct i2c_driver ov2680_driver = {
.remove = ov2680_remove,
.id_table = ov2680_id,
 };
-
-static int init_ov2680(void)
-{
-   return i2c_add_driver(_driver);
-}
-
-static void exit_ov2680(void)
-{
-
-   i2c_del_driver(_driver);
-}
-
-module_init(init_ov2680);
-module_exit(exit_ov2680);

[PATCH v1 09/13] staging: atomisp: Remove unused members of camera_sensor_platform_data

[Andy Shevchenko]

Remove unused members along with dead code.

Mostly done with help of coccinelle.

Signed-off-by: Andy Shevchenko 
---
 drivers/staging/media/atomisp/i2c/gc0310.c  | 13 -
 drivers/staging/media/atomisp/i2c/gc2235.c  | 13 -
 drivers/staging/media/atomisp/i2c/mt9m114.c |  9 -
 drivers/staging/media/atomisp/i2c/ov2722.c  | 13 -
 drivers/staging/media/atomisp/i2c/ov8858.c  | 13 -
 .../staging/media/atomisp/include/linux/atomisp_platform.h  |  5 -
 drivers/staging/media/atomisp/pci/atomisp2/atomisp_v4l2.c   |  9 +
 .../atomisp/platform/intel-mid/atomisp_gmin_platform.c  | 12 
 8 files changed, 1 insertion(+), 86 deletions(-)

diff --git a/drivers/staging/media/atomisp/i2c/gc0310.c 
b/drivers/staging/media/atomisp/i2c/gc0310.c
index b6b1956293c0..0b32c8a94e5c 100644
--- a/drivers/staging/media/atomisp/i2c/gc0310.c
+++ b/drivers/staging/media/atomisp/i2c/gc0310.c
@@ -1156,13 +1156,6 @@ static int gc0310_s_config(struct v4l2_subdev *sd,
(struct camera_sensor_platform_data *)platform_data;
 
mutex_lock(>input_lock);
-   if (dev->platform_data->platform_init) {
-   ret = dev->platform_data->platform_init(client);
-   if (ret) {
-   dev_err(>dev, "platform init err\n");
-   goto platform_init_failed;
-   }
-   }
/* power off the module, then power on it in future
 * as first power on by board may not fulfill the
 * power on sequqence needed by the module
@@ -1207,9 +1200,6 @@ static int gc0310_s_config(struct v4l2_subdev *sd,
power_down(sd);
dev_err(>dev, "sensor power-gating failed\n");
 fail_power_off:
-   if (dev->platform_data->platform_deinit)
-   dev->platform_data->platform_deinit();
-platform_init_failed:
mutex_unlock(>input_lock);
return ret;
 }
@@ -1353,9 +1343,6 @@ static int gc0310_remove(struct i2c_client *client)
struct gc0310_device *dev = to_gc0310_sensor(sd);
dev_dbg(>dev, "gc0310_remove...\n");
 
-   if (dev->platform_data->platform_deinit)
-   dev->platform_data->platform_deinit();
-
dev->platform_data->csi_cfg(sd, 0);
 
v4l2_device_unregister_subdev(sd);
diff --git a/drivers/staging/media/atomisp/i2c/gc2235.c 
b/drivers/staging/media/atomisp/i2c/gc2235.c
index 46e063dcdc19..bcfcdc220803 100644
--- a/drivers/staging/media/atomisp/i2c/gc2235.c
+++ b/drivers/staging/media/atomisp/i2c/gc2235.c
@@ -897,13 +897,6 @@ static int gc2235_s_config(struct v4l2_subdev *sd,
(struct camera_sensor_platform_data *)platform_data;
 
mutex_lock(>input_lock);
-   if (dev->platform_data->platform_init) {
-   ret = dev->platform_data->platform_init(client);
-   if (ret) {
-   dev_err(>dev, "platform init err\n");
-   goto platform_init_failed;
-   }
-   }
/* power off the module, then power on it in future
 * as first power on by board may not fulfill the
 * power on sequqence needed by the module
@@ -947,9 +940,6 @@ static int gc2235_s_config(struct v4l2_subdev *sd,
power_down(sd);
dev_err(>dev, "sensor power-gating failed\n");
 fail_power_off:
-   if (dev->platform_data->platform_deinit)
-   dev->platform_data->platform_deinit();
-platform_init_failed:
mutex_unlock(>input_lock);
return ret;
 }
@@ -1092,9 +1082,6 @@ static int gc2235_remove(struct i2c_client *client)
struct gc2235_device *dev = to_gc2235_sensor(sd);
dev_dbg(>dev, "gc2235_remove...\n");
 
-   if (dev->platform_data->platform_deinit)
-   dev->platform_data->platform_deinit();
-
dev->platform_data->csi_cfg(sd, 0);
 
v4l2_device_unregister_subdev(sd);
diff --git a/drivers/staging/media/atomisp/i2c/mt9m114.c 
b/drivers/staging/media/atomisp/i2c/mt9m114.c
index 950627efa977..09018d5ccaf2 100644
--- a/drivers/staging/media/atomisp/i2c/mt9m114.c
+++ b/drivers/staging/media/atomisp/i2c/mt9m114.c
@@ -1575,13 +1575,6 @@ mt9m114_s_config(struct v4l2_subdev *sd, int irq, void 
*platform_data)
dev->platform_data =
(struct camera_sensor_platform_data *)platform_data;
 
-   if (dev->platform_data->platform_init) {
-   ret = dev->platform_data->platform_init(client);
-   if (ret) {
-   v4l2_err(client, "mt9m114 platform init err\n");
-   return ret;
-   }
-   }
ret = power_up(sd);
if (ret) {
v4l2_err(client, "mt9m114 power-up err");
@@ -1835,8 +1828,6 @@ static int mt9m114_remove(struct i2c_client *client)
 
dev = container_of(sd, struct mt9m114_device, sd);

[PATCH v1 02/13] staging: atomisp: Remove AP1302 sensor support

[Andy Shevchenko]

This sensor is not used by any known ACPI-enabled platform
(and no kernel users for it so far).

Just remove it for good until we get a platform which actually uses it.

Signed-off-by: Andy Shevchenko 
---
 drivers/staging/media/atomisp/i2c/Kconfig  |   12 -
 drivers/staging/media/atomisp/i2c/Makefile |2 -
 drivers/staging/media/atomisp/i2c/ap1302.c | 1255 
 drivers/staging/media/atomisp/i2c/ap1302.h |  198 -
 4 files changed, 1467 deletions(-)
 delete mode 100644 drivers/staging/media/atomisp/i2c/ap1302.c
 delete mode 100644 drivers/staging/media/atomisp/i2c/ap1302.h

diff --git a/drivers/staging/media/atomisp/i2c/Kconfig 
b/drivers/staging/media/atomisp/i2c/Kconfig
index b607c9837e2f..4da028d919c5 100644
--- a/drivers/staging/media/atomisp/i2c/Kconfig
+++ b/drivers/staging/media/atomisp/i2c/Kconfig
@@ -58,18 +58,6 @@ config VIDEO_MT9M114
 
 It currently only works with the atomisp driver.
 
-config VIDEO_AP1302
-   tristate "AP1302 external ISP support"
-   depends on I2C && VIDEO_V4L2
-   select REGMAP_I2C
-   ---help---
-This is a Video4Linux2 sensor-level driver for the external
-ISP AP1302.
-
-AP1302 is an exteral ISP.
-
-It currently only works with the atomisp driver.
-
 config VIDEO_GC0310
tristate "GC0310 sensor support"
depends on I2C && VIDEO_V4L2
diff --git a/drivers/staging/media/atomisp/i2c/Makefile 
b/drivers/staging/media/atomisp/i2c/Makefile
index 8a5a37467c3e..09331f661791 100644
--- a/drivers/staging/media/atomisp/i2c/Makefile
+++ b/drivers/staging/media/atomisp/i2c/Makefile
@@ -11,8 +11,6 @@ obj-$(CONFIG_VIDEO_GC0310) += gc0310.o
 
 obj-$(CONFIG_VIDEO_MSRLIST_HELPER) += libmsrlisthelper.o
 
-obj-$(CONFIG_VIDEO_AP1302) += ap1302.o
-
 # Makefile for flash drivers
 #
 
diff --git a/drivers/staging/media/atomisp/i2c/ap1302.c 
b/drivers/staging/media/atomisp/i2c/ap1302.c
deleted file mode 100644
index 2f772a020c8b..
--- a/drivers/staging/media/atomisp/i2c/ap1302.c
+++ /dev/null
@@ -1,1255 +0,0 @@
-/*
- *
- * Copyright (c) 2013 Intel Corporation. All Rights Reserved.
- *
- * 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.
- *
- */
-
-#include "../include/linux/atomisp.h"
-#include 
-#include 
-#include 
-#include 
-#include 
-#include 
-#include 
-#include 
-#include 
-#include "ap1302.h"
-
-#define to_ap1302_device(sub_dev) \
-   container_of(sub_dev, struct ap1302_device, sd)
-
-/* Static definitions */
-static struct regmap_config ap1302_reg16_config = {
-   .reg_bits = 16,
-   .val_bits = 16,
-   .reg_format_endian = REGMAP_ENDIAN_BIG,
-   .val_format_endian = REGMAP_ENDIAN_BIG,
-};
-
-static struct regmap_config ap1302_reg32_config = {
-   .reg_bits = 16,
-   .val_bits = 32,
-   .reg_format_endian = REGMAP_ENDIAN_BIG,
-   .val_format_endian = REGMAP_ENDIAN_BIG,
-};
-
-static enum ap1302_contexts ap1302_cntx_mapping[] = {
-   CONTEXT_PREVIEW,/* Invalid atomisp run mode */
-   CONTEXT_VIDEO,  /* ATOMISP_RUN_MODE_VIDEO */
-   CONTEXT_SNAPSHOT,   /* ATOMISP_RUN_MODE_STILL_CAPTURE */
-   CONTEXT_SNAPSHOT,   /* ATOMISP_RUN_MODE_CONTINUOUS_CAPTURE */
-   CONTEXT_PREVIEW,/* ATOMISP_RUN_MODE_PREVIEW */
-};
-
-static struct ap1302_res_struct ap1302_preview_res[] = {
-   {
-   .width = 640,
-   .height = 480,
-   .fps = 30,
-   },
-   {
-   .width = 720,
-   .height = 480,
-   .fps = 30,
-   },
-   {
-   .width = 1280,
-   .height = 720,
-   .fps = 30,
-   },
-   {
-   .width = 1920,
-   .height = 1080,
-   .fps = 30,
-   }
-};
-
-static struct ap1302_res_struct ap1302_snapshot_res[] = {
-   {
-   .width = 640,
-   .height = 480,
-   .fps = 30,
-   },
-   {
-   .width = 720,
-   .height = 480,
-   .fps = 30,
-   },
-   {
-   .width = 1280,
-   .height = 720,
-   .fps = 30,
-   },
-   {
-   .width = 1920,
-   .height = 1080,
-   .fps = 30,
-   }
-};
-
-static struct ap1302_res_struct ap1302_video_res[] = {
-   {
-   .width = 640,
-   .height = 480,
-   .fps = 30,
-   },
-   {
-   .width = 720,
-   .height = 480,
-   .fps = 30,
-