Merge branch 'v4l_for_linus' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media

* 'v4l_for_linus' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media: (655 commits)
  [media] revert patch: HDIC HD29L2 DMB-TH USB2.0 reference design driver
  mb86a20s: Add a few more register settings at the init seq
  mb86a20s: Group registers into the same line
  [media] [PATCH] don't reset the delivery system on DTV_CLEAR
  [media] [BUG] it913x-fe fix typo error making SNR levels unstable
  [media] cx23885: Query the CX25840 during enum_input for status
  [media] cx25840: Add support for g_input_status
  [media] rc-videomate-m1f.c Rename to match remote controler name
  [media] drivers: media: au0828: Fix dependency for VIDEO_AU0828
  [media] convert drivers/media/* to use module_platform_driver()
  [media] drivers: video: cx231xx: Fix dependency for VIDEO_CX231XX_DVB
  [media] Exynos4 JPEG codec v4l2 driver
  [media] doc: v4l: selection: choose pixels as units for selection rectangles
  [media] v4l: s5p-tv: mixer: fix setup of VP scaling
  [media] v4l: s5p-tv: mixer: add support for selection API
  [media] v4l: emulate old crop API using extended crop/compose API
  [media] doc: v4l: add documentation for selection API
  [media] doc: v4l: add binary images for selection API
  [media] v4l: add support for selection api
  [media] hd29l2: fix review findings
  ...

1 files changed, 11 insertions, 0 deletions

diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt
index f8dcabf7852c..659b2ba12a4f 100644
--- a/Documentation/video4linux/v4l2-framework.txt
+++ b/Documentation/video4linux/v4l2-framework.txt
@@ -612,6 +612,12 @@ You can set a pointer to a mutex_lock in struct video_device. Usually this
 will be either a top-level mutex or a mutex per device node. If you want
 finer-grained locking then you have to set it to NULL and do you own locking.
 
+It is up to the driver developer to decide which method to use. However, if
+your driver has high-latency operations (for example, changing the exposure
+of a USB webcam might take a long time), then you might be better off with
+doing your own locking if you want to allow the user to do other things with
+the device while waiting for the high-latency command to finish.
+
 If a lock is specified then all file operations will be serialized on that
 lock. If you use videobuf then you must pass the same lock to the videobuf
 queue initialize function: if videobuf has to wait for a frame to arrive, then
@@ -619,6 +625,11 @@ it will temporarily unlock the lock and relock it afterwards. If your driver
 also waits in the code, then you should do the same to allow other processes
 to access the device node while the first process is waiting for something.
 
+In the case of videobuf2 you will need to implement the wait_prepare and
+wait_finish callbacks to unlock/lock if applicable. In particular, if you use
+the lock in struct video_device then you must unlock/lock this mutex in
+wait_prepare and wait_finish.
+
 The implementation of a hotplug disconnect should also take the lock before
 calling v4l2_device_disconnect.