Hi everybody,

Here is the seventh version of the media controller core and V4L2 patches.
the first one to be sent outside of the linux-media mailing list.

Quick reminder for those who missed the previous version. let me quote the
documentation (Documentation/DocBook/v4l/media-controller.xml).

"Discovering a [media] device internal topology, and configuring it at runtime,
is one of the goals of the media controller API. To achieve this, hardware
devices are modelled as an oriented graph of building blocks called entities
connected through pads."

The code has been extensively reviewed by the V4L community, and this version
is the first one to incorporate comments from the ALSA community (big thanks
to Mark Brown and Clemens Ladisch). Two issues are not fully addressed yet,
namely power management (I need to discuss this some more with the ALSA
developers to really understand their requirements) and entities type names.
I'm still posting this for review, as other developers have showed interest in
commenting on the code.

I want to emphasize once again that the media controller API does not replace
the V4L, DVB or ALSA APIs. It complements them.

The first user of the media controller API is the OMAP3 ISP driver. You can
find it (as well as these patches and other V4L-specific patches) in a git tree
at http://git.linuxtv.org/pinchartl/media.git (media-0004-omap3isp branch). The
OMAP3 ISP driver patches are regularly posted for review on the linux-media
list.

Laurent Pinchart (10):
  media: Media device node support
  media: Media device
  media: Entities, pads and links
  media: Media device information query
  media: Entities, pads and links enumeration
  media: Links setup
  media: Pipelines and media streams
  v4l: Add a media_device pointer to the v4l2_device structure
  v4l: Make video_device inherit from media_entity
  v4l: Make v4l2_subdev inherit from media_entity

Sakari Ailus (2):
  media: Entity graph traversal
  media: Reference count and power ...
[ message continues ]

The media_devnode structure provides support for registering and
unregistering character devices using a dynamic major number. Reference
counting is handled internally, making device drivers easier to write
without having to solve the open/disconnect race condition issue over
and over again.

The code is based on video/v4l2-dev.c.

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
 drivers/media/Kconfig         |   13 ++
 drivers/media/Makefile        |   10 +-
 drivers/media/media-devnode.c |  321 +++++++++++++++++++++++++++++++++++++++++
 include/media/media-devnode.h |   97 +++++++++++++
 4 files changed, 439 insertions(+), 2 deletions(-)
 create mode 100644 drivers/media/media-devnode.c
 create mode 100644 include/media/media-devnode.h

diff --git a/drivers/media/Kconfig b/drivers/media/Kconfig
index a28541b..6b946e6 100644
--- a/drivers/media/Kconfig
+++ b/drivers/media/Kconfig
@@ -14,6 +14,19 @@ if MEDIA_SUPPORT
 comment "Multimedia core support"
 
 #
+# Media controller
+#
+
+config MEDIA_CONTROLLER
+	bool "Media Controller API (EXPERIMENTAL)"
+	depends on EXPERIMENTAL
+	---help---
+	  Enable the media controller API used to query media devices internal
+	  topology and configure it dynamically.
+
+	  This API is mostly used by camera interfaces in embedded platforms.
+
+#
 # V4L core and enabled API's
 #
 
diff --git a/drivers/media/Makefile b/drivers/media/Makefile
index 499b081..3a08991 100644
--- a/drivers/media/Makefile
+++ b/drivers/media/Makefile
@@ -2,7 +2,13 @@
 # Makefile for the kernel multimedia device drivers.
 #
 
+media-objs	:= media-devnode.o
+
+ifeq ($(CONFIG_MEDIA_CONTROLLER),y)
+  obj-$(CONFIG_MEDIA_SUPPORT) += media.o
+endif
+
 obj-y += common/ IR/ video/
 
-obj-$(CONFIG_VIDEO_DEV) += radio/
-obj-$(CONFIG_DVB_CORE)  += dvb/
+obj-$(CONFIG_VIDEO_DEV)		+= radio/
+obj-$(CONFIG_DVB_CORE)		+= dvb/
diff --git a/drivers/media/media-devnode.c b/drivers/media/media-devnode.c
new file mode 100644
index ...
[ message continues ]

That's nice, but why should I enable this?  Or will drivers enable it







By virtue of having the reference to the module held by the vfs, this

