[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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
This commit is contained in:
Mauro Carvalho Chehab
parent
d888f8d7d8
commit
575f93084d
|
|
@ -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);
|
||||
/**
|
||||
* 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);
|
||||
|
||||
/* 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_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);
|
||||
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. */
|
||||
/**
|
||||
* 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)
|
||||
{
|
||||
|
|
|
|||
Loading…
Reference in New Issue