Now that we moved the content of the media-framework.txt into
the kerneldoc documentation, move the per-function specific
documentation to the corresponding functions and clean it up.

It would be good if we had already the markdown kernel-doc
patches merged upstream, but, while we doesn't have it,
let's make it less ugly at device-drivers.xml.
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

This function was used in the past to free the links
that were allocated by the media controller core.

However, this is not needed anymore. We should likely
get rid of the funcion on some function, but, for now,
let's just convert into an inlined function and let the
compiler to get rid of it.
Suggested-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

Instead of using a text file, let's put it together with the
struct documentation for the Media Controller.
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

Both revision and group_id fields were never used and were always
initialized to zero. Remove them.
Suggested-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

With the MC next gen rework, what's left for media_entity_init()
is to just initialize the PADs. However, certain devices, like
a FLASH led/light doesn't have any input or output PAD.

So, there's no reason why calling media_entity_init() would be
mandatory. Also, despite its name, what this function actually
does is to initialize the PADs data. So, rename it to
media_entity_pads_init() in order to reflect that.

The media entity actual init happens during entity register,
at media_device_register_entity(). We should move init of
num_links and num_backlinks to it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

The __media_device_enum_links() copies links definitions from
Kernelspace to userspace. It has to work with 3 structs that
handle with links. Better name them to:
	link: Kernelspace internal link representation, of the
		type media_link;
	klink_desc:  struct media_link_desc pointer to the
		kernel memory where the data will be filled;
	ulink_desc:  struct media_link_desc pointer to the
		memory where the data will be copied to
		userspace.
Suggested-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

It is better to keep the headers in alphabetic order.
Suggested-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

If an entity is registered with a media device before is initialized
with media_device_register_entity(), the number of pads won't be set
so media_device_register_entity() won't create pad objects and add
it to the media device pads list.

Do this at entity initialization time if the entity was registered
before so the graph is complete and correct regardless of the order
in which the entities are initialized and registered.
Suggested-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Signed-off-by: Javier Martinez Canillas <javier@osg.samsung.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

The entity->num_pads are defined as u16. So, better to use an
unsigned int, as this prevents additional warnings when W=2
(or W=1 on some architectures).

The "i" counter at __media_device_get_topology() is also a
monotonic counter that should never be below zero. So,
make it unsigned too.
Suggested-by: Sakari Ailus <sakari.ailus@iki.fi>
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

We should not be creating device nodes at IRQ contexts. So,
the only flags we'll be using will be GFP_KERNEL. Let's
remove the gfp_flags, in order to make the interface simpler.

If we ever need it, it would be easy to revert those changes.

While here, remove an extra blank line.
Suggested-by: Sakari Ailus <sakari.ailus@iki.fi>
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

Indirect links are those whose interface indirectly controls
other functions.

There are two interfaces that have indirect controls at the DVB
side:
- the network interface, which also controls the demux;
- the DVR interface which also controls the demux.

One could argue that the frontend control to the tuner is indirect.
Well, that's debatable. There's no way to create subdev interfaces
for tuner and demod, as those devices are tightly coupled. So, it
was decided that just one interface is the best to control both
entities, and there's no plan (or easy way) to decouple both. So,
the DVB frontend interface should link to both entities.
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

Cleanup the code a little bit by moving the routine that creates
links between DVR and demux to the I/O entitis into a separate
function.

While here, fix the code to use strncmp() instead of strcmp().
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

Due to the rename, the documentation became outdated.

Update it to reflect what's there at media.h.
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

Rename the userspace types from MEDIA_ENT_T_ to MEDIA_ENT_F_
and add the backward compatibility bits.

The changes at the .c files was generated by the following
coccinelle script:

