Merge tag 'media/v7.3-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-mediagrafted

Pull media updates from Mauro Carvalho Chehab:

 - v4l2-core: added ISP statistics support and per-block validation

 - v4l2-core: Allow unknown HDR10 white point and luminance

 - New camera sensors: Sony IMX678 and IMX471m, Himax HM1092 IR sensor

 - New codec: Milos: VPU v2.0 codec support

 - isp driver: gained support for Dreamchip RPPX1 ISP framework

 - vsp1 driver: gained support for RZ/T2H and RZ/N2H

 - Novalake driver: gained CVS support for new NVL hardware

 - dvb-core: fix feed leak on failed DMX_ADD_PID

 - several driver fixes, cleanups and minor improvements

* tag 'media/v7.3-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media: (308 commits)
  media: ipu-bridge: check all DMI entries when overriding sensor rotation
  media: v4l2-async: avoid deleting unlinked ASC entry on link error
  media: rzg2l-cru: Align bytesperline to hardware DMA stride requirement
  media: intel/ipu6: fix async notifier cleanup leak on parse error
  media: staging/ipu7: fix async notifier UAF on probe error path
  media: amd: isp4: fix self-deadlock in isp4sd_pwron_and_init() error path
  media: amd: isp4: release partial allocations in isp4if_alloc_fw_gpumem()
  media: rcar-isp: Fix VSPX reference leaks
  media: rcar-isp: Release ISPCORE resources
  media: i2c: imx415: Release runtime PM reference on VBLANK error
  media: i2c: imx415: Return test pattern write errors
  media: renesas: vsp1: Declare index variables in for loop statement
  media: renesas: vsp1: Make reset control optional to support platforms without a reset line
  media: dt-bindings: media: renesas,vsp1: Document RZ/T2H and RZ/N2H SoCs
  media: dt-bindings: media: renesas,fcp: Document RZ/T2H and RZ/N2H SoCs
  media: nxp: imx8-isi: Add additional 32-bit RGB format support
  media: nxp: imx8-isi: Add 16-bit raw Bayer format support
  media: nxp: imx8-isi: Implement per-stream reference counting for multiplexed streams
  media: nxp: imx8-isi: Use BIT_ULL() for 64-bit stream masks
  media: nxp: imx8-isi: Correct color map between V4L2 and ISI
  ...

1 files changed, 159 insertions, 0 deletions

diff --git a/Documentation/driver-api/usb/callbacks.rst b/Documentation/driver-api/usb/callbacks.rst
new file mode 100644
index 000000000..927da49b8
--- /dev/null
+++ b/Documentation/driver-api/usb/callbacks.rst
@@ -0,0 +1,159 @@
+USB core callbacks
+~~~~~~~~~~~~~~~~~~
+
+What callbacks will usbcore do?
+===============================
+
+Usbcore will call into a driver through callbacks defined in the driver
+structure and through the completion handler of URBs a driver submits.
+Only the former are in the scope of this document. These two kinds of
+callbacks are completely independent of each other. Information on the
+completion callback can be found in :ref:`usb-urb`.
+
+The callbacks defined in the driver structure are:
+
+1. Hotplugging callbacks:
+
+ - @probe:
+	Called to see if the driver is willing to manage a particular
+	interface on a device.
+
+ - @disconnect:
+	Called when the interface is no longer accessible, usually
+	because its device has been (or is being) disconnected or the
+	driver module is being unloaded.
+
+2. Odd backdoor through usbfs:
+
+ - @ioctl:
+	Used for drivers that want to talk to userspace through
+	the "usbfs" filesystem.  This lets devices provide ways to
+	expose information to user space regardless of where they
+	do (or don't) show up otherwise in the filesystem.
+
+3. Power management (PM) callbacks:
+
+ - @suspend:
+	Called when the device is going to be suspended.
+
+ - @resume:
+	Called when the device is being resumed.
+
+ - @reset_resume:
+	Called when the suspended device has been reset instead
+	of being resumed.
+
+4. Device level operations:
+
+ - @pre_reset:
+	Called when the device is about to be reset.
+
+ - @post_reset:
+	Called after the device has been reset
+
+The ioctl interface (2) should be used only if you have a very good
+reason. Sysfs is preferred these days. The PM callbacks are covered
+separately in :ref:`usb-power-management`.
+
+Calling conventions
+===================
+
+All callbacks are mutually exclusive. There's no need for locking
+against other USB callbacks. All callbacks are called from a task
+context. You may sleep. However, it is important that all sleeps have a
+small fixed upper limit in time. In particular you must not call out to
+user space and await results.
+
+Hotplugging callbacks
+=====================
+
+These callbacks are intended to associate and disassociate a driver with
+an interface. A driver's bond to an interface is exclusive.
+
+The probe() callback
+--------------------
+
+::
+
+  int (*probe) (struct usb_interface *intf,
+		const struct usb_device_id *id);
+
+Accept or decline an interface. If you accept the device return 0,
+otherwise -ENODEV or -ENXIO. Other error codes should be used only if a
+genuine error occurred during initialisation which prevented a driver
+from accepting a device that would else have been accepted.
+You are strongly encouraged to use usbcore's facility,
+usb_set_intfdata(), to associate a data structure with an interface, so
+that you know which internal state and identity you associate with a
+particular interface. The device will not be suspended and you may do IO
+to the interface you are called for and endpoint 0 of the device. Device
+initialisation that doesn't take too long is a good idea here.
+
+The disconnect() callback
+-------------------------
+
+::
+
+  void (*disconnect) (struct usb_interface *intf);
+
+This callback is a signal to break any connection with an interface.
+You are not allowed any IO to a device after returning from this
+callback. You also may not do any other operation that may interfere
+with another driver bound to the interface, eg. a power management
+operation. Outstanding operations on the device must be completed or
+aborted before this callback may return.
+
+If you are called due to a physical disconnection, all your URBs will be
+killed by usbcore. Note that in this case disconnect will be called some
+time after the physical disconnection. Thus your driver must be prepared
+to deal with failing IO even prior to the callback.
+
+Device level callbacks
+======================
+
+pre_reset
+---------
+
+::
+
+  int (*pre_reset)(struct usb_interface *intf);
+
+A driver or user space is triggering a reset on the device which
+contains the interface passed as an argument. Cease IO, wait for all
+outstanding URBs to complete, and save any device state you need to
+restore.  No more URBs may be submitted until the post_reset method
+is called.
+
+If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you
+are in atomic context.
+
+post_reset
+----------
+
+::
+
+  int (*post_reset)(struct usb_interface *intf);
+
+The reset has completed.  Restore any saved device state and begin
+using the device again.
+
+If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you
+are in atomic context.
+
+Call sequences
+==============
+
+No callbacks other than probe will be invoked for an interface
+that isn't bound to your driver.
+
+Probe will never be called for an interface bound to a driver.
+Hence following a successful probe, disconnect will be called
+before there is another probe for the same interface.
+
+Once your driver is bound to an interface, disconnect can be
+called at any time except in between pre_reset and post_reset.
+pre_reset is always followed by post_reset, even if the reset
+failed or the device has been unplugged.
+
+suspend is always followed by one of: resume, reset_resume, or
+disconnect.