diff mbox

[v3,9/9] davinci: vpfe: Add documentation and TODO

Message ID 1354099329-20722-10-git-send-email-prabhakar.lad@ti.com (mailing list archive)
State Not Applicable
Headers show

Commit Message

Lad, Prabhakar Nov. 28, 2012, 10:42 a.m. UTC
From: Manjunath Hadli <manjunath.hadli@ti.com>

Add documentation on the Davinci VPFE driver. Document the subdevs,
and private IOTCLs the driver implements. This patch also includes
the TODO's to fit into drivers/media/ folder.

Signed-off-by: Manjunath Hadli <manjunath.hadli@ti.com>
Signed-off-by: Lad, Prabhakar <prabhakar.lad@ti.com>
---
 drivers/staging/media/davinci_vpfe/TODO            |   34 +++++
 .../staging/media/davinci_vpfe/davinci-vpfe-mc.txt |  154 ++++++++++++++++++++
 2 files changed, 188 insertions(+), 0 deletions(-)
 create mode 100644 drivers/staging/media/davinci_vpfe/TODO
 create mode 100644 drivers/staging/media/davinci_vpfe/davinci-vpfe-mc.txt

Comments

Mauro Carvalho Chehab Nov. 28, 2012, 11:22 a.m. UTC | #1
Hi Prabhakar,

Em Wed, 28 Nov 2012 16:12:09 +0530
Prabhakar Lad <prabhakar.csengg@gmail.com> escreveu:

> +Introduction
> +============
> +
> +This file documents the Texas Instruments Davinci Video processing Front End
> +(VPFE) driver located under drivers/media/platform/davinci. The original driver
> +exists for Davinci VPFE, which is now being changed to Media Controller
> +Framework.

Hmm... please correct me if I'm wrong, but are you wanting to replace an existing
driver at drivers/media/platform/davinci, by another one at staging that has
lots of known issues, as pointed at your TODO????

If so, please don't do that. Replacing a driver by some other one is generally
a very bad idea, especially in this case, where the new driver has clearly several
issues, the main one being to define its own proprietary and undocumented API:

> +As of now since the interface will undergo few changes all the include
> +files are present in staging itself, to build for dm365 follow below steps,
> +
> +- copy vpfe.h from drivers/staging/media/davinci_vpfe/ to
> +  include/media/davinci/ folder for building the uImage.
> +- copy davinci_vpfe_user.h from drivers/staging/media/davinci_vpfe/ to
> +  include/uapi/linux/davinci_vpfe.h, and add a entry in Kbuild (required
> +  for building application).
> +- copy dm365_ipipeif_user.h from drivers/staging/media/davinci_vpfe/ to
> +  include/uapi/linux/dm365_ipipeif.h and a entry in Kbuild (required
> +  for building application).

Among other things, with those ugly and very likely mandatory API calls:

>+/*
>+ * Private IOCTL
>+ * VIDIOC_VPFE_IPIPEIF_S_CONFIG: Set IPIEIF configuration
>+ * VIDIOC_VPFE_IPIPEIF_G_CONFIG: Get IPIEIF configuration
>+ */
>+#define VIDIOC_VPFE_IPIPEIF_S_CONFIG \
>+	_IOWR('I', BASE_VIDIOC_PRIVATE + 1, struct ipipeif_params)
>+#define VIDIOC_VPFE_IPIPEIF_G_CONFIG \
>+	_IOWR('I', BASE_VIDIOC_PRIVATE + 2, struct ipipeif_params)
>+
>+#endif	

I remember we rejected already drivers like that with obscure "S_CONFIG"
private ioctl that were suspect to send a big initialization undocumented
blob to the driver, as only the vendor's application would be able to use
such driver.

So, instead, of submitting it to staging, you should be sending incremental
patches for the existing driver, adding newer functionality there, and 
using the proper V4L2 API, with makes life easier for reviewers and
application developers.

Regards,
Mauro
Laurent Pinchart Nov. 28, 2012, 1 p.m. UTC | #2
Hi Mauro,

Please see below.