@@
@@
-MEDIA_ENT_T_UNKNOWN
+MEDIA_ENT_F_UNKNOWN
@@
@@
-MEDIA_ENT_T_DVB_BASE
+MEDIA_ENT_F_DVB_BASE
@@
@@
-MEDIA_ENT_T_V4L2_BASE
+MEDIA_ENT_F_V4L2_BASE
@@
@@
-MEDIA_ENT_T_V4L2_SUBDEV_BASE
+MEDIA_ENT_F_V4L2_SUBDEV_BASE
@@
@@
-MEDIA_ENT_T_CONNECTOR_BASE
+MEDIA_ENT_F_CONNECTOR_BASE
@@
@@
-MEDIA_ENT_T_V4L2_VIDEO
+MEDIA_ENT_F_IO_V4L
@@
@@
-MEDIA_ENT_T_V4L2_VBI
+MEDIA_ENT_F_IO_VBI
@@
@@
-MEDIA_ENT_T_V4L2_SWRADIO
+MEDIA_ENT_F_IO_SWRADIO
@@
@@
-MEDIA_ENT_T_V4L2_SUBDEV_UNKNOWN
+MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN
@@
@@
-MEDIA_ENT_T_CONN_RF
+MEDIA_ENT_F_CONN_RF
@@
@@
-MEDIA_ENT_T_CONN_SVIDEO
+MEDIA_ENT_F_CONN_SVIDEO
@@
@@
-MEDIA_ENT_T_CONN_COMPOSITE
+MEDIA_ENT_F_CONN_COMPOSITE
@@
@@
-MEDIA_ENT_T_CONN_TEST
+MEDIA_ENT_F_CONN_TEST
@@
@@
-MEDIA_ENT_T_V4L2_SUBDEV_SENSOR
+MEDIA_ENT_F_CAM_SENSOR
@@
@@
-MEDIA_ENT_T_V4L2_SUBDEV_FLASH
+MEDIA_ENT_F_FLASH
@@
@@
-MEDIA_ENT_T_V4L2_SUBDEV_LENS
+MEDIA_ENT_F_LENS
@@
@@
-MEDIA_ENT_T_V4L2_SUBDEV_DECODER
+MEDIA_ENT_F_ATV_DECODER
@@
@@
-MEDIA_ENT_T_V4L2_SUBDEV_TUNER
+MEDIA_ENT_F_TUNER
@@
@@
-MEDIA_ENT_T_DVB_DEMOD
+MEDIA_ENT_F_DTV_DEMOD
@@
@@
-MEDIA_ENT_T_DVB_DEMUX
+MEDIA_ENT_F_TS_DEMUX
@@
@@
-MEDIA_ENT_T_DVB_TSOUT
+MEDIA_ENT_F_IO_DTV
@@
@@
-MEDIA_ENT_T_DVB_CA
+MEDIA_ENT_F_DTV_CA
@@
@@
-MEDIA_ENT_T_DVB_NET_DECAP
+MEDIA_ENT_F_DTV_NET_DECAP
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

Now that entities have a main function, expose it via
MEDIA_IOC_G_TOPOLOGY ioctl.

Please notice that some entities may have secundary functions.
Such use case will be addressed later, when we add support for the
Media Controller properties.
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

Entities should have one or more functions. Calling it as a
type proofed to not be correct, as an entity could eventually
have more than one type.

So, rename the field as function.

Please notice that this patch doesn't extend support for
multiple function entities. Such change will happen when
we have real case drivers using it.

No functional changes.
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

Drivers should check if media_create_pad_link() actually
worked.
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

If the graph creation fails, don't register the device.
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

If the graph creation fails, don't register the device.
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

Drivers should check if interfaces and interface links were
created. Add a must_check for them.
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

If media controller is enabled and mdev is filled, it should
ensure that the media graph will be properly initialized.

Enforce that.
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

Interface links are normally enabled, meaning that the interfaces are
bound to the entities. So, any ioctl send to the interface are reflected
at the entities managed by the interface.

However, when a device is used, other interfaces for the same hardware
could be decoupled from the entities linked to them, because the
hardware may have some parts busy.

That's for example, what happens when an hybrid TV device is in use.
If it is streaming analog TV or capturing signals from S-Video/Composite
connectors, typically the digital part of the hardware can't be used and
vice-versa.

This is generally due to some internal hardware or firmware limitation,
that it is not easily mapped via data pipelines.

What the Kernel drivers do internally is that they decouple the hardware
from the interface. So, all changes, if allowed, are done only at some
interface cache, but not physically changed at the hardware.

The usage is similar to the usage of the MEDIA_LNK_FL_ENABLED on data
links. So, let's use the same flag to indicate if either the interface
to entity link is bound/enabled or not.
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

