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

[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

Documentation/media/kapi/v4l2-core.rst

+2 −0
Original line number Diff line number Diff line
@@ -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

include/media/v4l2-device.h

+143 −55
Original line number Diff line number Diff line
@@ -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. */

/**

 * 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. */



/**

 * 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

/**

 * 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)

{