On Wednesday 28 November 2012 09:22:13 Mauro Carvalho Chehab wrote:
> Hi Prabhakar,
> 
> Em Wed, 28 Nov 2012 16:12:09 +0530
> 
> Prabhakar Lad <prabhakar.csengg@gmail.com> escreveu:
> > +Introduction
> > +============
> > +
> > + This file documents the Texas Instruments Davinci Video processing Front
> > + End (VPFE) driver located under drivers/media/platform/davinci. The
> > + original driver exists for Davinci VPFE, which is now being changed to
> > + Media Controller Framework.
> 
> Hmm... please correct me if I'm wrong, but are you wanting to replace an
> existing driver at drivers/media/platform/davinci, by another one at
> staging that has lots of known issues, as pointed at your TODO????
> 
> If so, please don't do that. Replacing a driver by some other one is
> generally a very bad idea, especially in this case, where the new driver
> has clearly several issues, the main one being to define its own proprietary
> and undocumented API:
>
> > +As of now since the interface will undergo few changes all the include
> > +files are present in staging itself, to build for dm365 follow below
> > +steps,
> > +
> > +- copy vpfe.h from drivers/staging/media/davinci_vpfe/ to
> > +  include/media/davinci/ folder for building the uImage.
> > +- copy davinci_vpfe_user.h from drivers/staging/media/davinci_vpfe/ to
> > +  include/uapi/linux/davinci_vpfe.h, and add a entry in Kbuild (required
> > +  for building application).
> > +- copy dm365_ipipeif_user.h from drivers/staging/media/davinci_vpfe/ to
> > +  include/uapi/linux/dm365_ipipeif.h and a entry in Kbuild (required
> > +  for building application).
> 
> Among other things, with those ugly and very likely mandatory API calls:
>
> >+/*
> >+ * Private IOCTL
> >+ * VIDIOC_VPFE_IPIPEIF_S_CONFIG: Set IPIEIF configuration
> >+ * VIDIOC_VPFE_IPIPEIF_G_CONFIG: Get IPIEIF configuration
> >+ */
> >+#define VIDIOC_VPFE_IPIPEIF_S_CONFIG \
> >+	_IOWR('I', BASE_VIDIOC_PRIVATE + 1, struct ipipeif_params)
> >+#define VIDIOC_VPFE_IPIPEIF_G_CONFIG \
> >+	_IOWR('I', BASE_VIDIOC_PRIVATE + 2, struct ipipeif_params)
> >+
> >+#endif
> 
> I remember we rejected already drivers like that with obscure "S_CONFIG"
> private ioctl that were suspect to send a big initialization undocumented
> blob to the driver, as only the vendor's application would be able to use
> such driver.

That's correct, and that's why the driver is going to staging. From there it 
will be incrementally fixed and then moved to drivers/media/, or dropped if 
not maintained.

> So, instead, of submitting it to staging, you should be sending incremental
> patches for the existing driver, adding newer functionality there, and
> using the proper V4L2 API, with makes life easier for reviewers and
> application developers.

I agree that it would be the best thing to do, but I don't think it's going to 
happen. We need to decide between two options.

- Push back now and insist in incremental patches for the existing driver, and 
get nothing back as TI will very likely give up completely.
- Accept the driver in staging, get it fixed incrementally, and finally move 
it to drivers/media/

There's a political side to this issue, we need to decide whether we want to 
insist vendors getting everything right before any code reaches mainline, in 
which case I believe we will lose some of them in the process, including major 
vendors such as TI, or if we can make the mainline learning curve and 
experience a bit more smooth by accepting such code in staging.

I would vote for the second option, with a very clear rule that getting the 
driver in staging is only one step in the journey: if the development effort 
stops there, the driver *will* be removed.
Mauro Carvalho Chehab Nov. 28, 2012, 7:35 p.m. UTC | #3
Hi Laurent,

Em Wed, 28 Nov 2012 14:00:14 +0100
Laurent Pinchart <laurent.pinchart@ideasonboard.com> escreveu:

> Hi Mauro,
> 
> Please see below.
> 
> On Wednesday 28 November 2012 09:22:13 Mauro Carvalho Chehab wrote:
> > Hi Prabhakar,
> > 
> > Em Wed, 28 Nov 2012 16:12:09 +0530
> > 
> > Prabhakar Lad <prabhakar.csengg@gmail.com> escreveu:
> > > +Introduction
> > > +============
> > > +
> > > + This file documents the Texas Instruments Davinci Video processing Front
> > > + End (VPFE) driver located under drivers/media/platform/davinci. The
> > > + original driver exists for Davinci VPFE, which is now being changed to
> > > + Media Controller Framework.
> > 
> > Hmm... please correct me if I'm wrong, but are you wanting to replace an
> > existing driver at drivers/media/platform/davinci, by another one at
> > staging that has lots of known issues, as pointed at your TODO????
> > 
> > If so, please don't do that. Replacing a driver by some other one is
> > generally a very bad idea, especially in this case, where the new driver
> > has clearly several issues, the main one being to define its own proprietary
> > and undocumented API:
> >
> > > +As of now since the interface will undergo few changes all the include
> > > +files are present in staging itself, to build for dm365 follow below
> > > +steps,
> > > +
> > > +- copy vpfe.h from drivers/staging/media/davinci_vpfe/ to
> > > +  include/media/davinci/ folder for building the uImage.
> > > +- copy davinci_vpfe_user.h from drivers/staging/media/davinci_vpfe/ to
> > > +  include/uapi/linux/davinci_vpfe.h, and add a entry in Kbuild (required
> > > +  for building application).
> > > +- copy dm365_ipipeif_user.h from drivers/staging/media/davinci_vpfe/ to
> > > +  include/uapi/linux/dm365_ipipeif.h and a entry in Kbuild (required
> > > +  for building application).
> > 
> > Among other things, with those ugly and very likely mandatory API calls:
> >
> > >+/*
> > >+ * Private IOCTL
> > >+ * VIDIOC_VPFE_IPIPEIF_S_CONFIG: Set IPIEIF configuration
> > >+ * VIDIOC_VPFE_IPIPEIF_G_CONFIG: Get IPIEIF configuration
> > >+ */
> > >+#define VIDIOC_VPFE_IPIPEIF_S_CONFIG \
> > >+	_IOWR('I', BASE_VIDIOC_PRIVATE + 1, struct ipipeif_params)
> > >+#define VIDIOC_VPFE_IPIPEIF_G_CONFIG \
> > >+	_IOWR('I', BASE_VIDIOC_PRIVATE + 2, struct ipipeif_params)
> > >+
> > >+#endif
> > 
> > I remember we rejected already drivers like that with obscure "S_CONFIG"
> > private ioctl that were suspect to send a big initialization undocumented
> > blob to the driver, as only the vendor's application would be able to use
> > such driver.
> 
> That's correct, and that's why the driver is going to staging. From there it 
> will be incrementally fixed and then moved to drivers/media/, or dropped if 
> not maintained.
> 
> > So, instead, of submitting it to staging, you should be sending incremental
> > patches for the existing driver, adding newer functionality there, and
> > using the proper V4L2 API, with makes life easier for reviewers and
> > application developers.
> 
> I agree that it would be the best thing to do, but I don't think it's going to 
> happen. We need to decide between two options.
> 
> - Push back now and insist in incremental patches for the existing driver, and 
> get nothing back as TI will very likely give up completely.
> - Accept the driver in staging, get it fixed incrementally, and finally move 
> it to drivers/media/
> 
> There's a political side to this issue, we need to decide whether we want to 
> insist vendors getting everything right before any code reaches mainline, in 
> which case I believe we will lose some of them in the process, including major 
> vendors such as TI, or if we can make the mainline learning curve and 
> experience a bit more smooth by accepting such code in staging.
> 
> I would vote for the second option, with a very clear rule that getting the 
> driver in staging is only one step in the journey: if the development effort 
> stops there, the driver *will* be removed.

What concerns most is that we'll be adding yet-another-driver for the same
hardware, but using a different API set (Media controller + subdevs, instead
of pure V4L2).

It should be noticed that even basic stuff seems to be missing at the driver,
like proper locks[1].

