diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 8b6e00a71034..2deb069aedf1 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -53,7 +53,10 @@ MAN := $(patsubst %.xml, %.9, $(BOOKS))
mandocs: $(MAN)
build_images = mkdir -p $(objtree)/Documentation/DocBook/media/ && \
- cp $(srctree)/Documentation/DocBook/dvb/*.png $(srctree)/Documentation/DocBook/v4l/*.gif $(objtree)/Documentation/DocBook/media/
+ cp $(srctree)/Documentation/DocBook/dvb/*.png \
+ $(srctree)/Documentation/DocBook/v4l/*.gif \
+ $(srctree)/Documentation/DocBook/v4l/*.png \
+ $(objtree)/Documentation/DocBook/media/
xmldoclinks:
ifneq ($(objtree),$(srctree))
diff --git a/Documentation/DocBook/media-entities.tmpl b/Documentation/DocBook/media-entities.tmpl
index 121db1549244..dbb9cb2e1ec6 100644
--- a/Documentation/DocBook/media-entities.tmpl
+++ b/Documentation/DocBook/media-entities.tmpl
@@ -86,6 +86,10 @@
VIDIOC_S_PRIORITY">
VIDIOC_S_STD">
VIDIOC_S_TUNER">
+VIDIOC_SUBDEV_ENUM_FRAME_SIZE">
+VIDIOC_SUBDEV_ENUM_MBUS_CODE">
+VIDIOC_SUBDEV_G_FMT">
+VIDIOC_SUBDEV_S_FMT">
VIDIOC_TRY_ENCODER_CMD">
VIDIOC_TRY_EXT_CTRLS">
VIDIOC_TRY_FMT">
@@ -107,6 +111,7 @@
v4l2_field">
v4l2_frmivaltypes">
v4l2_frmsizetypes">
+v4l2_mbus_pixelcode">
v4l2_memory">
v4l2_mpeg_audio_ac3_bitrate">
v4l2_mpeg_audio_crc">
@@ -130,6 +135,7 @@
v4l2_mpeg_video_encoding">
v4l2_power_line_frequency">
v4l2_priority">
+v4l2_subdev_format_whence">
v4l2_tuner_type">
v4l2_preemphasis">
@@ -172,6 +178,7 @@
v4l2_hw_freq_seek">
v4l2_input">
v4l2_jpegcompression">
+v4l2_mbus_framefmt">
v4l2_modulator">
v4l2_mpeg_vbi_fmt_ivtv">
v4l2_output">
@@ -186,6 +193,9 @@
v4l2_sliced_vbi_cap">
v4l2_sliced_vbi_data">
v4l2_sliced_vbi_format">
+v4l2_subdev_frame_size_enum">
+v4l2_subdev_format">
+v4l2_subdev_mbus_code_enum">
v4l2_standard">
v4l2_streamparm">
v4l2_timecode">
@@ -215,6 +225,7 @@
ENXIO error code">
EMFILE error code">
EPERM error code">
+EPIPE error code">
ERANGE error code">
@@ -234,6 +245,7 @@
+
@@ -319,6 +331,10 @@
+
+
+
+
diff --git a/Documentation/DocBook/v4l/dev-subdev.xml b/Documentation/DocBook/v4l/dev-subdev.xml
new file mode 100644
index 000000000000..fc62e65f45ef
--- /dev/null
+++ b/Documentation/DocBook/v4l/dev-subdev.xml
@@ -0,0 +1,280 @@
+ Sub-device Interface
+
+
+ Experimental
+ This is an experimental
+ interface and may change in the future.
+
+
+ The complex nature of V4L2 devices, where hardware is often made of
+ several integrated circuits that need to interact with each other in a
+ controlled way, leads to complex V4L2 drivers. The drivers usually reflect
+ the hardware model in software, and model the different hardware components
+ as software blocks called sub-devices.
+
+ V4L2 sub-devices are usually kernel-only objects. If the V4L2 driver
+ implements the media device API, they will automatically inherit from media
+ entities. Applications will be able to enumerate the sub-devices and discover
+ the hardware topology using the media entities, pads and links enumeration
+ API.
+
+ In addition to make sub-devices discoverable, drivers can also choose
+ to make them directly configurable by applications. When both the sub-device
+ driver and the V4L2 device driver support this, sub-devices will feature a
+ character device node on which ioctls can be called to
+
+ query, read and write sub-devices controls
+ subscribe and unsubscribe to events and retrieve them
+ negotiate image formats on individual pads
+
+
+
+ Sub-device character device nodes, conventionally named
+ /dev/v4l-subdev*, use major number 81.
+
+
+ Controls
+ Most V4L2 controls are implemented by sub-device hardware. Drivers
+ usually merge all controls and expose them through video device nodes.
+ Applications can control all sub-devices through a single interface.
+
+ Complex devices sometimes implement the same control in different
+ pieces of hardware. This situation is common in embedded platforms, where
+ both sensors and image processing hardware implement identical functions,
+ such as contrast adjustment, white balance or faulty pixels correction. As
+ the V4L2 controls API doesn't support several identical controls in a single
+ device, all but one of the identical controls are hidden.
+
+ Applications can access those hidden controls through the sub-device
+ node with the V4L2 control API described in . The
+ ioctls behave identically as when issued on V4L2 device nodes, with the
+ exception that they deal only with controls implemented in the sub-device.
+
+
+ Depending on the driver, those controls might also be exposed through
+ one (or several) V4L2 device nodes.
+
+
+
+ Events
+ V4L2 sub-devices can notify applications of events as described in
+ . The API behaves identically as when used on V4L2
+ device nodes, with the exception that it only deals with events generated by
+ the sub-device. Depending on the driver, those events might also be reported
+ on one (or several) V4L2 device nodes.
+
+
+
+ Pad-level Formats
+
+ Pad-level formats are only applicable to very complex device that
+ need to expose low-level format configuration to user space. Generic V4L2
+ applications do not need to use the API described in
+ this section.
+
+ For the purpose of this section, the term
+ format means the combination of media bus data
+ format, frame width and frame height.
+
+ Image formats are typically negotiated on video capture and output
+ devices using the cropping and scaling ioctls.
+ The driver is responsible for configuring every block in the video pipeline
+ according to the requested format at the pipeline input and/or
+ output.
+
+ For complex devices, such as often found in embedded systems,
+ identical image sizes at the output of a pipeline can be achieved using
+ different hardware configurations. One such exemple is shown on
+ , where
+ image scaling can be performed on both the video sensor and the host image
+ processing hardware.
+
+
+ Image Format Negotation on Pipelines
+
+
+
+
+
+
+
+
+ High quality and high speed pipeline configuration
+
+
+
+
+ The sensor scaler is usually of less quality than the host scaler, but
+ scaling on the sensor is required to achieve higher frame rates. Depending
+ on the use case (quality vs. speed), the pipeline must be configured
+ differently. Applications need to configure the formats at every point in
+ the pipeline explicitly.
+
+ Drivers that implement the media
+ API can expose pad-level image format configuration to applications.
+ When they do, applications can use the &VIDIOC-SUBDEV-G-FMT; and
+ &VIDIOC-SUBDEV-S-FMT; ioctls. to negotiate formats on a per-pad basis.
+
+ Applications are responsible for configuring coherent parameters on
+ the whole pipeline and making sure that connected pads have compatible
+ formats. The pipeline is checked for formats mismatch at &VIDIOC-STREAMON;
+ time, and an &EPIPE; is then returned if the configuration is
+ invalid.
+
+ Pad-level image format configuration support can be tested by calling
+ the &VIDIOC-SUBDEV-G-FMT; ioctl on pad 0. If the driver returns an &EINVAL;
+ pad-level format configuration is not supported by the sub-device.
+
+
+ Format Negotiation
+
+ Acceptable formats on pads can (and usually do) depend on a number
+ of external parameters, such as formats on other pads, active links, or
+ even controls. Finding a combination of formats on all pads in a video
+ pipeline, acceptable to both application and driver, can't rely on formats
+ enumeration only. A format negotiation mechanism is required.
+
+ Central to the format negotiation mechanism are the get/set format
+ operations. When called with the which argument
+ set to V4L2_SUBDEV_FORMAT_TRY, the
+ &VIDIOC-SUBDEV-G-FMT; and &VIDIOC-SUBDEV-S-FMT; ioctls operate on a set of
+ formats parameters that are not connected to the hardware configuration.
+ Modifying those 'try' formats leaves the device state untouched (this
+ applies to both the software state stored in the driver and the hardware
+ state stored in the device itself).
+
+ While not kept as part of the device state, try formats are stored
+ in the sub-device file handles. A &VIDIOC-SUBDEV-G-FMT; call will return
+ the last try format set on the same sub-device file
+ handle. Several applications querying the same sub-device at
+ the same time will thus not interact with each other.
+
+ To find out whether a particular format is supported by the device,
+ applications use the &VIDIOC-SUBDEV-S-FMT; ioctl. Drivers verify and, if
+ needed, change the requested format based on
+ device requirements and return the possibly modified value. Applications
+ can then choose to try a different format or accept the returned value and
+ continue.
+
+ Formats returned by the driver during a negotiation iteration are
+ guaranteed to be supported by the device. In particular, drivers guarantee
+ that a returned format will not be further changed if passed to an
+ &VIDIOC-SUBDEV-S-FMT; call as-is (as long as external parameters, such as
+ formats on other pads or links' configuration are not changed).
+
+ Drivers automatically propagate formats inside sub-devices. When a
+ try or active format is set on a pad, corresponding formats on other pads
+ of the same sub-device can be modified by the driver. Drivers are free to
+ modify formats as required by the device. However, they should comply with
+ the following rules when possible:
+
+ Formats should be propagated from sink pads to source pads.
+ Modifying a format on a source pad should not modify the format on any
+ sink pad.
+ Sub-devices that scale frames using variable scaling factors
+ should reset the scale factors to default values when sink pads formats
+ are modified. If the 1:1 scaling ratio is supported, this means that
+ source pads formats should be reset to the sink pads formats.
+
+
+
+ Formats are not propagated across links, as that would involve
+ propagating them from one sub-device file handle to another. Applications
+ must then take care to configure both ends of every link explicitly with
+ compatible formats. Identical formats on the two ends of a link are
+ guaranteed to be compatible. Drivers are free to accept different formats
+ matching device requirements as being compatible.
+
+
+ shows a sample configuration sequence for the pipeline described in
+ (table
+ columns list entity names and pad numbers).
+
+
+
+
+
+ Initial state. The sensor output is set to its native 3MP
+ resolution. Resolutions on the host frontend and scaler input and output
+ pads are undefined.
+ The application configures the frontend input pad resolution to
+ 2048x1536. The driver propagates the format to the frontend output pad.
+ Note that the propagated output format can be different, as in this case,
+ than the input format, as the hardware might need to crop pixels (for
+ instance when converting a Bayer filter pattern to RGB or YUV).
+ The application configures the scaler input pad resolution to
+ 2046x1534 to match the frontend output resolution. The driver propagates
+ the format to the scaler output pad.
+ The application configures the scaler output pad resolution to
+ 1280x960.
+
+
+
+ When satisfied with the try results, applications can set the active
+ formats by setting the which argument to
+ V4L2_SUBDEV_FORMAT_TRY. Active formats are changed
+ exactly as try formats by drivers. To avoid modifying the hardware state
+ during format negotiation, applications should negotiate try formats first
+ and then modify the active settings using the try formats returned during
+ the last negotiation iteration. This guarantees that the active format
+ will be applied as-is by the driver without being modified.
+
+
+
+
+
+ &sub-subdev-formats;
diff --git a/Documentation/DocBook/v4l/subdev-formats.xml b/Documentation/DocBook/v4l/subdev-formats.xml
new file mode 100644
index 000000000000..0cae57207006
--- /dev/null
+++ b/Documentation/DocBook/v4l/subdev-formats.xml
@@ -0,0 +1,2416 @@
+
+ Media Bus Formats
+
+
+ struct <structname>v4l2_mbus_framefmt</structname>
+
+ &cs-str;
+
+
+ __u32
+ width
+ Image width, in pixels.
+
+
+ __u32
+ height
+ Image height, in pixels.
+
+
+ __u32
+ code
+ Format code, from &v4l2-mbus-pixelcode;.
+
+
+ __u32
+ field
+ Field order, from &v4l2-field;. See
+ for details.
+
+
+ __u32
+ colorspace
+ Image colorspace, from &v4l2-colorspace;. See
+ for details.
+
+
+ __u32
+ reserved[7]
+ Reserved for future extensions. Applications and drivers must
+ set the array to zero.
+
+
+
+
+
+
+ Media Bus Pixel Codes
+
+ The media bus pixel codes describe image formats as flowing over
+ physical busses (both between separate physical components and inside SoC
+ devices). This should not be confused with the V4L2 pixel formats that
+ describe, using four character codes, image formats as stored in memory.
+
+
+ While there is a relationship between image formats on busses and
+ image formats in memory (a raw Bayer image won't be magically converted to
+ JPEG just by storing it to memory), there is no one-to-one correspondance
+ between them.
+
+
+ Packed RGB Formats
+
+ Those formats transfer pixel data as red, green and blue components.
+ The format code is made of the following information.
+
+ The red, green and blue components order code, as encoded in a
+ pixel sample. Possible values are RGB and BGR.
+ The number of bits per component, for each component. The values
+ can be different for all components. Common values are 555 and 565.
+
+ The number of bus samples per pixel. Pixels that are wider than
+ the bus width must be transferred in multiple samples. Common values are
+ 1 and 2.
+ The bus width.
+ For formats where the total number of bits per pixel is smaller
+ than the number of bus samples per pixel times the bus width, a padding
+ value stating if the bytes are padded in their most high order bits
+ (PADHI) or low order bits (PADLO).
+ For formats where the number of bus samples per pixel is larger
+ than 1, an endianness value stating if the pixel is transferred MSB first
+ (BE) or LSB first (LE).
+
+
+
+ For instance, a format where pixels are encoded as 5-bits red, 5-bits
+ green and 5-bit blue values padded on the high bit, transferred as 2 8-bit
+ samples per pixel with the most significant bits (padding, red and half of
+ the green value) transferred first will be named
+ V4L2_MBUS_FMT_RGB555_2X8_PADHI_BE.
+
+
+ The following tables list existing packet RGB formats.
+
+
+
+
+
+ Bayer Formats
+
+ Those formats transfer pixel data as red, green and blue components.
+ The format code is made of the following information.
+
+ The red, green and blue components order code, as encoded in a
+ pixel sample. The possible values are shown in .
+ The number of bits per pixel component. All components are
+ transferred on the same number of bits. Common values are 8, 10 and 12.
+
+ If the pixel components are DPCM-compressed, a mention of the
+ DPCM compression and the number of bits per compressed pixel component.
+
+ The number of bus samples per pixel. Pixels that are wider than
+ the bus width must be transferred in multiple samples. Common values are
+ 1 and 2.
+ The bus width.
+ For formats where the total number of bits per pixel is smaller
+ than the number of bus samples per pixel times the bus width, a padding
+ value stating if the bytes are padded in their most high order bits
+ (PADHI) or low order bits (PADLO).
+ For formats where the number of bus samples per pixel is larger
+ than 1, an endianness value stating if the pixel is transferred MSB first
+ (BE) or LSB first (LE).
+
+
+
+ For instance, a format with uncompressed 10-bit Bayer components
+ arranged in a red, green, green, blue pattern transferred as 2 8-bit
+ samples per pixel with the least significant bits transferred first will
+ be named V4L2_MBUS_FMT_SRGGB10_2X8_PADHI_LE.
+
+
+
+ Bayer Patterns
+
+
+
+
+
+
+
+
+ Bayer filter color patterns
+
+
+
+
+ The following table lists existing packet Bayer formats. The data
+ organization is given as an example for the first pixel only.
+
+
+
+
+
+ Packed YUV Formats
+
+ Those data formats transfer pixel data as (possibly downsampled) Y, U
+ and V components. The format code is made of the following information.
+
+ The Y, U and V components order code, as transferred on the
+ bus. Possible values are YUYV, UYVY, YVYU and VYUY.
+ The number of bits per pixel component. All components are
+ transferred on the same number of bits. Common values are 8, 10 and 12.
+
+ The number of bus samples per pixel. Pixels that are wider than
+ the bus width must be transferred in multiple samples. Common values are
+ 1, 1.5 (encoded as 1_5) and 2.
+ The bus width. When the bus width is larger than the number of
+ bits per pixel component, several components are packed in a single bus
+ sample. The components are ordered as specified by the order code, with
+ components on the left of the code transferred in the high order bits.
+ Common values are 8 and 16.
+
+
+
+
+ For instance, a format where pixels are encoded as 8-bit YUV values
+ downsampled to 4:2:2 and transferred as 2 8-bit bus samples per pixel in the
+ U, Y, V, Y order will be named V4L2_MBUS_FMT_UYVY8_2X8.
+
+
+ The following table lisst existing packet YUV formats.
+
+
+
+
+
diff --git a/Documentation/DocBook/v4l/v4l2.xml b/Documentation/DocBook/v4l/v4l2.xml
index 7859d7d9da39..2ada2f86bb54 100644
--- a/Documentation/DocBook/v4l/v4l2.xml
+++ b/Documentation/DocBook/v4l/v4l2.xml
@@ -439,6 +439,7 @@ and discussions on the V4L mailing list.
&sub-dev-radio; &sub-dev-rds; &sub-dev-event;
+ &sub-dev-subdev;
@@ -506,6 +507,9 @@ and discussions on the V4L mailing list.
&sub-reqbufs;
&sub-s-hw-freq-seek;
&sub-streamon;
+ &sub-subdev-enum-frame-size;
+ &sub-subdev-enum-mbus-code;
+ &sub-subdev-g-fmt;
&sub-subscribe-event;
&sub-mmap;
diff --git a/Documentation/DocBook/v4l/vidioc-streamon.xml b/Documentation/DocBook/v4l/vidioc-streamon.xml
index e42bff1f2c0a..75ed39bf4d2b 100644
--- a/Documentation/DocBook/v4l/vidioc-streamon.xml
+++ b/Documentation/DocBook/v4l/vidioc-streamon.xml
@@ -93,6 +93,15 @@ synchronize with other events.
been allocated (memory mapping) or enqueued (output) yet.
+
+ EPIPE
+
+ The driver implements pad-level format configuration and
+ the pipeline configuration is invalid.
+
+
+
diff --git a/Documentation/DocBook/v4l/vidioc-subdev-enum-frame-size.xml b/Documentation/DocBook/v4l/vidioc-subdev-enum-frame-size.xml
new file mode 100644
index 000000000000..79ce42b7c60c
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-subdev-enum-frame-size.xml
@@ -0,0 +1,154 @@
+
+
+ ioctl VIDIOC_SUBDEV_ENUM_FRAME_SIZE
+ &manvol;
+
+
+
+ VIDIOC_SUBDEV_ENUM_FRAME_SIZE
+ Enumerate media bus frame sizes
+
+
+
+
+
+ int ioctl
+ int fd
+ int request
+ struct v4l2_subdev_frame_size_enum *
+ argp
+
+
+
+
+
+ Arguments
+
+
+
+ fd
+
+ &fd;
+
+
+
+ request
+
+ VIDIOC_SUBDEV_ENUM_FRAME_SIZE
+
+
+
+ argp
+
+
+
+
+
+
+
+
+ Description
+
+
+ Experimental
+ This is an experimental
+ interface and may change in the future.
+
+
+ This ioctl allows applications to enumerate all frame sizes
+ supported by a sub-device on the given pad for the given media bus format.
+ Supported formats can be retrieved with the &VIDIOC-SUBDEV-ENUM-MBUS-CODE;
+ ioctl.
+
+ To enumerate frame sizes applications initialize the
+ pad, code and
+ index fields of the
+ &v4l2-subdev-mbus-code-enum; and call the
+ VIDIOC_SUBDEV_ENUM_FRAME_SIZE ioctl with a pointer to
+ the structure. Drivers fill the minimum and maximum frame sizes or return
+ an &EINVAL; if one of the input parameters is invalid.
+
+ Sub-devices that only support discrete frame sizes (such as most
+ sensors) will return one or more frame sizes with identical minimum and
+ maximum values.
+
+ Not all possible sizes in given [minimum, maximum] ranges need to be
+ supported. For instance, a scaler that uses a fixed-point scaling ratio
+ might not be able to produce every frame size between the minimum and
+ maximum values. Applications must use the &VIDIOC-SUBDEV-S-FMT; ioctl to
+ try the sub-device for an exact supported frame size.
+
+ Available frame sizes may depend on the current 'try' formats at other
+ pads of the sub-device, as well as on the current active links and the
+ current values of V4L2 controls. See &VIDIOC-SUBDEV-G-FMT; for more
+ information about try formats.
+
+
+ struct <structname>v4l2_subdev_frame_size_enum</structname>
+
+ &cs-str;
+
+
+ __u32
+ index
+ Number of the format in the enumeration, set by the
+ application.
+
+
+ __u32
+ pad
+ Pad number as reported by the media controller API.
+
+
+ __u32
+ code
+ The media bus format code, as defined in
+ .
+
+
+ __u32
+ min_width
+ Minimum frame width, in pixels.
+
+
+ __u32
+ max_width
+ Maximum frame width, in pixels.
+
+
+ __u32
+ min_height
+ Minimum frame height, in pixels.
+
+
+ __u32
+ max_height
+ Maximum frame height, in pixels.
+
+
+ __u32
+ reserved[9]
+ Reserved for future extensions. Applications and drivers must
+ set the array to zero.
+
+
+
+
+
+
+
+ &return-value;
+
+
+
+ EINVAL
+
+ The &v4l2-subdev-frame-size-enum; pad
+ references a non-existing pad, the code is
+ invalid for the given pad or the index
+ field is out of bounds.
+
+
+
+
+
diff --git a/Documentation/DocBook/v4l/vidioc-subdev-enum-mbus-code.xml b/Documentation/DocBook/v4l/vidioc-subdev-enum-mbus-code.xml
new file mode 100644
index 000000000000..a6b3432449f6
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-subdev-enum-mbus-code.xml
@@ -0,0 +1,119 @@
+
+
+ ioctl VIDIOC_SUBDEV_ENUM_MBUS_CODE
+ &manvol;
+
+
+
+ VIDIOC_SUBDEV_ENUM_MBUS_CODE
+ Enumerate media bus formats
+
+
+
+
+
+ int ioctl
+ int fd
+ int request
+ struct v4l2_subdev_mbus_code_enum *
+ argp
+
+
+
+
+
+ Arguments
+
+
+
+ fd
+
+ &fd;
+
+
+
+ request
+
+ VIDIOC_SUBDEV_ENUM_MBUS_CODE
+
+
+
+ argp
+
+
+
+
+
+
+
+
+ Description
+
+
+ Experimental
+ This is an experimental
+ interface and may change in the future.
+
+
+ To enumerate media bus formats available at a given sub-device pad
+ applications initialize the pad and
+ index fields of &v4l2-subdev-mbus-code-enum; and
+ call the VIDIOC_SUBDEV_ENUM_MBUS_CODE ioctl with a
+ pointer to this structure. Drivers fill the rest of the structure or return
+ an &EINVAL; if either the pad or
+ index are invalid. All media bus formats are
+ enumerable by beginning at index zero and incrementing by one until
+ EINVAL is returned.
+
+ Available media bus formats may depend on the current 'try' formats
+ at other pads of the sub-device, as well as on the current active links. See
+ &VIDIOC-SUBDEV-G-FMT; for more information about the try formats.
+
+
+ struct <structname>v4l2_subdev_mbus_code_enum</structname>
+
+ &cs-str;
+
+
+ __u32
+ pad
+ Pad number as reported by the media controller API.
+
+
+ __u32
+ index
+ Number of the format in the enumeration, set by the
+ application.
+
+
+ __u32
+ code
+ The media bus format code, as defined in
+ .
+
+
+ __u32
+ reserved[9]
+ Reserved for future extensions. Applications and drivers must
+ set the array to zero.
+
+
+
+
+
+
+
+ &return-value;
+
+
+
+ EINVAL
+
+ The &v4l2-subdev-mbus-code-enum; pad
+ references a non-existing pad, or the index
+ field is out of bounds.
+
+
+
+
+
diff --git a/Documentation/DocBook/v4l/vidioc-subdev-g-fmt.xml b/Documentation/DocBook/v4l/vidioc-subdev-g-fmt.xml
new file mode 100644
index 000000000000..f367c570c530
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-subdev-g-fmt.xml
@@ -0,0 +1,180 @@
+
+
+ ioctl VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT
+ &manvol;
+
+
+
+ VIDIOC_SUBDEV_G_FMT
+ VIDIOC_SUBDEV_S_FMT
+ Get or set the data format on a subdev pad
+
+
+
+
+
+ int ioctl
+ int fd
+ int request
+ struct v4l2_subdev_format *argp
+
+
+
+
+
+
+ Arguments
+
+
+
+ fd
+
+ &fd;
+
+
+
+ request
+
+ VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT
+
+
+
+ argp
+
+
+
+
+
+
+
+
+ Description
+
+
+ Experimental
+ This is an experimental
+ interface and may change in the future.
+
+
+ These ioctls are used to negotiate the frame format at specific
+ subdev pads in the image pipeline.
+
+ To retrieve the current format applications set the
+ pad field of a &v4l2-subdev-format; to the
+ desired pad number as reported by the media API and the
+ which field to
+ V4L2_SUBDEV_FORMAT_ACTIVE. When they call the
+ VIDIOC_SUBDEV_G_FMT ioctl with a pointer to this
+ structure the driver fills the members of the format
+ field.
+
+ To change the current format applications set both the
+ pad and which fields
+ and all members of the format field. When they
+ call the VIDIOC_SUBDEV_S_FMT ioctl with a pointer to this
+ structure the driver verifies the requested format, adjusts it based on the
+ hardware capabilities and configures the device. Upon return the
+ &v4l2-subdev-format; contains the current format as would be returned by a
+ VIDIOC_SUBDEV_G_FMT call.
+
+ Applications can query the device capabilities by setting the
+ which to
+ V4L2_SUBDEV_FORMAT_TRY. When set, 'try' formats are not
+ applied to the device by the driver, but are changed exactly as active
+ formats and stored in the sub-device file handle. Two applications querying
+ the same sub-device would thus not interact with each other.
+
+ For instance, to try a format at the output pad of a sub-device,
+ applications would first set the try format at the sub-device input with the
+ VIDIOC_SUBDEV_S_FMT ioctl. They would then either
+ retrieve the default format at the output pad with the
+ VIDIOC_SUBDEV_G_FMT ioctl, or set the desired output
+ pad format with the VIDIOC_SUBDEV_S_FMT ioctl and check
+ the returned value.
+
+ Try formats do not depend on active formats, but can depend on the
+ current links configuration or sub-device controls value. For instance, a
+ low-pass noise filter might crop pixels at the frame boundaries, modifying
+ its output frame size.
+
+ Drivers must not return an error solely because the requested format
+ doesn't match the device capabilities. They must instead modify the format
+ to match what the hardware can provide. The modified format should be as
+ close as possible to the original request.
+
+
+ struct <structname>v4l2_subdev_format</structname>
+
+ &cs-str;
+
+
+ __u32
+ pad
+ Pad number as reported by the media controller API.
+
+
+ __u32
+ which
+ Format to modified, from &v4l2-subdev-format-whence;.
+
+
+ &v4l2-mbus-framefmt;
+ format
+ Definition of an image format, see for details.
+
+
+ __u32
+ reserved[8]
+ Reserved for future extensions. Applications and drivers must
+ set the array to zero.
+
+
+
+
+
+
+ enum <structname>v4l2_subdev_format_whence</structname>
+
+ &cs-def;
+
+
+ V4L2_SUBDEV_FORMAT_TRY
+ 0
+ Try formats, used for querying device capabilities.
+
+
+ V4L2_SUBDEV_FORMAT_ACTIVE
+ 1
+ Active formats, applied to the hardware.
+
+
+
+
+
+
+
+ &return-value;
+
+
+
+ EBUSY
+
+ The format can't be changed because the pad is currently busy.
+ This can be caused, for instance, by an active video stream on the
+ pad. The ioctl must not be retried without performing another action
+ to fix the problem first. Only returned by
+ VIDIOC_SUBDEV_S_FMT
+
+
+
+ EINVAL
+
+ The &v4l2-subdev-format; pad
+ references a non-existing pad, or the which
+ field references a non-existing format.
+
+
+
+
+
diff --git a/drivers/media/video/v4l2-subdev.c b/drivers/media/video/v4l2-subdev.c
index bc763db385df..207cc5cceb29 100644
--- a/drivers/media/video/v4l2-subdev.c
+++ b/drivers/media/video/v4l2-subdev.c
@@ -149,6 +149,9 @@ static long subdev_do_ioctl(struct file *file, unsigned int cmd, void *arg)
struct video_device *vdev = video_devdata(file);
struct v4l2_subdev *sd = vdev_to_v4l2_subdev(vdev);
struct v4l2_fh *vfh = file->private_data;
+#if defined(CONFIG_VIDEO_V4L2_SUBDEV_API)
+ struct v4l2_subdev_fh *subdev_fh = to_v4l2_subdev_fh(vfh);
+#endif
switch (cmd) {
case VIDIOC_QUERYCTRL:
@@ -183,7 +186,53 @@ static long subdev_do_ioctl(struct file *file, unsigned int cmd, void *arg)
case VIDIOC_UNSUBSCRIBE_EVENT:
return v4l2_subdev_call(sd, core, unsubscribe_event, vfh, arg);
+#if defined(CONFIG_VIDEO_V4L2_SUBDEV_API)
+ case VIDIOC_SUBDEV_G_FMT: {
+ struct v4l2_subdev_format *format = arg;
+ if (format->which != V4L2_SUBDEV_FORMAT_TRY &&
+ format->which != V4L2_SUBDEV_FORMAT_ACTIVE)
+ return -EINVAL;
+
+ if (format->pad >= sd->entity.num_pads)
+ return -EINVAL;
+
+ return v4l2_subdev_call(sd, pad, get_fmt, subdev_fh, format);
+ }
+
+ case VIDIOC_SUBDEV_S_FMT: {
+ struct v4l2_subdev_format *format = arg;
+
+ if (format->which != V4L2_SUBDEV_FORMAT_TRY &&
+ format->which != V4L2_SUBDEV_FORMAT_ACTIVE)
+ return -EINVAL;
+
+ if (format->pad >= sd->entity.num_pads)
+ return -EINVAL;
+
+ return v4l2_subdev_call(sd, pad, set_fmt, subdev_fh, format);
+ }
+
+ case VIDIOC_SUBDEV_ENUM_MBUS_CODE: {
+ struct v4l2_subdev_mbus_code_enum *code = arg;
+
+ if (code->pad >= sd->entity.num_pads)
+ return -EINVAL;
+
+ return v4l2_subdev_call(sd, pad, enum_mbus_code, subdev_fh,
+ code);
+ }
+
+ case VIDIOC_SUBDEV_ENUM_FRAME_SIZE: {
+ struct v4l2_subdev_frame_size_enum *fse = arg;
+
+ if (fse->pad >= sd->entity.num_pads)
+ return -EINVAL;
+
+ return v4l2_subdev_call(sd, pad, enum_frame_size, subdev_fh,
+ fse);
+ }
+#endif
default:
return -ENOIOCTLCMD;
}
diff --git a/include/linux/Kbuild b/include/linux/Kbuild
index c33f22a6a404..43918a34db9f 100644
--- a/include/linux/Kbuild
+++ b/include/linux/Kbuild
@@ -372,6 +372,7 @@ header-y += usbdevice_fs.h
header-y += utime.h
header-y += utsname.h
header-y += v4l2-mediabus.h
+header-y += v4l2-subdev.h
header-y += veth.h
header-y += vhost.h
header-y += videodev2.h
diff --git a/include/linux/v4l2-subdev.h b/include/linux/v4l2-subdev.h
new file mode 100644
index 000000000000..8dbb44873821
--- /dev/null
+++ b/include/linux/v4l2-subdev.h
@@ -0,0 +1,90 @@
+/*
+ * V4L2 subdev userspace API
+ *
+ * Copyright (C) 2010 Nokia Corporation
+ *
+ * Contacts: Laurent Pinchart
+ * Sakari Ailus
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 as
+ * published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ */
+
+#ifndef __LINUX_V4L2_SUBDEV_H
+#define __LINUX_V4L2_SUBDEV_H
+
+#include
+#include
+#include
+
+/**
+ * enum v4l2_subdev_format_whence - Media bus format type
+ * @V4L2_SUBDEV_FORMAT_TRY: try format, for negotiation only
+ * @V4L2_SUBDEV_FORMAT_ACTIVE: active format, applied to the device
+ */
+enum v4l2_subdev_format_whence {
+ V4L2_SUBDEV_FORMAT_TRY = 0,
+ V4L2_SUBDEV_FORMAT_ACTIVE = 1,
+};
+
+/**
+ * struct v4l2_subdev_format - Pad-level media bus format
+ * @which: format type (from enum v4l2_subdev_format_whence)
+ * @pad: pad number, as reported by the media API
+ * @format: media bus format (format code and frame size)
+ */
+struct v4l2_subdev_format {
+ __u32 which;
+ __u32 pad;
+ struct v4l2_mbus_framefmt format;
+ __u32 reserved[8];
+};
+
+/**
+ * struct v4l2_subdev_mbus_code_enum - Media bus format enumeration
+ * @pad: pad number, as reported by the media API
+ * @index: format index during enumeration
+ * @code: format code (from enum v4l2_mbus_pixelcode)
+ */
+struct v4l2_subdev_mbus_code_enum {
+ __u32 pad;
+ __u32 index;
+ __u32 code;
+ __u32 reserved[9];
+};
+
+/**
+ * struct v4l2_subdev_frame_size_enum - Media bus format enumeration
+ * @pad: pad number, as reported by the media API
+ * @index: format index during enumeration
+ * @code: format code (from enum v4l2_mbus_pixelcode)
+ */
+struct v4l2_subdev_frame_size_enum {
+ __u32 index;
+ __u32 pad;
+ __u32 code;
+ __u32 min_width;
+ __u32 max_width;
+ __u32 min_height;
+ __u32 max_height;
+ __u32 reserved[9];
+};
+
+#define VIDIOC_SUBDEV_G_FMT _IOWR('V', 4, struct v4l2_subdev_format)
+#define VIDIOC_SUBDEV_S_FMT _IOWR('V', 5, struct v4l2_subdev_format)
+#define VIDIOC_SUBDEV_ENUM_MBUS_CODE \
+ _IOWR('V', 2, struct v4l2_subdev_mbus_code_enum)
+#define VIDIOC_SUBDEV_ENUM_FRAME_SIZE \
+ _IOWR('V', 74, struct v4l2_subdev_frame_size_enum)
+
+#endif
diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
index d4d3653426a9..4215650151be 100644
--- a/include/media/v4l2-subdev.h
+++ b/include/media/v4l2-subdev.h
@@ -21,6 +21,7 @@
#ifndef _V4L2_SUBDEV_H
#define _V4L2_SUBDEV_H
+#include
#include
#include
#include
@@ -414,6 +415,15 @@ struct v4l2_subdev_ir_ops {
};
struct v4l2_subdev_pad_ops {
+ int (*enum_mbus_code)(struct v4l2_subdev *sd, struct v4l2_subdev_fh *fh,
+ struct v4l2_subdev_mbus_code_enum *code);
+ int (*enum_frame_size)(struct v4l2_subdev *sd,
+ struct v4l2_subdev_fh *fh,
+ struct v4l2_subdev_frame_size_enum *fse);
+ int (*get_fmt)(struct v4l2_subdev *sd, struct v4l2_subdev_fh *fh,
+ struct v4l2_subdev_format *format);
+ int (*set_fmt)(struct v4l2_subdev *sd, struct v4l2_subdev_fh *fh,
+ struct v4l2_subdev_format *format);
};
struct v4l2_subdev_ops {