diff options
Diffstat (limited to 'Documentation/video4linux/v4l2-framework.txt')
-rw-r--r-- | Documentation/video4linux/v4l2-framework.txt | 120 |
1 files changed, 87 insertions, 33 deletions
diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt index f2df31b088c6..1c8d4492f5c7 100644 --- a/Documentation/video4linux/v4l2-framework.txt +++ b/Documentation/video4linux/v4l2-framework.txt | |||
@@ -549,6 +549,10 @@ You should also set these fields: | |||
549 | Otherwise you give it a pointer to a struct mutex_lock and before any | 549 | Otherwise you give it a pointer to a struct mutex_lock and before any |
550 | of the v4l2_file_operations is called this lock will be taken by the | 550 | of the v4l2_file_operations is called this lock will be taken by the |
551 | core and released afterwards. | 551 | core and released afterwards. |
552 | - prio: keeps track of the priorities. Used to implement VIDIOC_G/S_PRIORITY. | ||
553 | If left to NULL, then it will use the struct v4l2_prio_state in v4l2_device. | ||
554 | If you want to have a separate priority state per (group of) device node(s), | ||
555 | then you can point it to your own struct v4l2_prio_state. | ||
552 | - parent: you only set this if v4l2_device was registered with NULL as | 556 | - parent: you only set this if v4l2_device was registered with NULL as |
553 | the parent device struct. This only happens in cases where one hardware | 557 | the parent device struct. This only happens in cases where one hardware |
554 | device has multiple PCI devices that all share the same v4l2_device core. | 558 | device has multiple PCI devices that all share the same v4l2_device core. |
@@ -559,8 +563,10 @@ You should also set these fields: | |||
559 | PCI device it is setup without a parent device. But when the struct | 563 | PCI device it is setup without a parent device. But when the struct |
560 | video_device is setup you do know which parent PCI device to use. | 564 | video_device is setup you do know which parent PCI device to use. |
561 | 565 | ||
562 | If you use v4l2_ioctl_ops, then you should set either .unlocked_ioctl or | 566 | If you use v4l2_ioctl_ops, then you should set .unlocked_ioctl to video_ioctl2 |
563 | .ioctl to video_ioctl2 in your v4l2_file_operations struct. | 567 | in your v4l2_file_operations struct. |
568 | |||
569 | Do not use .ioctl! This is deprecated and will go away in the future. | ||
564 | 570 | ||
565 | The v4l2_file_operations struct is a subset of file_operations. The main | 571 | The v4l2_file_operations struct is a subset of file_operations. The main |
566 | difference is that the inode argument is omitted since it is never used. | 572 | difference is that the inode argument is omitted since it is never used. |
@@ -753,39 +759,24 @@ struct v4l2_fh | |||
753 | -------------- | 759 | -------------- |
754 | 760 | ||
755 | struct v4l2_fh provides a way to easily keep file handle specific data | 761 | struct v4l2_fh provides a way to easily keep file handle specific data |
756 | that is used by the V4L2 framework. Using v4l2_fh is optional for | 762 | that is used by the V4L2 framework. New drivers must use struct v4l2_fh |
757 | drivers. | 763 | since it is also used to implement priority handling (VIDIOC_G/S_PRIORITY). |
758 | 764 | ||
759 | The users of v4l2_fh (in the V4L2 framework, not the driver) know | 765 | The users of v4l2_fh (in the V4L2 framework, not the driver) know |
760 | whether a driver uses v4l2_fh as its file->private_data pointer by | 766 | whether a driver uses v4l2_fh as its file->private_data pointer by |
761 | testing the V4L2_FL_USES_V4L2_FH bit in video_device->flags. | 767 | testing the V4L2_FL_USES_V4L2_FH bit in video_device->flags. This bit is |
762 | 768 | set whenever v4l2_fh_init() is called. | |
763 | Useful functions: | ||
764 | |||
765 | - v4l2_fh_init() | ||
766 | |||
767 | Initialise the file handle. This *MUST* be performed in the driver's | ||
768 | v4l2_file_operations->open() handler. | ||
769 | |||
770 | - v4l2_fh_add() | ||
771 | 769 | ||
772 | Add a v4l2_fh to video_device file handle list. May be called after | 770 | struct v4l2_fh is allocated as a part of the driver's own file handle |
773 | initialising the file handle. | 771 | structure and file->private_data is set to it in the driver's open |
774 | 772 | function by the driver. | |
775 | - v4l2_fh_del() | ||
776 | |||
777 | Unassociate the file handle from video_device(). The file handle | ||
778 | exit function may now be called. | ||
779 | 773 | ||
780 | - v4l2_fh_exit() | 774 | In many cases the struct v4l2_fh will be embedded in a larger structure. |
775 | In that case you should call v4l2_fh_init+v4l2_fh_add in open() and | ||
776 | v4l2_fh_del+v4l2_fh_exit in release(). | ||
781 | 777 | ||
782 | Uninitialise the file handle. After uninitialisation the v4l2_fh | 778 | Drivers can extract their own file handle structure by using the container_of |
783 | memory can be freed. | 779 | macro. Example: |
784 | |||
785 | struct v4l2_fh is allocated as a part of the driver's own file handle | ||
786 | structure and is set to file->private_data in the driver's open | ||
787 | function by the driver. Drivers can extract their own file handle | ||
788 | structure by using the container_of macro. Example: | ||
789 | 780 | ||
790 | struct my_fh { | 781 | struct my_fh { |
791 | int blah; | 782 | int blah; |
@@ -802,15 +793,21 @@ int my_open(struct file *file) | |||
802 | 793 | ||
803 | ... | 794 | ... |
804 | 795 | ||
796 | my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL); | ||
797 | |||
798 | ... | ||
799 | |||
805 | ret = v4l2_fh_init(&my_fh->fh, vfd); | 800 | ret = v4l2_fh_init(&my_fh->fh, vfd); |
806 | if (ret) | 801 | if (ret) { |
802 | kfree(my_fh); | ||
807 | return ret; | 803 | return ret; |
804 | } | ||
808 | 805 | ||
809 | v4l2_fh_add(&my_fh->fh); | 806 | ... |
810 | 807 | ||
811 | file->private_data = &my_fh->fh; | 808 | file->private_data = &my_fh->fh; |
812 | 809 | v4l2_fh_add(&my_fh->fh); | |
813 | ... | 810 | return 0; |
814 | } | 811 | } |
815 | 812 | ||
816 | int my_release(struct file *file) | 813 | int my_release(struct file *file) |
@@ -819,8 +816,65 @@ int my_release(struct file *file) | |||
819 | struct my_fh *my_fh = container_of(fh, struct my_fh, fh); | 816 | struct my_fh *my_fh = container_of(fh, struct my_fh, fh); |
820 | 817 | ||
821 | ... | 818 | ... |
819 | v4l2_fh_del(&my_fh->fh); | ||
820 | v4l2_fh_exit(&my_fh->fh); | ||
821 | kfree(my_fh); | ||
822 | return 0; | ||
822 | } | 823 | } |
823 | 824 | ||
825 | Below is a short description of the v4l2_fh functions used: | ||
826 | |||
827 | int v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev) | ||
828 | |||
829 | Initialise the file handle. This *MUST* be performed in the driver's | ||
830 | v4l2_file_operations->open() handler. | ||
831 | |||
832 | void v4l2_fh_add(struct v4l2_fh *fh) | ||
833 | |||
834 | Add a v4l2_fh to video_device file handle list. Must be called once the | ||
835 | file handle is completely initialized. | ||
836 | |||
837 | void v4l2_fh_del(struct v4l2_fh *fh) | ||
838 | |||
839 | Unassociate the file handle from video_device(). The file handle | ||
840 | exit function may now be called. | ||
841 | |||
842 | void v4l2_fh_exit(struct v4l2_fh *fh) | ||
843 | |||
844 | Uninitialise the file handle. After uninitialisation the v4l2_fh | ||
845 | memory can be freed. | ||
846 | |||
847 | |||
848 | If struct v4l2_fh is not embedded, then you can use these helper functions: | ||
849 | |||
850 | int v4l2_fh_open(struct file *filp) | ||
851 | |||
852 | This allocates a struct v4l2_fh, initializes it and adds it to the struct | ||
853 | video_device associated with the file struct. | ||
854 | |||
855 | int v4l2_fh_release(struct file *filp) | ||
856 | |||
857 | This deletes it from the struct video_device associated with the file | ||
858 | struct, uninitialised the v4l2_fh and frees it. | ||
859 | |||
860 | These two functions can be plugged into the v4l2_file_operation's open() and | ||
861 | release() ops. | ||
862 | |||
863 | |||
864 | Several drivers need to do something when the first file handle is opened and | ||
865 | when the last file handle closes. Two helper functions were added to check | ||
866 | whether the v4l2_fh struct is the only open filehandle of the associated | ||
867 | device node: | ||
868 | |||
869 | int v4l2_fh_is_singular(struct v4l2_fh *fh) | ||
870 | |||
871 | Returns 1 if the file handle is the only open file handle, else 0. | ||
872 | |||
873 | int v4l2_fh_is_singular_file(struct file *filp) | ||
874 | |||
875 | Same, but it calls v4l2_fh_is_singular with filp->private_data. | ||
876 | |||
877 | |||
824 | V4L2 events | 878 | V4L2 events |
825 | ----------- | 879 | ----------- |
826 | 880 | ||