[1] I'm basing my comments only at this patchset's TODO list - I didn't 
reviewed the code, but it this is one of the listed items: "Check proper
serialisation (through mutexes and spinlocks)"

As no regressions are accepted, on non-staging drivers, the switch from the
already working, stable one to the new one, when this driver reaches the
required quality, will be a very hard task, as one would need to check the
exact behavior of the existing driver, and check if the new driver will
behave the same, in order to warrant that no regressions will be introduced.

This doesn't sound something easy to do, especially if the implementation
decisions taken on the second driver aren't based on the same way as the
existing driver.

The risk is that this driver would never be merged upstream, due to those
conflicts, or that we'll take several years to solve it, before being
able to warrant that userspace binaries developed for the first driver
will work as-is with the new one.

Regards,
Mauro
Sakari Ailus Nov. 28, 2012, 8 p.m. UTC | #4
Hi Mauro,

On Wed, Nov 28, 2012 at 09:22:13AM -0200, Mauro Carvalho Chehab wrote:
> Hi Prabhakar,
> 
> Em Wed, 28 Nov 2012 16:12:09 +0530
> Prabhakar Lad <prabhakar.csengg@gmail.com> escreveu:
> 
> > +Introduction
> > +============
> > +
> > +This file documents the Texas Instruments Davinci Video processing Front End
> > +(VPFE) driver located under drivers/media/platform/davinci. The original driver
> > +exists for Davinci VPFE, which is now being changed to Media Controller
> > +Framework.
> 
> Hmm... please correct me if I'm wrong, but are you wanting to replace an existing
> driver at drivers/media/platform/davinci, by another one at staging that has
> lots of known issues, as pointed at your TODO????

This driver going to staging is not going to replace anything as such.

The reason to put the driver to staging is simply that it'd be part of the
kernel source so people can use it effortlessly, just as any other driver
that's in staging. If you compare this to them, I think you will find it for
this driver's favour. Reading the Barcelona mini-summit report, isn't the
only requirement for staging drivers that they compile? I think this driver
passes that requiremnt with flying colours.

The driver that's currently in drivers/media/platform/davinci is a) serves a
small subset of potential use cases and b) lacks most features the hardware
can offer. This new driver that's intended for staging, is more generic,
feature-rich and supports standard APIs such as V4L2 subdev and Media
controller which the old driver does not do at all.

The TODO file exists to document what needs to be done to this driver to get
it out of staging. After this is done, its APIs and functionality is similar
to that offered by the OMAP 3 ISP driver.

> If so, please don't do that. Replacing a driver by some other one is generally
> a very bad idea, especially in this case, where the new driver has clearly several
> issues, the main one being to define its own proprietary and undocumented API:

What's currently is in mainline more closely resembles what the OMAP 3 ISP
driver used to be in the end of 2008. The code quality is better and it
contains less hacks, but still that is the case. At the time me and Laurent
decided that we didn't want to push it to staging, but instead continue
developing it out-of-tree.

> > +As of now since the interface will undergo few changes all the include
> > +files are present in staging itself, to build for dm365 follow below steps,
> > +
> > +- copy vpfe.h from drivers/staging/media/davinci_vpfe/ to
> > +  include/media/davinci/ folder for building the uImage.
> > +- copy davinci_vpfe_user.h from drivers/staging/media/davinci_vpfe/ to
> > +  include/uapi/linux/davinci_vpfe.h, and add a entry in Kbuild (required
> > +  for building application).
> > +- copy dm365_ipipeif_user.h from drivers/staging/media/davinci_vpfe/ to
> > +  include/uapi/linux/dm365_ipipeif.h and a entry in Kbuild (required
> > +  for building application).
> 
> Among other things, with those ugly and very likely mandatory API calls:
> 
> >+/*
> >+ * Private IOCTL
> >+ * VIDIOC_VPFE_IPIPEIF_S_CONFIG: Set IPIEIF configuration
> >+ * VIDIOC_VPFE_IPIPEIF_G_CONFIG: Get IPIEIF configuration
> >+ */
> >+#define VIDIOC_VPFE_IPIPEIF_S_CONFIG \
> >+	_IOWR('I', BASE_VIDIOC_PRIVATE + 1, struct ipipeif_params)
> >+#define VIDIOC_VPFE_IPIPEIF_G_CONFIG \
> >+	_IOWR('I', BASE_VIDIOC_PRIVATE + 2, struct ipipeif_params)
> >+
> >+#endif	
> 
> I remember we rejected already drivers like that with obscure "S_CONFIG"
> private ioctl that were suspect to send a big initialization undocumented
> blob to the driver, as only the vendor's application would be able to use
> such driver.

