Commit 575f9308 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab

[media] v4l2-device.h: document functions

The functions at v4l2-device.h are not using the proper
markups. Add it, and include at the v4l2-core.rst.
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
parent d888f8d7
......@@ -11,6 +11,8 @@ Video2Linux devices
.. kernel-doc:: include/media/v4l2-ctrls.h
.. kernel-doc:: include/media/v4l2-device.h
.. kernel-doc:: include/media/v4l2-dv-timings.h
.. kernel-doc:: include/media/v4l2-event.h
......
......@@ -25,100 +25,188 @@
#include <media/v4l2-subdev.h>
#include <media/v4l2-dev.h>
/* Each instance of a V4L2 device should create the v4l2_device struct,
either stand-alone or embedded in a larger struct.
It allows easy access to sub-devices (see v4l2-subdev.h) and provides
basic V4L2 device-level support.
*/
#define V4L2_DEVICE_NAME_SIZE (20 + 16)
struct v4l2_ctrl_handler;
/**
* struct v4l2_device - main struct to for V4L2 device drivers
*
* @dev: pointer to struct device.
* @mdev: pointer to struct media_device
* @subdevs: used to keep track of the registered subdevs
* @lock: lock this struct; can be used by the driver as well
* if this struct is embedded into a larger struct.
* @name: unique device name, by default the driver name + bus ID
* @notify: notify callback called by some sub-devices.
* @ctrl_handler: The control handler. May be NULL.
* @prio: Device's priority state
* @ref: Keep track of the references to this struct.
* @release: Release function that is called when the ref count
* goes to 0.
*
* Each instance of a V4L2 device should create the v4l2_device struct,
* either stand-alone or embedded in a larger struct.
*
* It allows easy access to sub-devices (see v4l2-subdev.h) and provides
* basic V4L2 device-level support.
*
* .. note::
*
* #) dev->driver_data points to this struct.
* #) dev might be NULL if there is no parent device
*/
struct v4l2_device {
/* dev->driver_data points to this struct.
Note: dev might be NULL if there is no parent device
as is the case with e.g. ISA devices. */
struct device *dev;
#if defined(CONFIG_MEDIA_CONTROLLER)
struct media_device *mdev;
#endif
/* used to keep track of the registered subdevs */
struct list_head subdevs;
/* lock this struct; can be used by the driver as well if this
struct is embedded into a larger struct. */
spinlock_t lock;
/* unique device name, by default the driver name + bus ID */
char name[V4L2_DEVICE_NAME_SIZE];
/* notify callback called by some sub-devices. */
void (*notify)(struct v4l2_subdev *sd,
unsigned int notification, void *arg);
/* The control handler. May be NULL. */
struct v4l2_ctrl_handler *ctrl_handler;
/* Device's priority state */
struct v4l2_prio_state prio;
/* Keep track of the references to this struct. */
struct kref ref;
/* Release function that is called when the ref count goes to 0. */
void (*release)(struct v4l2_device *v4l2_dev);
};
/**
* v4l2_device_get - gets a V4L2 device reference
*
* @v4l2_dev: pointer to struct v4l2_device
*
* This is an ancillary routine meant to increment the usage for the
* struct v4l2_device pointed by @v4l2_dev.
*/
static inline void v4l2_device_get(struct v4l2_device *v4l2_dev)
{
kref_get(&v4l2_dev->ref);
}
/**
* v4l2_device_put - putss a V4L2 device reference
*
* @v4l2_dev: pointer to struct v4l2_device
*
* This is an ancillary routine meant to decrement the usage for the
* struct v4l2_device pointed by @v4l2_dev.
*/
int v4l2_device_put(struct v4l2_device *v4l2_dev);
/* Initialize v4l2_dev and make dev->driver_data point to v4l2_dev.
dev may be NULL in rare cases (ISA devices). In that case you
must fill in the v4l2_dev->name field before calling this function. */
int __must_check v4l2_device_register(struct device *dev, struct v4l2_device *v4l2_dev);
/* Optional function to initialize the name field of struct v4l2_device using
the driver name and a driver-global atomic_t instance.
This function will increment the instance counter and returns the instance
value used in the name.
Example:
static atomic_t drv_instance = ATOMIC_INIT(0);
...
instance = v4l2_device_set_name(&v4l2_dev, "foo", &drv_instance);
The first time this is called the name field will be set to foo0 and
this function returns 0. If the name ends with a digit (e.g. cx18),
then the name will be set to cx18-0 since cx180 looks really odd. */
/**
* v4l2_device_register -Initialize v4l2_dev and make dev->driver_data
* point to v4l2_dev.
*
* @dev: pointer to struct device
* @v4l2_dev: pointer to struct v4l2_device
*
* .. note::
* dev may be NULL in rare cases (ISA devices).
* In such case the caller must fill in the v4l2_dev->name field
* before calling this function.
*/
int __must_check v4l2_device_register(struct device *dev,
struct v4l2_device *v4l2_dev);
/**
* v4l2_device_set_name - Optional function to initialize the
* name field of struct v4l2_device
*
* @v4l2_dev: pointer to struct v4l2_device
* @basename: base name for the device name
* @instance: pointer to a static atomic_t var with the instance usage for
* the device driver.
*
* v4l2_device_set_name() initializes the name field of struct v4l2_device
* using the driver name and a driver-global atomic_t instance.
*
* This function will increment the instance counter and returns the
* instance value used in the name.
*
* Example:
*
* static atomic_t drv_instance = ATOMIC_INIT(0);
*
* ...
*
* instance = v4l2_device_set_name(&v4l2_dev, "foo", &drv_instance);
*
* The first time this is called the name field will be set to foo0 and
* this function returns 0. If the name ends with a digit (e.g. cx18),
* then the name will be set to cx18-0 since cx180 would look really odd.
*/
int v4l2_device_set_name(struct v4l2_device *v4l2_dev, const char *basename,
atomic_t *instance);
/* Set v4l2_dev->dev to NULL. Call when the USB parent disconnects.
Since the parent disappears this ensures that v4l2_dev doesn't have an
invalid parent pointer. */
atomic_t *instance);
/**
* v4l2_device_disconnect - Change V4L2 device state to disconnected.
*
* @v4l2_dev: pointer to struct v4l2_device
*
* Should be called when the USB parent disconnects.
* Since the parent disappears, this ensures that v4l2_dev doesn't have
* an invalid parent pointer.
*
* .. note:: This function sets v4l2_dev->dev to NULL.
*/
void v4l2_device_disconnect(struct v4l2_device *v4l2_dev);
/* Unregister all sub-devices and any other resources related to v4l2_dev. */
/**
* v4l2_device_unregister - Unregister all sub-devices and any other
* resources related to v4l2_dev.
*
* @v4l2_dev: pointer to struct v4l2_device
*/
void v4l2_device_unregister(struct v4l2_device *v4l2_dev);
/* Register a subdev with a v4l2 device. While registered the subdev module
is marked as in-use. An error is returned if the module is no longer
loaded when you attempt to register it. */
/**
* v4l2_device_register_subdev - Registers a subdev with a v4l2 device.
*
* @v4l2_dev: pointer to struct v4l2_device
* @sd: pointer to struct v4l2_subdev
*
* While registered, the subdev module is marked as in-use.
*
* An error is returned if the module is no longer loaded on any attempts
* to register it.
*/
int __must_check v4l2_device_register_subdev(struct v4l2_device *v4l2_dev,
struct v4l2_subdev *sd);
/* Unregister a subdev with a v4l2 device. Can also be called if the subdev
wasn't registered. In that case it will do nothing. */
struct v4l2_subdev *sd);
/**
* v4l2_device_unregister_subdev - Unregisters a subdev with a v4l2 device.
*
* @sd: pointer to struct v4l2_subdev
*
* .. note ::
*
* Can also be called if the subdev wasn't registered. In such
* case, it will do nothing.
*/
void v4l2_device_unregister_subdev(struct v4l2_subdev *sd);
/* Register device nodes for all subdev of the v4l2 device that are marked with
* the V4L2_SUBDEV_FL_HAS_DEVNODE flag.
/**
* v4l2_device_register_subdev_nodes - Registers device nodes for all subdevs
* of the v4l2 device that are marked with
* the V4L2_SUBDEV_FL_HAS_DEVNODE flag.
*
* @v4l2_dev: pointer to struct v4l2_device
*/
int __must_check
v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev);
/* Send a notification to v4l2_device. */
/**
* v4l2_subdev_notify - Sends a notification to v4l2_device.
*
* @sd: pointer to struct 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
* notification type.
*/
static inline void v4l2_subdev_notify(struct v4l2_subdev *sd,
unsigned int notification, void *arg)
{
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment