[media] v4l2-fh.h: add documentation for it (4ada120e) · Commits · jan.koester / Linux

Documentation/media/kapi/v4l2-core.rst

+1 −0

Original line number	Diff line number	Diff line
		@@ -8,6 +8,7 @@ Video2Linux devices
		v4l2-dev
		v4l2-controls
		v4l2-device
		v4l2-fh
		v4l2-dv-timings
		v4l2-event
		v4l2-flash-led-class

Documentation/media/kapi/v4l2-fh.rst

0 → 100644

+3 −0

Original line number	Diff line number	Diff line
		V4L2 File Handler kAPI
		^^^^^^^^^^^^^^^^^^^^^^
		.. kernel-doc:: include/media/v4l2-fh.h

include/media/v4l2-fh.h

+96 −32

Original line number	Diff line number	Diff line
		@@ -33,6 +33,21 @@
		struct video_device;
		struct v4l2_ctrl_handler;

		/**
		* struct v4l2_fh - Describes a V4L2 file handler
		*
		* @list: list of file handlers
		* @vdev: pointer to &struct video_device
		* @ctrl_handler: pointer to &struct v4l2_ctrl_handler
		* @prio: priority of the file handler, as defined by &enum v4l2_priority
		*
		* @wait: event' s wait queue
		* @subscribed: list of subscribed events
		* @available: list of events waiting to be dequeued
		* @navailable: number of available events at @available list
		* @sequence: event sequence number
		* @m2m_ctx: pointer to &struct v4l2_m2m_ctx
		*/
		struct v4l2_fh {
		struct list_head list;
		struct video_device *vdev;
		@@ -41,8 +56,8 @@ struct v4l2_fh {

		/* Events */
		wait_queue_head_t wait;
		struct list_head subscribed; /* Subscribed events */
		struct list_head available; /* Dequeueable event */
		struct list_head subscribed;
		struct list_head available;
		unsigned int navailable;
		u32 sequence;

		@@ -51,53 +66,102 @@ struct v4l2_fh {
		#endif
		};

		/*
		* Initialise the file handle. Parts of the V4L2 framework using the
		/**
		* v4l2_fh_init - Initialise the file handle.
		*
		* @fh: pointer to &struct v4l2_fh
		* @vdev: pointer to &struct video_device
		*
		* Parts of the V4L2 framework using the
		* file handles should be initialised in this function. Must be called
		* from driver's v4l2_file_operations->open() handler if the driver
		* uses v4l2_fh.
		* from driver's v4l2_file_operations->open\(\) handler if the driver
		* uses &struct v4l2_fh.
		*/
		void v4l2_fh_init(struct v4l2_fh fh, struct video_device vdev);
		/*
		* Add the fh to the list of file handles on a video_device. The file
		* handle must be initialised first.

		/**
		* v4l2_fh_add - Add the fh to the list of file handles on a video_device.
		*
		* @fh: pointer to &struct v4l2_fh
		*
		* .. note::
		* The @fh file handle must be initialised first.
		*/
		void v4l2_fh_add(struct v4l2_fh *fh);
		/*
		* Can be used as the open() op of v4l2_file_operations.
		* It allocates a v4l2_fh and inits and adds it to the video_device associated
		* with the file pointer.

		/**
		* v4l2_fh_open - Ancillary routine that can be used as the open\(\) op
		* of v4l2_file_operations.
		*
		* @filp: pointer to struct file
		*
		* It allocates a v4l2_fh and inits and adds it to the &struct video_device
		* associated with the file pointer.
		*/
		int v4l2_fh_open(struct file *filp);
		/*
		* Remove file handle from the list of file handles. Must be called in
		* v4l2_file_operations->release() handler if the driver uses v4l2_fh.
		* On error filp->private_data will be NULL, otherwise it will point to
		* the v4l2_fh struct.

		/**
		* v4l2_fh_del - Remove file handle from the list of file handles.
		*
		* @fh: pointer to &struct v4l2_fh
		*
		* On error filp->private_data will be %NULL, otherwise it will point to
		* the &struct v4l2_fh.
		*
		* .. note::
		* Must be called in v4l2_file_operations->release\(\) handler if the driver
		* uses &struct v4l2_fh.
		*/
		void v4l2_fh_del(struct v4l2_fh *fh);
		/*
		* Release resources related to a file handle. Parts of the V4L2
		* framework using the v4l2_fh must release their resources here, too.
		* Must be called in v4l2_file_operations->release() handler if the
		* driver uses v4l2_fh.

		/**
		* v4l2_fh_exit - Release resources related to a file handle.
		*
		* @fh: pointer to &struct v4l2_fh
		*
		* Parts of the V4L2 framework using the v4l2_fh must release their
		* resources here, too.
		*
		* .. note::
		* Must be called in v4l2_file_operations->release\(\) handler if the
		* driver uses &struct v4l2_fh.
		*/
		void v4l2_fh_exit(struct v4l2_fh *fh);
		/*
		* Can be used as the release() op of v4l2_file_operations.

		/**
		* v4l2_fh_release - Ancillary routine that can be used as the release\(\) op
		* of v4l2_file_operations.
		*
		* @filp: pointer to struct file
		*
		* It deletes and exits the v4l2_fh associated with the file pointer and
		* frees it. It will do nothing if filp->private_data (the pointer to the
		* v4l2_fh struct) is NULL. This function always returns 0.
		* v4l2_fh struct) is %NULL.
		*
		* This function always returns 0.
		*/
		int v4l2_fh_release(struct file *filp);
		/*
		* Returns 1 if this filehandle is the only filehandle opened for the
		* associated video_device. If fh is NULL, then it returns 0.

		/**
		* v4l2_fh_is_singular - Returns 1 if this filehandle is the only filehandle
		* opened for the associated video_device.
		*
		* @fh: pointer to &struct v4l2_fh
		*
		* If @fh is NULL, then it returns 0.
		*/
		int v4l2_fh_is_singular(struct v4l2_fh *fh);
		/*
		* Helper function with struct file as argument. If filp->private_data is
		* NULL, then it will return 0.

		/**
		* v4l2_fh_is_singular_file - Returns 1 if this filehandle is the only
		* filehandle opened for the associated video_device.
		*
		* @filp: pointer to struct file
		*
		* This is a helper function variant of v4l2_fh_is_singular() with uses
		* struct file as argument.
		*
		* If filp->private_data is %NULL, then it will return 0.
		*/
		static inline int v4l2_fh_is_singular_file(struct file *filp)
		{