We know this is bad, and it's not going to stay. Improving the user space
API is mentioned in the TODO file. Also, much of this configuration is for
parts that weren't supported by the old driver to begin with.

> So, instead, of submitting it to staging, you should be sending incremental
> patches for the existing driver, adding newer functionality there, and 
> using the proper V4L2 API, with makes life easier for reviewers and
> application developers.

If you're looking to see API compatibility between the two, you will not be
able to get it: the old driver simply implements a different profile (which
should be defined but that's a separate issue). This is a new driver and
deserves to be treated that way.

If someone depends on the old driver currently, we should keep that old
driver in the tree and eventually remove it once users have moved to use the
new one. That requires resolving the issues listed in the TODO file and
accepting the driver as part of the media tree.
Lad, Prabhakar Nov. 29, 2012, 3:08 a.m. UTC | #5
Hi Mauro,

On Thu, Nov 29, 2012 at 1:05 AM, Mauro Carvalho Chehab
<mchehab@redhat.com> wrote:
> Hi Laurent,
>
> Em Wed, 28 Nov 2012 14:00:14 +0100
> Laurent Pinchart <laurent.pinchart@ideasonboard.com> escreveu:
>
>> Hi Mauro,
>>
>> Please see below.
>>
>> On Wednesday 28 November 2012 09:22:13 Mauro Carvalho Chehab wrote:
>> > Hi Prabhakar,
>> >
>> > Em Wed, 28 Nov 2012 16:12:09 +0530
>> >
>> > Prabhakar Lad <prabhakar.csengg@gmail.com> escreveu:
>> > > +Introduction
>> > > +============
>> > > +
>> > > + This file documents the Texas Instruments Davinci Video processing Front
>> > > + End (VPFE) driver located under drivers/media/platform/davinci. The
>> > > + original driver exists for Davinci VPFE, which is now being changed to
>> > > + Media Controller Framework.
>> >
>> > Hmm... please correct me if I'm wrong, but are you wanting to replace an
>> > existing driver at drivers/media/platform/davinci, by another one at
>> > staging that has lots of known issues, as pointed at your TODO????
>> >
>> > If so, please don't do that. Replacing a driver by some other one is
>> > generally a very bad idea, especially in this case, where the new driver
>> > has clearly several issues, the main one being to define its own proprietary
>> > and undocumented API:
>> >
>> > > +As of now since the interface will undergo few changes all the include
>> > > +files are present in staging itself, to build for dm365 follow below
>> > > +steps,
>> > > +
>> > > +- copy vpfe.h from drivers/staging/media/davinci_vpfe/ to
>> > > +  include/media/davinci/ folder for building the uImage.
>> > > +- copy davinci_vpfe_user.h from drivers/staging/media/davinci_vpfe/ to
>> > > +  include/uapi/linux/davinci_vpfe.h, and add a entry in Kbuild (required
>> > > +  for building application).
>> > > +- copy dm365_ipipeif_user.h from drivers/staging/media/davinci_vpfe/ to
>> > > +  include/uapi/linux/dm365_ipipeif.h and a entry in Kbuild (required
>> > > +  for building application).
>> >
>> > Among other things, with those ugly and very likely mandatory API calls:
>> >
>> > >+/*
>> > >+ * Private IOCTL
>> > >+ * VIDIOC_VPFE_IPIPEIF_S_CONFIG: Set IPIEIF configuration
>> > >+ * VIDIOC_VPFE_IPIPEIF_G_CONFIG: Get IPIEIF configuration
>> > >+ */
>> > >+#define VIDIOC_VPFE_IPIPEIF_S_CONFIG \
>> > >+  _IOWR('I', BASE_VIDIOC_PRIVATE + 1, struct ipipeif_params)
>> > >+#define VIDIOC_VPFE_IPIPEIF_G_CONFIG \
>> > >+  _IOWR('I', BASE_VIDIOC_PRIVATE + 2, struct ipipeif_params)
>> > >+
>> > >+#endif
>> >
>> > I remember we rejected already drivers like that with obscure "S_CONFIG"
>> > private ioctl that were suspect to send a big initialization undocumented
>> > blob to the driver, as only the vendor's application would be able to use
>> > such driver.
>>
>> That's correct, and that's why the driver is going to staging. From there it
>> will be incrementally fixed and then moved to drivers/media/, or dropped if
>> not maintained.
>>
>> > So, instead, of submitting it to staging, you should be sending incremental
>> > patches for the existing driver, adding newer functionality there, and
>> > using the proper V4L2 API, with makes life easier for reviewers and
>> > application developers.
>>
>> I agree that it would be the best thing to do, but I don't think it's going to
>> happen. We need to decide between two options.
>>
>> - Push back now and insist in incremental patches for the existing driver, and
>> get nothing back as TI will very likely give up completely.
>> - Accept the driver in staging, get it fixed incrementally, and finally move
>> it to drivers/media/
>>
>> There's a political side to this issue, we need to decide whether we want to
>> insist vendors getting everything right before any code reaches mainline, in
>> which case I believe we will lose some of them in the process, including major
>> vendors such as TI, or if we can make the mainline learning curve and
>> experience a bit more smooth by accepting such code in staging.
>>
>> I would vote for the second option, with a very clear rule that getting the
>> driver in staging is only one step in the journey: if the development effort
>> stops there, the driver *will* be removed.
>
> What concerns most is that we'll be adding yet-another-driver for the same
> hardware, but using a different API set (Media controller + subdevs, instead
> of pure V4L2).
>
> It should be noticed that even basic stuff seems to be missing at the driver,
> like proper locks[1].
>
> [1] I'm basing my comments only at this patchset's TODO list - I didn't
> reviewed the code, but it this is one of the listed items: "Check proper
> serialisation (through mutexes and spinlocks)"
>
This was just a quick TODO list provided by Sakari, These code was being
targeted for media folder itself and not staging. This code is well
tested on DM365
EVM. The TODO list might be looking long but trust me this would be
fixed up quickly.

> As no regressions are accepted, on non-staging drivers, the switch from the
> already working, stable one to the new one, when this driver reaches the
> required quality, will be a very hard task, as one would need to check the
> exact behavior of the existing driver, and check if the new driver will
> behave the same, in order to warrant that no regressions will be introduced.
>
> This doesn't sound something easy to do, especially if the implementation
> decisions taken on the second driver aren't based on the same way as the
> existing driver.
>
> The risk is that this driver would never be merged upstream, due to those
> conflicts, or that we'll take several years to solve it, before being
> able to warrant that userspace binaries developed for the first driver
> will work as-is with the new one.
>
This is pretty much similar as OMAP3isp driver. The current driver is based
on V4l2 lacking major features such as ipipe, and resizing. The new driver
which has being added uses the Media controller framewrok, uses videobuf2,
supports ipipe and resizing driver and obvious advantages  of media controller
framework. If driver with these new features and enhancement doesn't make into
just because taking into mind of the users of old driver.

This is something similar like you have videobuf and videobuf2. But
there were no
incremental patches for videobuf itself, but it was added new. But now
there is rule
for users writing a new driver should write using videobuf2 only, so
that slowly videobuf
phases of, Similarly the users will need to be encouraged to use the new drivers
with such a huge list of features in new driver and slowly phase of
the old driver.

Regards,
--Prabhakar Lad

> Regards,
> Mauro
diff mbox

Patch

diff --git a/drivers/staging/media/davinci_vpfe/TODO b/drivers/staging/media/davinci_vpfe/TODO
new file mode 100644
index 0000000..b575cd1
--- /dev/null
+++ b/drivers/staging/media/davinci_vpfe/TODO
@@ -0,0 +1,34 @@ 
+TODO (general):
+==================================
+
+- User space interface refinement
+        - Controls should be used when possible rather than private ioctl
+        - No enums should be used
+        - Use of MC and V4L2 subdev APIs when applicable
+        - Single interface header might suffice
+        - Current interface forces to configure everything at once
+- Get rid of the dm365_ipipe_hw.[ch] layer
+- Active external sub-devices defined by link configuration; no strcmp
+  needed
+- More generic platform data (i2c adapters)
+- The driver should have no knowledge of possible external subdevs; see
+  struct vpfe_subdev_id
+- Some of the hardware control should be refactorede
+- Check proper serialisation (through mutexes and spinlocks)
+- Names that are visible in kernel global namespace should have a common
+  prefix (or a few)
+
+Building of uImage and Applications:
+==================================
+
+As of now since the interface will undergo few changes all the include
+files are present in staging itself, to build for dm365 follow below steps,
+
+- copy vpfe.h from drivers/staging/media/davinci_vpfe/ to
+  include/media/davinci/ folder for building the uImage.
+- copy davinci_vpfe_user.h from drivers/staging/media/davinci_vpfe/ to
+  include/uapi/linux/davinci_vpfe.h, and add a entry in Kbuild (required
+  for building application).
+- copy dm365_ipipeif_user.h from drivers/staging/media/davinci_vpfe/ to
+  include/uapi/linux/dm365_ipipeif.h and a entry in Kbuild (required
+  for building application).
diff --git a/drivers/staging/media/davinci_vpfe/davinci-vpfe-mc.txt b/drivers/staging/media/davinci_vpfe/davinci-vpfe-mc.txt
new file mode 100644
index 0000000..1dbd564
--- /dev/null
+++ b/drivers/staging/media/davinci_vpfe/davinci-vpfe-mc.txt
@@ -0,0 +1,154 @@ 
+Davinci Video processing Front End (VPFE) driver
+
+Copyright (C) 2012 Texas Instruments Inc
+
+Contacts: Manjunath Hadli <manjunath.hadli@ti.com>
+	  Prabhakar Lad <prabhakar.lad@ti.com>
+
+
+Introduction
+============
+
+This file documents the Texas Instruments Davinci Video processing Front End
+(VPFE) driver located under drivers/media/platform/davinci. The original driver
+exists for Davinci VPFE, which is now being changed to Media Controller
+Framework.
+
+Currently the driver has been successfully used on the following
+version of Davinci:
+
+	DM365/DM368
+
+The driver implements V4L2, Media controller and v4l2_subdev interfaces. Sensor,
+lens and flash drivers using the v4l2_subdev interface in the kernel are
+supported.
+
+
+Split to subdevs
+================
+
+The Davinci VPFE is split into V4L2 subdevs, each of the blocks inside the VPFE
+having one subdev to represent it. Each of the subdevs provide a V4L2 subdev
+interface to userspace.
+
+	DAVINCI ISIF
+	DAVINCI IPIPEIF
+	DAVINCI IPIPE
+	DAVINCI CROP RESIZER
+	DAVINCI RESIZER A
+	DAVINCI RESIZER B
+
+Each possible link in the VPFE is modeled by a link in the Media controller
+interface. For an example program see [1].
+
+
+ISIF, IPIPE, and RESIZER block IOCTLs
+======================================
+
+The Davinci Video processing Front End (VPFE) driver supports standard V4L2
+IOCTLs and controls where possible and practical. Much of the functions provided
+by the VPFE, however, does not fall under the standard IOCTL's.
+
+In general, there is a private ioctl for configuring each of the blocks
+containing hardware-dependent functions.
+
+The following private IOCTLs are supported:
+
+	VIDIOC_VPFE_ISIF_[S/G]_RAW_PARAMS
+	VIDIOC_VPFE_IPIPE_[S/G]_CONFIG
+	VIDIOC_VPFE_RSZ_[S/G]_CONFIG
+
+The parameter structures used by these ioctl's are described in
+include/uapi/linux/davinci_vpfe.h.
+
+The VIDIOC_VPFE_ISIF_S_RAW_PARAMS, VIDIOC_VPFE_IPIPE_S_CONFIG and
+VIDIOC_VPFE_RSZ_S_CONFIG are used to configure, enable and disable functions in
+the isif, ipipe and resizer blocks respectively. These IOCTL's control several
+functions in the blocks they control. VIDIOC_VPFE_ISIF_S_RAW_PARAMS IOCTL
+accepts a pointer to struct vpfe_isif_raw_config as its argument. Similarly
+VIDIOC_VPFE_IPIPE_S_CONFIG accepts a pointer to struct vpfe_ipipe_config. And
+VIDIOC_VPFE_RSZ_S_CONFIG accepts a pointer to struct vpfe_rsz_config as its
+argument. Similarly VIDIOC_VPFE_ISIF_G_RAW_PARAMS, VIDIOC_VPFE_IPIPE_G_CONFIG
+and VIDIOC_VPFE_RSZ_G_CONFIG are used to get the current configuration set in
+the isif, ipipe and resizer blocks respectively.
+
+The detailed functions of the VPFE itself related to a given VPFE block is
+described in the Technical Reference Manuals (TRMs) --- see the end of the
+document for those.
+
+
+IPIPEIF block IOCTLs
+======================================
+
+The following private IOCTLs are supported:
+
+	VIDIOC_VPFE_IPIPEIF_[S/G]_CONFIG
+
+The parameter structures used by these ioctl's are described in
+include/uapi/linux/dm365_ipipeif.h
+
+The VIDIOC_VPFE_IPIPEIF_S_CONFIG is used to configure the ipipeif
+hardware block. The VIDIOC_VPFE_IPIPEIF_S_CONFIG and
+VIDIOC_VPFE_IPIPEIF_G_CONFIG accepts a pointer to struct ipipeif_params
+as its argument.
+
+
+VPFE Operating Modes
+==========================================
+
+a: Continuous Modes
+------------------------
+
+1: tvp514x/tvp7002/mt9p031---> DAVINCI ISIF---> SDRAM
+
+2: tvp514x/tvp7002/mt9p031---> DAVINCI ISIF---> DAVINCI IPIPEIF--->|
+                                                                   |
+   <--------------------<----------------<---------------------<---|
+   |
+   V
+ DAVINCI CROP RESIZER--->DAVINCI RESIZER [A/B]---> SDRAM
+
+3: tvp514x/tvp7002/mt9p031---> DAVINCI ISIF---> DAVINCI IPIPEIF--->|
+                                                                   |
+   <--------------------<----------------<---------------------<---|
+   |
+   V
+ DAVINCI IPIPE---> DAVINCI CROP RESIZER--->DAVINCI RESIZER [A/B]---> SDRAM
+
+a: Single Shot Modes
+------------------------
+
+1: SDRAM---> DAVINCI IPIPEIF---> DAVINCI IPIPE---> DAVINCI CROP RESIZER--->|
+                                                                           |
+   <----------------<----------------<------------------<---------------<--|
+   |
+   V
+DAVINCI RESIZER [A/B]---> SDRAM
+
+2: SDRAM---> DAVINCI IPIPEIF---> DAVINCI CROP RESIZER--->|
+                                                         |
+   <----------------<----------------<---------------<---|
+   |
+   V
+DAVINCI RESIZER [A/B]---> SDRAM
+
+
+Technical reference manuals (TRMs) and other documentation
+==========================================================
+
+Davinci DM365 TRM:
+<URL:http://www.ti.com/lit/ds/sprs457e/sprs457e.pdf>
+Referenced MARCH 2009-REVISED JUNE 2011
+
+Davinci DM368 TRM:
+<URL:http://www.ti.com/lit/ds/sprs668c/sprs668c.pdf>
+Referenced APRIL 2010-REVISED JUNE 2011
+
+Davinci Video Processing Front End (VPFE) DM36x
+<URL:http://www.ti.com/lit/ug/sprufg8c/sprufg8c.pdf>
+
+
+References
+==========
+
+[1] http://git.ideasonboard.org/?p=media-ctl.git;a=summary