So you can unregister a device at any time, even if the device is open,
or about to be opened?  Then that's fine, but you can put the lock after

How is that holding anything into memory?  Don't you want to keep the
module that the fops pointer in the device in memory, not necessarily

No reference counting for the fops?  Why not?

Anyway, it looks like what you really want is an "easier" way to handle
a cdev and a struct device that will export the proper information to
userspace, right?

Why not do this generically, fixing up the cdev interface (which really
needs it) and not tie it to media devices at all, making it possible for
_everyone_ to use this type of infrastructure?

That seems like the better thing to do here.

thanks,

greg k-h
--

[ message continues ]

Hi Greg,

Thank you for the review.


In a nutshell, the race between device disconnection, which results in the 
device instance being delete (if not in use of course), and open() calls from 
userspace. The problem has been solved in V4L a couple of releases ago after 
suffering from this race for a too long time. As V4L devices (and now media 
devices) need to create both a struct device and a struct cdev instance, 

Drivers depending on the media controller API will enable this, yes. The 
option will probably removed later when the API won't be deemed as 

Because I'm using a bitmap to store the used minor numbers, and I thus need a 
limit. I could get rid of it of it by using a linked list, but that will not 
be efficient (you could argue that the list will hold a few entries only most 

It's not just camera. Media devices are... well, media devices. Basically 
anything that can handle audio and/or video streams. The media controller API 

Yes, one major and (for now) 256 minors. Is there a problem with it being 

That will be done by the release callback. The media_devnode structure is 
embedded in the media_device structure, which will be embedded in driver-




inode->i_cdev is set to NULL by cdev_default_release() which can be called 
from media_devnode_unregister(). I could move to container_of outside the 
lock, but in that case I would have to check for mdev == NULL || 
!mdev_devnode_is_registered(mdev) (or move the NULL check inside 

That's correct. That way drivers don't need to care about unregister/open 


That will prevent the device instance from being freed until the device is 
closed, thereby holding both the device instance and the cdev instance in 

The cdev owner pointer is set to the fops owner. Unless I'm mistaken it will 
keep the module in memory. I need to keep the device in memory (or rather the 
media_devnode structure that embeds it) to handle file operations on a device 


Sounds like a good idea. You're a better cdev expert than me, ...
[ message continues ]

It's a define, not a flag, or anything that any driver could touch.

And if you don't want anyone to touch the thing, then make it private
and unable to be touched by anyone else.  Otherwise it will be
touched...

thanks,

greg k-h
--

[ message continues ]

The media_device structure abstracts functions common to all kind of
media devices (v4l2, dvb, alsa, ...). It manages media entities and
offers a userspace API to discover and configure the media device
internal topology.

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
 Documentation/DocBook/media-entities.tmpl      |    2 +
 Documentation/DocBook/media.tmpl               |    3 +
 Documentation/DocBook/v4l/media-controller.xml |   56 +++++++++++++
 Documentation/media-framework.txt              |   68 ++++++++++++++++
 drivers/media/Makefile                         |    2 +-
 drivers/media/media-device.c                   |  100 ++++++++++++++++++++++++
 include/media/media-device.h                   |   69 ++++++++++++++++
 7 files changed, 299 insertions(+), 1 deletions(-)
 create mode 100644 Documentation/DocBook/v4l/media-controller.xml
 create mode 100644 Documentation/media-framework.txt
 create mode 100644 drivers/media/media-device.c
 create mode 100644 include/media/media-device.h

diff --git a/Documentation/DocBook/media-entities.tmpl b/Documentation/DocBook/media-entities.tmpl
index be34dcb..61d6f11 100644
--- a/Documentation/DocBook/media-entities.tmpl
+++ b/Documentation/DocBook/media-entities.tmpl
@@ -321,6 +321,8 @@
 <!ENTITY sub-media-entities SYSTEM "media-entities.tmpl">
 <!ENTITY sub-media-indices SYSTEM "media-indices.tmpl">
 
+<!ENTITY sub-media-controller SYSTEM "v4l/media-controller.xml">
+
 <!-- Function Reference -->
 <!ENTITY close SYSTEM "v4l/func-close.xml">
 <!ENTITY ioctl SYSTEM "v4l/func-ioctl.xml">
diff --git a/Documentation/DocBook/media.tmpl b/Documentation/DocBook/media.tmpl
index f11048d..73464b0 100644
--- a/Documentation/DocBook/media.tmpl
+++ b/Documentation/DocBook/media.tmpl
@@ -106,6 +106,9 @@ Foundation. A copy of the license is included in the chapter entitled
 &sub-remote_controllers;
 </chapter>
 </part>
+<part id="media_common">
+&sub-media-controller;
+</part>
 
 &sub-fdl-appendix;
 
diff ...
[ message continues ]

As you create sysfs files, please also create Documentation/ABI/ entries
for those sysfs files at the same time.

thanks,

greg k-h
--

[ message continues ]

Hi Greg,

Thanks for the review.


Sorry for having forgotten that. I will fix it.

-- 
Regards,

Laurent Pinchart
--

[ message continues ]

From: Sakari Ailus <sakari.ailus@maxwell.research.nokia.com>

Add media entity graph traversal. The traversal follows enabled links by
depth first. Traversing graph backwards is prevented by comparing the next
possible entity in the graph with the previous one. Multiply connected
graphs are thus not supported.

Signed-off-by: Sakari Ailus <sakari.ailus@maxwell.research.nokia.com>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Vimarsh Zutshi <vimarsh.zutshi@nokia.com>
---
 Documentation/media-framework.txt |   42 +++++++++++++
 drivers/media/media-entity.c      |  115 +++++++++++++++++++++++++++++++++++++
 include/media/media-entity.h      |   15 +++++
 3 files changed, 172 insertions(+), 0 deletions(-)

diff --git a/Documentation/media-framework.txt b/Documentation/media-framework.txt
index c35b641..2cf3676 100644
--- a/Documentation/media-framework.txt
+++ b/Documentation/media-framework.txt
@@ -217,3 +217,45 @@ Links have flags that describe the link capabilities and state.
 	MEDIA_LINK_FLAG_ENABLED must also be set since an immutable link is
 	always enabled.
 
+
+Graph traversal
+---------------
+
+The media framework provides APIs to iterate over entities in a graph.
+
+To iterate over all entities belonging to a media device, drivers can use the
+media_device_for_each_entity macro, defined in include/media/media-device.h.
+
+	struct media_entity *entity;
+
+	media_device_for_each_entity(entity, mdev) {
+		/* entity will point to each entity in turn */
+		...
+	}
+
+Drivers might also need to iterate over all entities in a graph that can be
+reached only through enabled links starting at a given entity. The media
+framework provides a depth-first graph traversal API for that purpose.
+
+Note that graphs with cycles (whether directed or undirected) are *NOT*
+supported by the graph traversal API. To prevent infinite loops, the graph
+traversal code limits the maximum depth to MEDIA_ENTITY_ENUM_MAX_DEPTH,
+currently defined ...
[ message continues ]

From: Sakari Ailus <sakari.ailus@maxwell.research.nokia.com>

Basically these are the interface functions:

media_entity_get() - acquire entity
media_entity_put() - release entity

If the entity is of node type, the power change is distributed to all
connected entities. For non-nodes it only affects that very node. A
mutex is used to serialise access to the entity graph.

In the background there's a depth-first search algorithm that traverses
the enabled links in the graph. All these functions parse the graph to
implement whatever they're to do.

The module counters are increased/decreased in media_entity_get/put to
prevent module unloading when an entity is referenced.

Signed-off-by: Sakari Ailus <sakari.ailus@maxwell.research.nokia.com>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Stanimir Varbanov <svarbanov@mm-sol.com>
---
 Documentation/media-framework.txt |   37 +++++++++
 drivers/media/media-device.c      |    1 +
 drivers/media/media-entity.c      |  146 +++++++++++++++++++++++++++++++++++++
 include/media/media-device.h      |    4 +
 include/media/media-entity.h      |   15 ++++
 5 files changed, 203 insertions(+), 0 deletions(-)

diff --git a/Documentation/media-framework.txt b/Documentation/media-framework.txt
index 2cf3676..e90969e 100644
--- a/Documentation/media-framework.txt
+++ b/Documentation/media-framework.txt
@@ -259,3 +259,40 @@ When the graph traversal is complete the function will return NULL.
 Graph traversal can be interrupted at any moment. No cleanup function call is
 required and the graph structure can be freed normally.
 
+
+Reference counting and power handling
+-------------------------------------
+
+Before accessing type-specific entities operations (such as the V4L2
+sub-device operations), drivers must acquire a reference to the entity. This
+ensures that the entity will be powered on and ready to accept requests.
+Similarly, after being done with an entity, drivers must release ...
[ message continues ]

Create the following ioctl and implement it at the media device level to
setup links.

- MEDIA_IOC_SETUP_LINK: Modify the properties of a given link

The only property that can currently be modified is the ENABLED link
flag to enable/disable a link. Links marked with the IMMUTABLE link flag
can not be enabled or disabled.

Enabling or disabling a link has effects on entities' use count. Those
changes are automatically propagated through the graph.

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Stanimir Varbanov <svarbanov@mm-sol.com>
Signed-off-by: Sakari Ailus <sakari.ailus@maxwell.research.nokia.com>
---
 Documentation/DocBook/media-entities.tmpl          |    2 +
 Documentation/DocBook/v4l/media-controller.xml     |    1 +
 Documentation/DocBook/v4l/media-ioc-setup-link.xml |   90 +++++++++
 Documentation/media-framework.txt                  |   47 +++++
 drivers/media/media-device.c                       |   45 +++++
 drivers/media/media-entity.c                       |  208 ++++++++++++++++++++
 include/linux/media.h                              |    1 +
 include/media/media-entity.h                       |    8 +
 8 files changed, 402 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/DocBook/v4l/media-ioc-setup-link.xml

diff --git a/Documentation/DocBook/media-entities.tmpl b/Documentation/DocBook/media-entities.tmpl
index 6e7dae4..679c585 100644
--- a/Documentation/DocBook/media-entities.tmpl
+++ b/Documentation/DocBook/media-entities.tmpl
@@ -94,6 +94,7 @@
 <!ENTITY MEDIA-IOC-DEVICE-INFO "<link linkend='media-ioc-device-info'><constant>MEDIA_IOC_DEVICE_INFO</constant></link>">
 <!ENTITY MEDIA-IOC-ENUM-ENTITIES "<link linkend='media-ioc-enum-entities'><constant>MEDIA_IOC_ENUM_ENTITIES</constant></link>">
 <!ENTITY MEDIA-IOC-ENUM-LINKS "<link linkend='media-ioc-enum-links'><constant>MEDIA_IOC_ENUM_LINKS</constant></link>">
+<!ENTITY MEDIA-IOC-SETUP-LINK "<link ...
[ message continues ]

The pointer will later be used to register/unregister media entities
when registering/unregistering a v4l2_subdev or a video_device.

With the introduction of media devices, device drivers need to store a
pointer to a driver-specific structure in the device's drvdata.
v4l2_device can't claim ownership of the drvdata anymore.

To maintain compatibility with drivers that rely on v4l2_device storing
a pointer to itself in the device's drvdata, v4l2_device_register() will
keep doing so if the drvdata is NULL.

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
 Documentation/video4linux/v4l2-framework.txt |   17 ++++++++++++-----
 drivers/media/video/v4l2-device.c            |   13 +++++++------
 include/media/v4l2-device.h                  |    4 ++++
 3 files changed, 23 insertions(+), 11 deletions(-)

diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt
index 4db1def..aeb2a22 100644
--- a/Documentation/video4linux/v4l2-framework.txt
+++ b/Documentation/video4linux/v4l2-framework.txt
@@ -83,11 +83,17 @@ You must register the device instance:
 
 	v4l2_device_register(struct device *dev, struct v4l2_device *v4l2_dev);
 
-Registration will initialize the v4l2_device struct and link dev->driver_data
-to v4l2_dev. If v4l2_dev->name is empty then it will be set to a value derived
-from dev (driver name followed by the bus_id, to be precise). If you set it
-up before calling v4l2_device_register then it will be untouched. If dev is
-NULL, then you *must* setup v4l2_dev->name before calling v4l2_device_register.
+Registration will initialize the v4l2_device struct. If the dev->driver_data
+field is NULL, it will be linked to v4l2_dev. Drivers that use the media
+device framework in addition to the V4L2 framework need to set
+dev->driver_data manually to point to the driver-specific device structure
+that embed the struct v4l2_device instance. This is achieved by a
+dev_set_drvdata() call before registering the ...
[ message continues ]

V4L2 subdevices are media entities. As such they need to inherit from
(include) the media_entity structure.

When registering/unregistering the subdevice, the media entity is
automatically registered/unregistered. The entity is acquired on device
open and released on device close.

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Sakari Ailus <sakari.ailus@maxwell.research.nokia.com>
---
 Documentation/video4linux/v4l2-framework.txt |   23 ++++++++++++++
 drivers/media/video/v4l2-device.c            |   39 ++++++++++++++++++++----
 drivers/media/video/v4l2-subdev.c            |   41 ++++++++++++++++++++++++-
 include/media/v4l2-subdev.h                  |   10 ++++++
 4 files changed, 104 insertions(+), 9 deletions(-)

diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt
index f231bc20..d0fb880 100644
--- a/Documentation/video4linux/v4l2-framework.txt
+++ b/Documentation/video4linux/v4l2-framework.txt
@@ -268,6 +268,26 @@ A sub-device driver initializes the v4l2_subdev struct using:
 Afterwards you need to initialize subdev->name with a unique name and set the
 module owner. This is done for you if you use the i2c helper functions.
 
+If integration with the media framework is needed, you must initialize the
+media_entity struct embedded in the v4l2_subdev struct (entity field) by
+calling media_entity_init():
+
+	struct media_pad *pads = &my_sd->pads;
+	int err;
+
+	err = media_entity_init(&sd->entity, npads, pads, 0);
+
+The pads array must have been previously initialized. There is no need to
+manually set the struct media_entity type and name fields, but the revision
+field must be initialized if needed.
+
+A reference to the entity will be automatically acquired/released when the
+subdev device node (if any) is opened/closed.
+
+Don't forget to cleanup the media entity before the sub-device is destroyed:
+
+	media_entity_cleanup(&sd->entity);
+
 A device (bridge) driver needs ...
[ message continues ]

V4L2 devices are media entities. As such they need to inherit from
(include) the media_entity structure.

When registering/unregistering the device, the media entity is
automatically registered/unregistered. The entity is acquired on device
open and released on device close.

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Sakari Ailus <sakari.ailus@maxwell.research.nokia.com>
---
 Documentation/video4linux/v4l2-framework.txt |   38 ++++++++++++++++++--
 drivers/media/video/v4l2-dev.c               |   49 +++++++++++++++++++++++---
 include/media/v4l2-dev.h                     |    7 ++++
 3 files changed, 86 insertions(+), 8 deletions(-)

diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt
index aeb2a22..f231bc20 100644
--- a/Documentation/video4linux/v4l2-framework.txt
+++ b/Documentation/video4linux/v4l2-framework.txt
@@ -71,6 +71,10 @@ sub-device instances, the video_device struct stores V4L2 device node data
 and in the future a v4l2_fh struct will keep track of filehandle instances
 (this is not yet implemented).
 
+The V4L2 framework also optionally integrates with the media framework. If a
+driver sets the struct v4l2_device mdev field, sub-devices and video nodes
+will automatically appear in the media framework as entities.
+
 
 struct v4l2_device
 ------------------
@@ -84,11 +88,14 @@ You must register the device instance:
 	v4l2_device_register(struct device *dev, struct v4l2_device *v4l2_dev);
 
 Registration will initialize the v4l2_device struct. If the dev->driver_data
-field is NULL, it will be linked to v4l2_dev. Drivers that use the media
-device framework in addition to the V4L2 framework need to set
+field is NULL, it will be linked to v4l2_dev.
+
+Drivers that want integration with the media device framework need to set
 dev->driver_data manually to point to the driver-specific device structure
 that embed the struct v4l2_device instance. This is achieved by ...
[ message continues ]

Drivers often need to associate pipeline objects to entities, and to
take stream state into account when configuring entities and links. The
pipeline API helps drivers manage that information.

When starting streaming, drivers call media_entity_pipeline_start(). The
function marks all entities connected to the given entity through
enabled links, either directly or indirectly, as streaming. Similarly,
when stopping the stream, drivers call media_entity_pipeline_stop().

The media_entity_pipeline_start() function takes a pointer to a media
pipeline and stores it in every entity in the graph. Drivers should
embed the media_pipeline structure in higher-level pipeline structures
and can then access the pipeline through the media_entity structure.

Link configuration will fail with -EBUSY by default if either end of the
link is a streaming entity, unless the link is marked with the
MEDIA_LINK_FLAG_DYNAMIC flag.

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
 Documentation/DocBook/v4l/media-ioc-enum-links.xml |    5 ++
 Documentation/DocBook/v4l/media-ioc-setup-link.xml |    3 +
 Documentation/media-framework.txt                  |   38 ++++++++++
 drivers/media/media-entity.c                       |   74 ++++++++++++++++++++
 include/linux/media.h                              |    1 +
 include/media/media-entity.h                       |   10 +++
 6 files changed, 131 insertions(+), 0 deletions(-)

diff --git a/Documentation/DocBook/v4l/media-ioc-enum-links.xml b/Documentation/DocBook/v4l/media-ioc-enum-links.xml
index bcec89b..aa164f4 100644
--- a/Documentation/DocBook/v4l/media-ioc-enum-links.xml
+++ b/Documentation/DocBook/v4l/media-ioc-enum-links.xml
@@ -179,6 +179,11 @@
 	    <entry>The link enabled state can't be modified at runtime. An
 	    immutable link is always enabled.</entry>
 	  </row>
+	  <row>
+	    <entry><constant>MEDIA_LINK_FLAG_DYNAMIC</constant></entry>
+	    <entry>The link enabled state can be modified during streaming. This
+	 ...
[ message continues ]

Create the following two ioctls and implement them at the media device
level to enumerate entities, pads and links.

- MEDIA_IOC_ENUM_ENTITIES: Enumerate entities and their properties
- MEDIA_IOC_ENUM_LINKS: Enumerate all pads and links for a given entity

Entity IDs can be non-contiguous. Userspace applications should
enumerate entities using the MEDIA_ENTITY_ID_FLAG_NEXT flag. When the
flag is set in the entity ID, the MEDIA_IOC_ENUM_ENTITIES will return
the next entity with an ID bigger than the requested one.

Only forward links that originate at one of the entity's source pads are
returned during the enumeration process.

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Sakari Ailus <sakari.ailus@maxwell.research.nokia.com>
---
 Documentation/DocBook/media-entities.tmpl          |    8 +
 Documentation/DocBook/v4l/media-controller.xml     |    2 +
 .../DocBook/v4l/media-ioc-device-info.xml          |    3 +-
 .../DocBook/v4l/media-ioc-enum-entities.xml        |  308 ++++++++++++++++++++
 Documentation/DocBook/v4l/media-ioc-enum-links.xml |  202 +++++++++++++
 drivers/media/media-device.c                       |  123 ++++++++
 include/linux/media.h                              |   85 ++++++
 include/media/media-entity.h                       |   24 +--
 8 files changed, 731 insertions(+), 24 deletions(-)
 create mode 100644 Documentation/DocBook/v4l/media-ioc-enum-entities.xml
 create mode 100644 Documentation/DocBook/v4l/media-ioc-enum-links.xml

diff --git a/Documentation/DocBook/media-entities.tmpl b/Documentation/DocBook/media-entities.tmpl
index 6af3375..6e7dae4 100644
--- a/Documentation/DocBook/media-entities.tmpl
+++ b/Documentation/DocBook/media-entities.tmpl
@@ -92,6 +92,8 @@
 <!ENTITY VIDIOC-UNSUBSCRIBE-EVENT "<link linkend='vidioc-subscribe-event'><constant>VIDIOC_UNSUBSCRIBE_EVENT</constant></link>">
 
 <!ENTITY MEDIA-IOC-DEVICE-INFO "<link ...
[ message continues ]

Create the following ioctl and implement it at the media device level to
query device information.

- MEDIA_IOC_DEVICE_INFO: Query media device information

The ioctl and its data structure are defined in the new kernel header
linux/media.h available to userspace applications.

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
 Documentation/DocBook/media-entities.tmpl          |   12 ++
 Documentation/DocBook/v4l/media-controller.xml     |   10 ++
 Documentation/DocBook/v4l/media-func-close.xml     |   59 +++++++++
 Documentation/DocBook/v4l/media-func-ioctl.xml     |  116 +++++++++++++++++
 Documentation/DocBook/v4l/media-func-open.xml      |   94 ++++++++++++++
 .../DocBook/v4l/media-ioc-device-info.xml          |  132 ++++++++++++++++++++
 drivers/media/media-device.c                       |   57 +++++++++
 include/linux/Kbuild                               |    1 +
 include/linux/media.h                              |   45 +++++++
 9 files changed, 526 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/DocBook/v4l/media-func-close.xml
 create mode 100644 Documentation/DocBook/v4l/media-func-ioctl.xml
 create mode 100644 Documentation/DocBook/v4l/media-func-open.xml
 create mode 100644 Documentation/DocBook/v4l/media-ioc-device-info.xml
 create mode 100644 include/linux/media.h

diff --git a/Documentation/DocBook/media-entities.tmpl b/Documentation/DocBook/media-entities.tmpl
index 61d6f11..6af3375 100644
--- a/Documentation/DocBook/media-entities.tmpl
+++ b/Documentation/DocBook/media-entities.tmpl
@@ -11,6 +11,10 @@
 <!ENTITY func-select "<link linkend='func-select'><function>select()</function></link>">
 <!ENTITY func-write "<link linkend='func-write'><function>write()</function></link>">
 
+<!ENTITY media-func-close "<link linkend='media-func-close'><function>close()</function></link>">
+<!ENTITY media-func-ioctl "<link linkend='media-func-ioctl'><function>ioctl()</function></link>">
+<!ENTITY media-func-open "<link ...
[ message continues ]

As video hardware pipelines become increasingly complex and
configurable, the current hardware description through v4l2 subdevices
reaches its limits. In addition to enumerating and configuring
subdevices, video camera drivers need a way to discover and modify at
runtime how those subdevices are connected. This is done through new
elements called entities, pads and links.

An entity is a basic media hardware building block. It can correspond to
a large variety of logical blocks such as physical hardware devices
(CMOS sensor for instance), logical hardware devices (a building block
in a System-on-Chip image processing pipeline), DMA channels or physical
connectors.

A pad is a connection endpoint through which an entity can interact with
other entities. Data (not restricted to video) produced by an entity
flows from the entity's output to one or more entity inputs. Pads should
not be confused with physical pins at chip boundaries.

A link is a point-to-point oriented connection between two pads, either
on the same entity or on different entities. Data flows from a source
pad to a sink pad.

Links are stored in the source entity. To make backwards graph walk
faster, a copy of all links is also stored in the sink entity. The copy
is known as a backlink and is only used to help graph traversal.

The entity API is made of three functions:

- media_entity_init() initializes an entity. The caller must provide an
array of pads as well as an estimated number of links. The links array
is allocated dynamically and will be reallocated if it grows beyond the
initial estimate.

- media_entity_cleanup() frees resources allocated for an entity. It
must be called during the cleanup phase after unregistering the entity
and before freeing it.

- media_entity_create_link() creates a link between two entities. An
entry in the link array of each entity is allocated and stores pointers
to source and sink pads.

When a media device is unregistered, all its entities are ...
[ message continues ]

Hi Laurent,

I promised to look at the new type names, so here is my opinion:

On Monday, December 20, 2010 12:36:26 Laurent Pinchart wrote:


Using V4L2_SUBDEV instead of just SUBDEV is definitely an improvement.

However, I think the defines are getting way too long and I would propose
to use the ME_ prefix instead of MEDIA_ENTITY_. Also ML_ instead of MEDIA_LINK_
and MP_ instead of MEDIA_PAD_.

That way it is less of an alphabet soup when reading code.

Regards,

	Hans

-- 
Hans Verkuil - video4linux developer - sponsored by Cisco
--

[ message continues ]

Hi Hans,



I agree that the names are too long, but I'm concerned that the ME_, ML_ and 
MP_ prefixes might cause namespace clashes.

-- 
Regards,

Laurent Pinchart
--

[ message continues ]