Due to the graph traversal algorithm currently in usage, we
need a copy of all data links. Those backlinks should not be
send to userspace, as otherwise, all links there will be
duplicated.
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

Now that connectors are entities, we need to represent the
connector links.
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

Depending on the input, an au0828 may have a different
number of connectors. add entities to represent them.
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

Add entities to represent the connectors that exists inside a
hybrid TV device.
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

Only a few structs are documented on kernel-doc-nano format
(the ones added by the MC next gen patches).

Add a documentation for all structs, and ensure that they'll
be producing the documentation at the Kernel's device driver
DocBook.
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

V4L2 device (and subdevice) nodes should create an interface, if the
Media Controller support is enabled.

Please notice that radio devices should not create an entity, as radio
input/output is either via wires or via ALSA.
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

Right now, if something gets wrong at dvb_create_media_entity()
or at dvb_create_media_graph(), the device will still be
registered.

Change the logic to properly handle it and free all media graph
objects if something goes wrong at dvb_register_device().

Also, change the logic at dvb_create_media_graph() to return
an error code if something goes wrong. It is up to the
caller to implement the right logic and to call
dvb_unregister_device() to unregister the already-created
objects.

While here, add a missing logic to unregister the created
interfaces.
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

The logic is testing if num_links==0 at the wrong place. Due to
that, a backlink may be kept without removal, causing KASAN
to complain about usage after free during either entity or
link removal.
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

The media_entity_cleanup() function only cleans up the entity links list
but this operation is already made in media_device_unregister_entity().

In most cases this should be harmless (besides having duplicated code)
since the links list would be empty so the iteration would not happen
but the links list is initialized in media_device_register_entity() so
if a driver fails to register an entity with a media device and clean up
the entity in the error path, a NULL deference pointer error will happen.

So don't try to empty the links list in media_entity_cleanup() since
is either done already or haven't been initialized yet.
Signed-off-by: Javier Martinez Canillas <javier@osg.samsung.com>

The DVB core needs to unregister the media device. So, we
can't call au0828_unregister_media_device() before calling
au0828_dvb_unregister(), otherwise the DVB MC free code
(that will be implemented on the next patch) will fail.
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

Interface links are normally enabled, meaning that the interfaces are
bound to the entities. So, any ioctl sent to the interface are reflected
at the entities managed by the interface.

However, when a device is in use, other interfaces for the same hardware
could be decoupled from the entities linked to them, because the
hardware may have some parts busy.

That's for example, what happens when an hybrid TV device is in use.
If it is streaming analog TV or capturing signals from S-Video/Composite
connectors, typically the digital part of the hardware can't be used and
vice-versa.

This is generally due to some internal hardware or firmware limitation,
that it is not easily mapped via data pipelines.

What the Kernel drivers do internally is that they decouple the hardware
from the interface. So, all changes, if allowed, are done only at some
interface cache, but not physically changed at the hardware.

The usage is similar to the usage of the MEDIA_LNK_FL_ENABLED on data
links. So, let's use the same flag to indicate if either the interface
to entity link is bound/enabled or not.
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

Tuners actually have at least one connector on its input.

Add a PAD to connect it.
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

Some parts of the media controller are using mutexes while
others are using spin locks in order to protect creation
and removal of elements in the graph. That's wrong!

Also, the V4L2 core can remove graph elements on non-interactive
context:
	BUG: sleeping function called from invalid context at include/linux/sched.h:2776

Fix it by always using spin locks for graph element addition/removal,
just like entity creation/removal is protected at media-device.c
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

Just like what's done with entities, when the media controller is
unregistered, release any interface and interface links that
might still be there.
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

Interface links connected to an entity should be removed
before the entity itself can be removed.
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

Add functions to explicitly unregister all entity links.
This function is called automatically when an entity
link is destroyed.
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

Add support for the new MEDIA_IOC_G_TOPOLOGY ioctl, according
with the RFC for the MC next generation.
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

Every time a graph object is added or removed, the version
of the topology changes. That's a requirement for the new
MEDIA_IOC_G_TOPOLOGY, in order to allow userspace to know
that the topology has changed after a previous call to it.
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>