summaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/DocBook')
-rw-r--r--Documentation/DocBook/80211.tmpl1
-rw-r--r--Documentation/DocBook/Makefile3
-rw-r--r--Documentation/DocBook/filesystems.tmpl2
-rw-r--r--Documentation/DocBook/media/Makefile4
-rw-r--r--Documentation/DocBook/media/v4l/io.xml15
-rw-r--r--Documentation/DocBook/media/v4l/media-ioc-enum-links.xml8
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt.xml4
-rw-r--r--Documentation/DocBook/media/v4l/subdev-formats.xml760
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-dqevent.xml33
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml27
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml30
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml20
-rw-r--r--Documentation/DocBook/writing_musb_glue_layer.tmpl873
13 files changed, 1755 insertions, 25 deletions
diff --git a/Documentation/DocBook/80211.tmpl b/Documentation/DocBook/80211.tmpl
index 044b764..d9b9416 100644
--- a/Documentation/DocBook/80211.tmpl
+++ b/Documentation/DocBook/80211.tmpl
@@ -100,6 +100,7 @@
!Finclude/net/cfg80211.h wdev_priv
!Finclude/net/cfg80211.h ieee80211_iface_limit
!Finclude/net/cfg80211.h ieee80211_iface_combination
+!Finclude/net/cfg80211.h cfg80211_check_combinations
</chapter>
<chapter>
<title>Actions and configuration</title>
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index b444f2e..bec0665 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -14,7 +14,8 @@ DOCBOOKS := z8530book.xml device-drivers.xml \
genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \
80211.xml debugobjects.xml sh.xml regulator.xml \
alsa-driver-api.xml writing-an-alsa-driver.xml \
- tracepoint.xml drm.xml media_api.xml w1.xml
+ tracepoint.xml drm.xml media_api.xml w1.xml \
+ writing_musb_glue_layer.xml
include Documentation/DocBook/media/Makefile
diff --git a/Documentation/DocBook/filesystems.tmpl b/Documentation/DocBook/filesystems.tmpl
index 4f67683..bcdfdb9 100644
--- a/Documentation/DocBook/filesystems.tmpl
+++ b/Documentation/DocBook/filesystems.tmpl
@@ -62,7 +62,7 @@
!Efs/mpage.c
!Efs/namei.c
!Efs/buffer.c
-!Efs/bio.c
+!Eblock/bio.c
!Efs/seq_file.c
!Efs/filesystems.c
!Efs/fs-writeback.c
diff --git a/Documentation/DocBook/media/Makefile b/Documentation/DocBook/media/Makefile
index 1d27f0a..639e748 100644
--- a/Documentation/DocBook/media/Makefile
+++ b/Documentation/DocBook/media/Makefile
@@ -202,8 +202,8 @@ $(MEDIA_OBJ_DIR)/%: $(MEDIA_SRC_DIR)/%.b64
$(MEDIA_OBJ_DIR)/v4l2.xml: $(OBJIMGFILES)
@$($(quiet)gen_xml)
- @(ln -sf $(MEDIA_SRC_DIR)/v4l/*xml $(MEDIA_OBJ_DIR)/)
- @(ln -sf $(MEDIA_SRC_DIR)/dvb/*xml $(MEDIA_OBJ_DIR)/)
+ @(ln -sf `cd $(MEDIA_SRC_DIR) && /bin/pwd`/v4l/*xml $(MEDIA_OBJ_DIR)/)
+ @(ln -sf `cd $(MEDIA_SRC_DIR) && /bin/pwd`/dvb/*xml $(MEDIA_OBJ_DIR)/)
$(MEDIA_OBJ_DIR)/videodev2.h.xml: $(srctree)/include/uapi/linux/videodev2.h $(MEDIA_OBJ_DIR)/v4l2.xml
@$($(quiet)gen_xml)
diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml
index 97a69bf..a086a5d 100644
--- a/Documentation/DocBook/media/v4l/io.xml
+++ b/Documentation/DocBook/media/v4l/io.xml
@@ -125,7 +125,7 @@ location of the buffers in device memory can be determined with the
<structfield>m.offset</structfield> and <structfield>length</structfield>
returned in a &v4l2-buffer; are passed as sixth and second parameter to the
<function>mmap()</function> function. When using the multi-planar API,
-struct &v4l2-buffer; contains an array of &v4l2-plane; structures, each
+&v4l2-buffer; contains an array of &v4l2-plane; structures, each
containing its own <structfield>m.offset</structfield> and
<structfield>length</structfield>. When using the multi-planar API, every
plane of every buffer has to be mapped separately, so the number of
@@ -699,7 +699,12 @@ linkend="v4l2-buf-type" /></entry>
buffer. It depends on the negotiated data format and may change with
each buffer for compressed variable size data like JPEG images.
Drivers must set this field when <structfield>type</structfield>
-refers to an input stream, applications when it refers to an output stream.</entry>
+refers to an input stream, applications when it refers to an output stream.
+If the application sets this to 0 for an output stream, then
+<structfield>bytesused</structfield> will be set to the size of the
+buffer (see the <structfield>length</structfield> field of this struct) by
+the driver. For multiplanar formats this field is ignored and the
+<structfield>planes</structfield> pointer is used instead.</entry>
</row>
<row>
<entry>__u32</entry>
@@ -861,7 +866,11 @@ should set this to 0.</entry>
<entry></entry>
<entry>The number of bytes occupied by data in the plane
(its payload). Drivers must set this field when <structfield>type</structfield>
- refers to an input stream, applications when it refers to an output stream.</entry>
+ refers to an input stream, applications when it refers to an output stream.
+ If the application sets this to 0 for an output stream, then
+ <structfield>bytesused</structfield> will be set to the size of the
+ plane (see the <structfield>length</structfield> field of this struct)
+ by the driver.</entry>
</row>
<row>
<entry>__u32</entry>
diff --git a/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml b/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml
index cf85485..74fb394 100644
--- a/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml
+++ b/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml
@@ -79,13 +79,13 @@
<entry>Entity id, set by the application.</entry>
</row>
<row>
- <entry>struct &media-pad-desc;</entry>
+ <entry>&media-pad-desc;</entry>
<entry>*<structfield>pads</structfield></entry>
<entry>Pointer to a pads array allocated by the application. Ignored
if NULL.</entry>
</row>
<row>
- <entry>struct &media-link-desc;</entry>
+ <entry>&media-link-desc;</entry>
<entry>*<structfield>links</structfield></entry>
<entry>Pointer to a links array allocated by the application. Ignored
if NULL.</entry>
@@ -153,12 +153,12 @@
&cs-str;
<tbody valign="top">
<row>
- <entry>struct &media-pad-desc;</entry>
+ <entry>&media-pad-desc;</entry>
<entry><structfield>source</structfield></entry>
<entry>Pad at the origin of this link.</entry>
</row>
<row>
- <entry>struct &media-pad-desc;</entry>
+ <entry>&media-pad-desc;</entry>
<entry><structfield>sink</structfield></entry>
<entry>Pad at the target of this link.</entry>
</row>
diff --git a/Documentation/DocBook/media/v4l/pixfmt.xml b/Documentation/DocBook/media/v4l/pixfmt.xml
index ea514d60..91dcbc8 100644
--- a/Documentation/DocBook/media/v4l/pixfmt.xml
+++ b/Documentation/DocBook/media/v4l/pixfmt.xml
@@ -772,7 +772,7 @@ extended control <constant>V4L2_CID_MPEG_STREAM_TYPE</constant>, see
</row>
<row id="V4L2-PIX-FMT-H264-MVC">
<entry><constant>V4L2_PIX_FMT_H264_MVC</constant></entry>
- <entry>'MVC'</entry>
+ <entry>'M264'</entry>
<entry>H264 MVC video elementary stream.</entry>
</row>
<row id="V4L2-PIX-FMT-H263">
@@ -812,7 +812,7 @@ extended control <constant>V4L2_CID_MPEG_STREAM_TYPE</constant>, see
</row>
<row id="V4L2-PIX-FMT-VP8">
<entry><constant>V4L2_PIX_FMT_VP8</constant></entry>
- <entry>'VP8'</entry>
+ <entry>'VP80'</entry>
<entry>VP8 video elementary stream.</entry>
</row>
</tbody>
diff --git a/Documentation/DocBook/media/v4l/subdev-formats.xml b/Documentation/DocBook/media/v4l/subdev-formats.xml
index 7331ce1..b2d5a03 100644
--- a/Documentation/DocBook/media/v4l/subdev-formats.xml
+++ b/Documentation/DocBook/media/v4l/subdev-formats.xml
@@ -1898,6 +1898,134 @@
<entry>y<subscript>1</subscript></entry>
<entry>y<subscript>0</subscript></entry>
</row>
+ <row id="V4L2-MBUS-FMT-UYVY10-2X10">
+ <entry>V4L2_MBUS_FMT_UYVY10_2X10</entry>
+ <entry>0x2018</entry>
+ <entry></entry>
+ &dash-ent-22;
+ <entry>u<subscript>9</subscript></entry>
+ <entry>u<subscript>8</subscript></entry>
+ <entry>u<subscript>7</subscript></entry>
+ <entry>u<subscript>6</subscript></entry>
+ <entry>u<subscript>5</subscript></entry>
+ <entry>u<subscript>4</subscript></entry>
+ <entry>u<subscript>3</subscript></entry>
+ <entry>u<subscript>2</subscript></entry>
+ <entry>u<subscript>1</subscript></entry>
+ <entry>u<subscript>0</subscript></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ &dash-ent-22;
+ <entry>y<subscript>9</subscript></entry>
+ <entry>y<subscript>8</subscript></entry>
+ <entry>y<subscript>7</subscript></entry>
+ <entry>y<subscript>6</subscript></entry>
+ <entry>y<subscript>5</subscript></entry>
+ <entry>y<subscript>4</subscript></entry>
+ <entry>y<subscript>3</subscript></entry>
+ <entry>y<subscript>2</subscript></entry>
+ <entry>y<subscript>1</subscript></entry>
+ <entry>y<subscript>0</subscript></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ &dash-ent-22;
+ <entry>v<subscript>9</subscript></entry>
+ <entry>v<subscript>8</subscript></entry>
+ <entry>v<subscript>7</subscript></entry>
+ <entry>v<subscript>6</subscript></entry>
+ <entry>v<subscript>5</subscript></entry>
+ <entry>v<subscript>4</subscript></entry>
+ <entry>v<subscript>3</subscript></entry>
+ <entry>v<subscript>2</subscript></entry>
+ <entry>v<subscript>1</subscript></entry>
+ <entry>v<subscript>0</subscript></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ &dash-ent-22;
+ <entry>y<subscript>9</subscript></entry>
+ <entry>y<subscript>8</subscript></entry>
+ <entry>y<subscript>7</subscript></entry>
+ <entry>y<subscript>6</subscript></entry>
+ <entry>y<subscript>5</subscript></entry>
+ <entry>y<subscript>4</subscript></entry>
+ <entry>y<subscript>3</subscript></entry>
+ <entry>y<subscript>2</subscript></entry>
+ <entry>y<subscript>1</subscript></entry>
+ <entry>y<subscript>0</subscript></entry>
+ </row>
+ <row id="V4L2-MBUS-FMT-VYUY10-2X10">
+ <entry>V4L2_MBUS_FMT_VYUY10_2X10</entry>
+ <entry>0x2019</entry>
+ <entry></entry>
+ &dash-ent-22;
+ <entry>v<subscript>9</subscript></entry>
+ <entry>v<subscript>8</subscript></entry>
+ <entry>v<subscript>7</subscript></entry>
+ <entry>v<subscript>6</subscript></entry>
+ <entry>v<subscript>5</subscript></entry>
+ <entry>v<subscript>4</subscript></entry>
+ <entry>v<subscript>3</subscript></entry>
+ <entry>v<subscript>2</subscript></entry>
+ <entry>v<subscript>1</subscript></entry>
+ <entry>v<subscript>0</subscript></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ &dash-ent-22;
+ <entry>y<subscript>9</subscript></entry>
+ <entry>y<subscript>8</subscript></entry>
+ <entry>y<subscript>7</subscript></entry>
+ <entry>y<subscript>6</subscript></entry>
+ <entry>y<subscript>5</subscript></entry>
+ <entry>y<subscript>4</subscript></entry>
+ <entry>y<subscript>3</subscript></entry>
+ <entry>y<subscript>2</subscript></entry>
+ <entry>y<subscript>1</subscript></entry>
+ <entry>y<subscript>0</subscript></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ &dash-ent-22;
+ <entry>u<subscript>9</subscript></entry>
+ <entry>u<subscript>8</subscript></entry>
+ <entry>u<subscript>7</subscript></entry>
+ <entry>u<subscript>6</subscript></entry>
+ <entry>u<subscript>5</subscript></entry>
+ <entry>u<subscript>4</subscript></entry>
+ <entry>u<subscript>3</subscript></entry>
+ <entry>u<subscript>2</subscript></entry>
+ <entry>u<subscript>1</subscript></entry>
+ <entry>u<subscript>0</subscript></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ &dash-ent-22;
+ <entry>y<subscript>9</subscript></entry>
+ <entry>y<subscript>8</subscript></entry>
+ <entry>y<subscript>7</subscript></entry>
+ <entry>y<subscript>6</subscript></entry>
+ <entry>y<subscript>5</subscript></entry>
+ <entry>y<subscript>4</subscript></entry>
+ <entry>y<subscript>3</subscript></entry>
+ <entry>y<subscript>2</subscript></entry>
+ <entry>y<subscript>1</subscript></entry>
+ <entry>y<subscript>0</subscript></entry>
+ </row>
<row id="V4L2-MBUS-FMT-YUYV10-2X10">
<entry>V4L2_MBUS_FMT_YUYV10_2X10</entry>
<entry>0x200b</entry>
@@ -2308,6 +2436,110 @@
<entry>v<subscript>1</subscript></entry>
<entry>v<subscript>0</subscript></entry>
</row>
+ <row id="V4L2-MBUS-FMT-UYVY10-1X20">
+ <entry>V4L2_MBUS_FMT_UYVY10_1X20</entry>
+ <entry>0x201a</entry>
+ <entry></entry>
+ &dash-ent-12;
+ <entry>u<subscript>9</subscript></entry>
+ <entry>u<subscript>8</subscript></entry>
+ <entry>u<subscript>7</subscript></entry>
+ <entry>u<subscript>6</subscript></entry>
+ <entry>u<subscript>5</subscript></entry>
+ <entry>u<subscript>4</subscript></entry>
+ <entry>u<subscript>3</subscript></entry>
+ <entry>u<subscript>2</subscript></entry>
+ <entry>u<subscript>1</subscript></entry>
+ <entry>u<subscript>0</subscript></entry>
+ <entry>y<subscript>9</subscript></entry>
+ <entry>y<subscript>8</subscript></entry>
+ <entry>y<subscript>7</subscript></entry>
+ <entry>y<subscript>6</subscript></entry>
+ <entry>y<subscript>5</subscript></entry>
+ <entry>y<subscript>4</subscript></entry>
+ <entry>y<subscript>3</subscript></entry>
+ <entry>y<subscript>2</subscript></entry>
+ <entry>y<subscript>1</subscript></entry>
+ <entry>y<subscript>0</subscript></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ &dash-ent-12;
+ <entry>v<subscript>9</subscript></entry>
+ <entry>v<subscript>8</subscript></entry>
+ <entry>v<subscript>7</subscript></entry>
+ <entry>v<subscript>6</subscript></entry>
+ <entry>v<subscript>5</subscript></entry>
+ <entry>v<subscript>4</subscript></entry>
+ <entry>v<subscript>3</subscript></entry>
+ <entry>v<subscript>2</subscript></entry>
+ <entry>v<subscript>1</subscript></entry>
+ <entry>v<subscript>0</subscript></entry>
+ <entry>y<subscript>9</subscript></entry>
+ <entry>y<subscript>8</subscript></entry>
+ <entry>y<subscript>7</subscript></entry>
+ <entry>y<subscript>6</subscript></entry>
+ <entry>y<subscript>5</subscript></entry>
+ <entry>y<subscript>4</subscript></entry>
+ <entry>y<subscript>3</subscript></entry>
+ <entry>y<subscript>2</subscript></entry>
+ <entry>y<subscript>1</subscript></entry>
+ <entry>y<subscript>0</subscript></entry>
+ </row>
+ <row id="V4L2-MBUS-FMT-VYUY10-1X20">
+ <entry>V4L2_MBUS_FMT_VYUY10_1X20</entry>
+ <entry>0x201b</entry>
+ <entry></entry>
+ &dash-ent-12;
+ <entry>v<subscript>9</subscript></entry>
+ <entry>v<subscript>8</subscript></entry>
+ <entry>v<subscript>7</subscript></entry>
+ <entry>v<subscript>6</subscript></entry>
+ <entry>v<subscript>5</subscript></entry>
+ <entry>v<subscript>4</subscript></entry>
+ <entry>v<subscript>3</subscript></entry>
+ <entry>v<subscript>2</subscript></entry>
+ <entry>v<subscript>1</subscript></entry>
+ <entry>v<subscript>0</subscript></entry>
+ <entry>y<subscript>9</subscript></entry>
+ <entry>y<subscript>8</subscript></entry>
+ <entry>y<subscript>7</subscript></entry>
+ <entry>y<subscript>6</subscript></entry>
+ <entry>y<subscript>5</subscript></entry>
+ <entry>y<subscript>4</subscript></entry>
+ <entry>y<subscript>3</subscript></entry>
+ <entry>y<subscript>2</subscript></entry>
+ <entry>y<subscript>1</subscript></entry>
+ <entry>y<subscript>0</subscript></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ &dash-ent-12;
+ <entry>u<subscript>9</subscript></entry>
+ <entry>u<subscript>8</subscript></entry>
+ <entry>u<subscript>7</subscript></entry>
+ <entry>u<subscript>6</subscript></entry>
+ <entry>u<subscript>5</subscript></entry>
+ <entry>u<subscript>4</subscript></entry>
+ <entry>u<subscript>3</subscript></entry>
+ <entry>u<subscript>2</subscript></entry>
+ <entry>u<subscript>1</subscript></entry>
+ <entry>u<subscript>0</subscript></entry>
+ <entry>y<subscript>9</subscript></entry>
+ <entry>y<subscript>8</subscript></entry>
+ <entry>y<subscript>7</subscript></entry>
+ <entry>y<subscript>6</subscript></entry>
+ <entry>y<subscript>5</subscript></entry>
+ <entry>y<subscript>4</subscript></entry>
+ <entry>y<subscript>3</subscript></entry>
+ <entry>y<subscript>2</subscript></entry>
+ <entry>y<subscript>1</subscript></entry>
+ <entry>y<subscript>0</subscript></entry>
+ </row>
<row id="V4L2-MBUS-FMT-YUYV10-1X20">
<entry>V4L2_MBUS_FMT_YUYV10_1X20</entry>
<entry>0x200d</entry>
@@ -2486,6 +2718,534 @@
<entry>v<subscript>1</subscript></entry>
<entry>v<subscript>0</subscript></entry>
</row>
+ <row id="V4L2-MBUS-FMT-UYVY12-2X12">
+ <entry>V4L2_MBUS_FMT_UYVY12_2X12</entry>
+ <entry>0x201c</entry>
+ <entry></entry>
+ &dash-ent-20;
+ <entry>u<subscript>11</subscript></entry>
+ <entry>u<subscript>10</subscript></entry>
+ <entry>u<subscript>9</subscript></entry>
+ <entry>u<subscript>8</subscript></entry>
+ <entry>u<subscript>7</subscript></entry>
+ <entry>u<subscript>6</subscript></entry>
+ <entry>u<subscript>5</subscript></entry>
+ <entry>u<subscript>4</subscript></entry>
+ <entry>u<subscript>3</subscript></entry>
+ <entry>u<subscript>2</subscript></entry>
+ <entry>u<subscript>1</subscript></entry>
+ <entry>u<subscript>0</subscript></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ &dash-ent-20;
+ <entry>y<subscript>11</subscript></entry>
+ <entry>y<subscript>10</subscript></entry>
+ <entry>y<subscript>9</subscript></entry>
+ <entry>y<subscript>8</subscript></entry>
+ <entry>y<subscript>7</subscript></entry>
+ <entry>y<subscript>6</subscript></entry>
+ <entry>y<subscript>5</subscript></entry>
+ <entry>y<subscript>4</subscript></entry>
+ <entry>y<subscript>3</subscript></entry>
+ <entry>y<subscript>2</subscript></entry>
+ <entry>y<subscript>1</subscript></entry>
+ <entry>y<subscript>0</subscript></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ &dash-ent-20;
+ <entry>v<subscript>11</subscript></entry>
+ <entry>v<subscript>10</subscript></entry>
+ <entry>v<subscript>9</subscript></entry>
+ <entry>v<subscript>8</subscript></entry>
+ <entry>v<subscript>7</subscript></entry>
+ <entry>v<subscript>6</subscript></entry>
+ <entry>v<subscript>5</subscript></entry>
+ <entry>v<subscript>4</subscript></entry>
+ <entry>v<subscript>3</subscript></entry>
+ <entry>v<subscript>2</subscript></entry>
+ <entry>v<subscript>1</subscript></entry>
+ <entry>v<subscript>0</subscript></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ &dash-ent-20;
+ <entry>y<subscript>11</subscript></entry>
+ <entry>y<subscript>10</subscript></entry>
+ <entry>y<subscript>9</subscript></entry>
+ <entry>y<subscript>8</subscript></entry>
+ <entry>y<subscript>7</subscript></entry>
+ <entry>y<subscript>6</subscript></entry>
+ <entry>y<subscript>5</subscript></entry>
+ <entry>y<subscript>4</subscript></entry>
+ <entry>y<subscript>3</subscript></entry>
+ <entry>y<subscript>2</subscript></entry>
+ <entry>y<subscript>1</subscript></entry>
+ <entry>y<subscript>0</subscript></entry>
+ </row>
+ <row id="V4L2-MBUS-FMT-VYUY12-2X12">
+ <entry>V4L2_MBUS_FMT_VYUY12_2X12</entry>
+ <entry>0x201d</entry>
+ <entry></entry>
+ &dash-ent-20;
+ <entry>v<subscript>11</subscript></entry>
+ <entry>v<subscript>10</subscript></entry>
+ <entry>v<subscript>9</subscript></entry>
+ <entry>v<subscript>8</subscript></entry>
+ <entry>v<subscript>7</subscript></entry>
+ <entry>v<subscript>6</subscript></entry>
+ <entry>v<subscript>5</subscript></entry>
+ <entry>v<subscript>4</subscript></entry>
+ <entry>v<subscript>3</subscript></entry>
+ <entry>v<subscript>2</subscript></entry>
+ <entry>v<subscript>1</subscript></entry>
+ <entry>v<subscript>0</subscript></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ &dash-ent-20;
+ <entry>y<subscript>11</subscript></entry>
+ <entry>y<subscript>10</subscript></entry>
+ <entry>y<subscript>9</subscript></entry>
+ <entry>y<subscript>8</subscript></entry>
+ <entry>y<subscript>7</subscript></entry>
+ <entry>y<subscript>6</subscript></entry>
+ <entry>y<subscript>5</subscript></entry>
+ <entry>y<subscript>4</subscript></entry>
+ <entry>y<subscript>3</subscript></entry>
+ <entry>y<subscript>2</subscript></entry>
+ <entry>y<subscript>1</subscript></entry>
+ <entry>y<subscript>0</subscript></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ &dash-ent-20;
+ <entry>u<subscript>11</subscript></entry>
+ <entry>u<subscript>10</subscript></entry>
+ <entry>u<subscript>9</subscript></entry>
+ <entry>u<subscript>8</subscript></entry>
+ <entry>u<subscript>7</subscript></entry>
+ <entry>u<subscript>6</subscript></entry>
+ <entry>u<subscript>5</subscript></entry>
+ <entry>u<subscript>4</subscript></entry>
+ <entry>u<subscript>3</subscript></entry>
+ <entry>u<subscript>2</subscript></entry>
+ <entry>u<subscript>1</subscript></entry>
+ <entry>u<subscript>0</subscript></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ &dash-ent-20;
+ <entry>y<subscript>11</subscript></entry>
+ <entry>y<subscript>10</subscript></entry>
+ <entry>y<subscript>9</subscript></entry>
+ <entry>y<subscript>8</subscript></entry>
+ <entry>y<subscript>7</subscript></entry>
+ <entry>y<subscript>6</subscript></entry>
+ <entry>y<subscript>5</subscript></entry>
+ <entry>y<subscript>4</subscript></entry>
+ <entry>y<subscript>3</subscript></entry>
+ <entry>y<subscript>2</subscript></entry>
+ <entry>y<subscript>1</subscript></entry>
+ <entry>y<subscript>0</subscript></entry>
+ </row>
+ <row id="V4L2-MBUS-FMT-YUYV12-2X12">
+ <entry>V4L2_MBUS_FMT_YUYV12_2X12</entry>
+ <entry>0x201e</entry>
+ <entry></entry>
+ &dash-ent-20;
+ <entry>y<subscript>11</subscript></entry>
+ <entry>y<subscript>10</subscript></entry>
+ <entry>y<subscript>9</subscript></entry>
+ <entry>y<subscript>8</subscript></entry>
+ <entry>y<subscript>7</subscript></entry>
+ <entry>y<subscript>6</subscript></entry>
+ <entry>y<subscript>5</subscript></entry>
+ <entry>y<subscript>4</subscript></entry>
+ <entry>y<subscript>3</subscript></entry>
+ <entry>y<subscript>2</subscript></entry>
+ <entry>y<subscript>1</subscript></entry>
+ <entry>y<subscript>0</subscript></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ &dash-ent-20;
+ <entry>u<subscript>11</subscript></entry>
+ <entry>u<subscript>10</subscript></entry>
+ <entry>u<subscript>9</subscript></entry>
+ <entry>u<subscript>8</subscript></entry>
+ <entry>u<subscript>7</subscript></entry>
+ <entry>u<subscript>6</subscript></entry>
+ <entry>u<subscript>5</subscript></entry>
+ <entry>u<subscript>4</subscript></entry>
+ <entry>u<subscript>3</subscript></entry>
+ <entry>u<subscript>2</subscript></entry>
+ <entry>u<subscript>1</subscript></entry>
+ <entry>u<subscript>0</subscript></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ &dash-ent-20;
+ <entry>y<subscript>11</subscript></entry>
+ <entry>y<subscript>10</subscript></entry>
+ <entry>y<subscript>9</subscript></entry>
+ <entry>y<subscript>8</subscript></entry>
+ <entry>y<subscript>7</subscript></entry>
+ <entry>y<subscript>6</subscript></entry>
+ <entry>y<subscript>5</subscript></entry>
+ <entry>y<subscript>4</subscript></entry>
+ <entry>y<subscript>3</subscript></entry>
+ <entry>y<subscript>2</subscript></entry>
+ <entry>y<subscript>1</subscript></entry>
+ <entry>y<subscript>0</subscript></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ &dash-ent-20;
+ <entry>v<subscript>11</subscript></entry>
+ <entry>v<subscript>10</subscript></entry>
+ <entry>v<subscript>9</subscript></entry>
+ <entry>v<subscript>8</subscript></entry>
+ <entry>v<subscript>7</subscript></entry>
+ <entry>v<subscript>6</subscript></entry>
+ <entry>v<subscript>5</subscript></entry>
+ <entry>v<subscript>4</subscript></entry>
+ <entry>v<subscript>3</subscript></entry>
+ <entry>v<subscript>2</subscript></entry>
+ <entry>v<subscript>1</subscript></entry>
+ <entry>v<subscript>0</subscript></entry>
+ </row>
+ <row id="V4L2-MBUS-FMT-YVYU12-2X12">
+ <entry>V4L2_MBUS_FMT_YVYU12_2X12</entry>
+ <entry>0x201f</entry>
+ <entry></entry>
+ &dash-ent-20;
+ <entry>y<subscript>11</subscript></entry>
+ <entry>y<subscript>10</subscript></entry>
+ <entry>y<subscript>9</subscript></entry>
+ <entry>y<subscript>8</subscript></entry>
+ <entry>y<subscript>7</subscript></entry>
+ <entry>y<subscript>6</subscript></entry>
+ <entry>y<subscript>5</subscript></entry>
+ <entry>y<subscript>4</subscript></entry>
+ <entry>y<subscript>3</subscript></entry>
+ <entry>y<subscript>2</subscript></entry>
+ <entry>y<subscript>1</subscript></entry>
+ <entry>y<subscript>0</subscript></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ &dash-ent-20;
+ <entry>v<subscript>11</subscript></entry>
+ <entry>v<subscript>10</subscript></entry>
+ <entry>v<subscript>9</subscript></entry>
+ <entry>v<subscript>8</subscript></entry>
+ <entry>v<subscript>7</subscript></entry>
+ <entry>v<subscript>6</subscript></entry>
+ <entry>v<subscript>5</subscript></entry>
+ <entry>v<subscript>4</subscript></entry>
+ <entry>v<subscript>3</subscript></entry>
+ <entry>v<subscript>2</subscript></entry>
+ <entry>v<subscript>1</subscript></entry>
+ <entry>v<subscript>0</subscript></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ &dash-ent-20;
+ <entry>y<subscript>11</subscript></entry>
+ <entry>y<subscript>10</subscript></entry>
+ <entry>y<subscript>9</subscript></entry>
+ <entry>y<subscript>8</subscript></entry>
+ <entry>y<subscript>7</subscript></entry>
+ <entry>y<subscript>6</subscript></entry>
+ <entry>y<subscript>5</subscript></entry>
+ <entry>y<subscript>4</subscript></entry>
+ <entry>y<subscript>3</subscript></entry>
+ <entry>y<subscript>2</subscript></entry>
+ <entry>y<subscript>1</subscript></entry>
+ <entry>y<subscript>0</subscript></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ &dash-ent-20;
+ <entry>u<subscript>11</subscript></entry>
+ <entry>u<subscript>10</subscript></entry>
+ <entry>u<subscript>9</subscript></entry>
+ <entry>u<subscript>8</subscript></entry>
+ <entry>u<subscript>7</subscript></entry>
+ <entry>u<subscript>6</subscript></entry>
+ <entry>u<subscript>5</subscript></entry>
+ <entry>u<subscript>4</subscript></entry>
+ <entry>u<subscript>3</subscript></entry>
+ <entry>u<subscript>2</subscript></entry>
+ <entry>u<subscript>1</subscript></entry>
+ <entry>u<subscript>0</subscript></entry>
+ </row>
+ <row id="V4L2-MBUS-FMT-UYVY12-1X24">
+ <entry>V4L2_MBUS_FMT_UYVY12_1X24</entry>
+ <entry>0x2020</entry>
+ <entry></entry>
+ &dash-ent-8;
+ <entry>u<subscript>11</subscript></entry>
+ <entry>u<subscript>10</subscript></entry>
+ <entry>u<subscript>9</subscript></entry>
+ <entry>u<subscript>8</subscript></entry>
+ <entry>u<subscript>7</subscript></entry>
+ <entry>u<subscript>6</subscript></entry>
+ <entry>u<subscript>5</subscript></entry>
+ <entry>u<subscript>4</subscript></entry>
+ <entry>u<subscript>3</subscript></entry>
+ <entry>u<subscript>2</subscript></entry>
+ <entry>u<subscript>1</subscript></entry>
+ <entry>u<subscript>0</subscript></entry>
+ <entry>y<subscript>11</subscript></entry>
+ <entry>y<subscript>10</subscript></entry>
+ <entry>y<subscript>9</subscript></entry>
+ <entry>y<subscript>8</subscript></entry>
+ <entry>y<subscript>7</subscript></entry>
+ <entry>y<subscript>6</subscript></entry>
+ <entry>y<subscript>5</subscript></entry>
+ <entry>y<subscript>4</subscript></entry>
+ <entry>y<subscript>3</subscript></entry>
+ <entry>y<subscript>2</subscript></entry>
+ <entry>y<subscript>1</subscript></entry>
+ <entry>y<subscript>0</subscript></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ &dash-ent-8;
+ <entry>v<subscript>11</subscript></entry>
+ <entry>v<subscript>10</subscript></entry>
+ <entry>v<subscript>9</subscript></entry>
+ <entry>v<subscript>8</subscript></entry>
+ <entry>v<subscript>7</subscript></entry>
+ <entry>v<subscript>6</subscript></entry>
+ <entry>v<subscript>5</subscript></entry>
+ <entry>v<subscript>4</subscript></entry>
+ <entry>v<subscript>3</subscript></entry>
+ <entry>v<subscript>2</subscript></entry>
+ <entry>v<subscript>1</subscript></entry>
+ <entry>v<subscript>0</subscript></entry>
+ <entry>y<subscript>11</subscript></entry>
+ <entry>y<subscript>10</subscript></entry>
+ <entry>y<subscript>9</subscript></entry>
+ <entry>y<subscript>8</subscript></entry>
+ <entry>y<subscript>7</subscript></entry>
+ <entry>y<subscript>6</subscript></entry>
+ <entry>y<subscript>5</subscript></entry>
+ <entry>y<subscript>4</subscript></entry>
+ <entry>y<subscript>3</subscript></entry>
+ <entry>y<subscript>2</subscript></entry>
+ <entry>y<subscript>1</subscript></entry>
+ <entry>y<subscript>0</subscript></entry>
+ </row>
+ <row id="V4L2-MBUS-FMT-VYUY12-1X24">
+ <entry>V4L2_MBUS_FMT_VYUY12_1X24</entry>
+ <entry>0x2021</entry>
+ <entry></entry>
+ &dash-ent-8;
+ <entry>v<subscript>11</subscript></entry>
+ <entry>v<subscript>10</subscript></entry>
+ <entry>v<subscript>9</subscript></entry>
+ <entry>v<subscript>8</subscript></entry>
+ <entry>v<subscript>7</subscript></entry>
+ <entry>v<subscript>6</subscript></entry>
+ <entry>v<subscript>5</subscript></entry>
+ <entry>v<subscript>4</subscript></entry>
+ <entry>v<subscript>3</subscript></entry>
+ <entry>v<subscript>2</subscript></entry>
+ <entry>v<subscript>1</subscript></entry>
+ <entry>v<subscript>0</subscript></entry>
+ <entry>y<subscript>11</subscript></entry>
+ <entry>y<subscript>10</subscript></entry>
+ <entry>y<subscript>9</subscript></entry>
+ <entry>y<subscript>8</subscript></entry>
+ <entry>y<subscript>7</subscript></entry>
+ <entry>y<subscript>6</subscript></entry>
+ <entry>y<subscript>5</subscript></entry>
+ <entry>y<subscript>4</subscript></entry>
+ <entry>y<subscript>3</subscript></entry>
+ <entry>y<subscript>2</subscript></entry>
+ <entry>y<subscript>1</subscript></entry>
+ <entry>y<subscript>0</subscript></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ &dash-ent-8;
+ <entry>u<subscript>11</subscript></entry>
+ <entry>u<subscript>10</subscript></entry>
+ <entry>u<subscript>9</subscript></entry>
+ <entry>u<subscript>8</subscript></entry>
+ <entry>u<subscript>7</subscript></entry>
+ <entry>u<subscript>6</subscript></entry>
+ <entry>u<subscript>5</subscript></entry>
+ <entry>u<subscript>4</subscript></entry>
+ <entry>u<subscript>3</subscript></entry>
+ <entry>u<subscript>2</subscript></entry>
+ <entry>u<subscript>1</subscript></entry>
+ <entry>u<subscript>0</subscript></entry>
+ <entry>y<subscript>11</subscript></entry>
+ <entry>y<subscript>10</subscript></entry>
+ <entry>y<subscript>9</subscript></entry>
+ <entry>y<subscript>8</subscript></entry>
+ <entry>y<subscript>7</subscript></entry>
+ <entry>y<subscript>6</subscript></entry>
+ <entry>y<subscript>5</subscript></entry>
+ <entry>y<subscript>4</subscript></entry>
+ <entry>y<subscript>3</subscript></entry>
+ <entry>y<subscript>2</subscript></entry>
+ <entry>y<subscript>1</subscript></entry>
+ <entry>y<subscript>0</subscript></entry>
+ </row>
+ <row id="V4L2-MBUS-FMT-YUYV12-1X24">
+ <entry>V4L2_MBUS_FMT_YUYV12_1X24</entry>
+ <entry>0x2022</entry>
+ <entry></entry>
+ &dash-ent-8;
+ <entry>y<subscript>11</subscript></entry>
+ <entry>y<subscript>10</subscript></entry>
+ <entry>y<subscript>9</subscript></entry>
+ <entry>y<subscript>8</subscript></entry>
+ <entry>y<subscript>7</subscript></entry>
+ <entry>y<subscript>6</subscript></entry>
+ <entry>y<subscript>5</subscript></entry>
+ <entry>y<subscript>4</subscript></entry>
+ <entry>y<subscript>3</subscript></entry>
+ <entry>y<subscript>2</subscript></entry>
+ <entry>y<subscript>1</subscript></entry>
+ <entry>y<subscript>0</subscript></entry>
+ <entry>u<subscript>11</subscript></entry>
+ <entry>u<subscript>10</subscript></entry>
+ <entry>u<subscript>9</subscript></entry>
+ <entry>u<subscript>8</subscript></entry>
+ <entry>u<subscript>7</subscript></entry>
+ <entry>u<subscript>6</subscript></entry>
+ <entry>u<subscript>5</subscript></entry>
+ <entry>u<subscript>4</subscript></entry>
+ <entry>u<subscript>3</subscript></entry>
+ <entry>u<subscript>2</subscript></entry>
+ <entry>u<subscript>1</subscript></entry>
+ <entry>u<subscript>0</subscript></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ &dash-ent-8;
+ <entry>y<subscript>11</subscript></entry>
+ <entry>y<subscript>10</subscript></entry>
+ <entry>y<subscript>9</subscript></entry>
+ <entry>y<subscript>8</subscript></entry>
+ <entry>y<subscript>7</subscript></entry>
+ <entry>y<subscript>6</subscript></entry>
+ <entry>y<subscript>5</subscript></entry>
+ <entry>y<subscript>4</subscript></entry>
+ <entry>y<subscript>3</subscript></entry>
+ <entry>y<subscript>2</subscript></entry>
+ <entry>y<subscript>1</subscript></entry>
+ <entry>y<subscript>0</subscript></entry>
+ <entry>v<subscript>11</subscript></entry>
+ <entry>v<subscript>10</subscript></entry>
+ <entry>v<subscript>9</subscript></entry>
+ <entry>v<subscript>8</subscript></entry>
+ <entry>v<subscript>7</subscript></entry>
+ <entry>v<subscript>6</subscript></entry>
+ <entry>v<subscript>5</subscript></entry>
+ <entry>v<subscript>4</subscript></entry>
+ <entry>v<subscript>3</subscript></entry>
+ <entry>v<subscript>2</subscript></entry>
+ <entry>v<subscript>1</subscript></entry>
+ <entry>v<subscript>0</subscript></entry>
+ </row>
+ <row id="V4L2-MBUS-FMT-YVYU12-1X24">
+ <entry>V4L2_MBUS_FMT_YVYU12_1X24</entry>
+ <entry>0x2023</entry>
+ <entry></entry>
+ &dash-ent-8;
+ <entry>y<subscript>11</subscript></entry>
+ <entry>y<subscript>10</subscript></entry>
+ <entry>y<subscript>9</subscript></entry>
+ <entry>y<subscript>8</subscript></entry>
+ <entry>y<subscript>7</subscript></entry>
+ <entry>y<subscript>6</subscript></entry>
+ <entry>y<subscript>5</subscript></entry>
+ <entry>y<subscript>4</subscript></entry>
+ <entry>y<subscript>3</subscript></entry>
+ <entry>y<subscript>2</subscript></entry>
+ <entry>y<subscript>1</subscript></entry>
+ <entry>y<subscript>0</subscript></entry>
+ <entry>v<subscript>11</subscript></entry>
+ <entry>v<subscript>10</subscript></entry>
+ <entry>v<subscript>9</subscript></entry>
+ <entry>v<subscript>8</subscript></entry>
+ <entry>v<subscript>7</subscript></entry>
+ <entry>v<subscript>6</subscript></entry>
+ <entry>v<subscript>5</subscript></entry>
+ <entry>v<subscript>4</subscript></entry>
+ <entry>v<subscript>3</subscript></entry>
+ <entry>v<subscript>2</subscript></entry>
+ <entry>v<subscript>1</subscript></entry>
+ <entry>v<subscript>0</subscript></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ &dash-ent-8;
+ <entry>y<subscript>11</subscript></entry>
+ <entry>y<subscript>10</subscript></entry>
+ <entry>y<subscript>9</subscript></entry>
+ <entry>y<subscript>8</subscript></entry>
+ <entry>y<subscript>7</subscript></entry>
+ <entry>y<subscript>6</subscript></entry>
+ <entry>y<subscript>5</subscript></entry>
+ <entry>y<subscript>4</subscript></entry>
+ <entry>y<subscript>3</subscript></entry>
+ <entry>y<subscript>2</subscript></entry>
+ <entry>y<subscript>1</subscript></entry>
+ <entry>y<subscript>0</subscript></entry>
+ <entry>u<subscript>11</subscript></entry>
+ <entry>u<subscript>10</subscript></entry>
+ <entry>u<subscript>9</subscript></entry>
+ <entry>u<subscript>8</subscript></entry>
+ <entry>u<subscript>7</subscript></entry>
+ <entry>u<subscript>6</subscript></entry>
+ <entry>u<subscript>5</subscript></entry>
+ <entry>u<subscript>4</subscript></entry>
+ <entry>u<subscript>3</subscript></entry>
+ <entry>u<subscript>2</subscript></entry>
+ <entry>u<subscript>1</subscript></entry>
+ <entry>u<subscript>0</subscript></entry>
+ </row>
</tbody>
</tgroup>
</table>
diff --git a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
index 89891ad..820f86e 100644
--- a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
@@ -242,6 +242,22 @@
</tgroup>
</table>
+ <table frame="none" pgwide="1" id="v4l2-event-src-change">
+ <title>struct <structname>v4l2_event_src_change</structname></title>
+ <tgroup cols="3">
+ &cs-str;
+ <tbody valign="top">
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>changes</structfield></entry>
+ <entry>
+ A bitmask that tells what has changed. See <xref linkend="src-changes-flags" />.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
<table pgwide="1" frame="none" id="changes-flags">
<title>Changes</title>
<tgroup cols="3">
@@ -270,6 +286,23 @@
</tbody>
</tgroup>
</table>
+
+ <table pgwide="1" frame="none" id="src-changes-flags">
+ <title>Source Changes</title>
+ <tgroup cols="3">
+ &cs-def;
+ <tbody valign="top">
+ <row>
+ <entry><constant>V4L2_EVENT_SRC_CH_RESOLUTION</constant></entry>
+ <entry>0x0001</entry>
+ <entry>This event gets triggered when a resolution change is
+ detected at an input. This can come from an input connector or
+ from a video decoder.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
</refsect1>
<refsect1>
&return-value;
diff --git a/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml b/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml
index cd7720d..28a8c1e 100644
--- a/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml
@@ -1,11 +1,12 @@
<refentry id="vidioc-dv-timings-cap">
<refmeta>
- <refentrytitle>ioctl VIDIOC_DV_TIMINGS_CAP</refentrytitle>
+ <refentrytitle>ioctl VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_DV_TIMINGS_CAP</refname>
+ <refname>VIDIOC_SUBDEV_DV_TIMINGS_CAP</refname>
<refpurpose>The capabilities of the Digital Video receiver/transmitter</refpurpose>
</refnamediv>
@@ -33,7 +34,7 @@
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
- <para>VIDIOC_DV_TIMINGS_CAP</para>
+ <para>VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -54,10 +55,19 @@
interface and may change in the future.</para>
</note>
- <para>To query the capabilities of the DV receiver/transmitter applications can call
-this ioctl and the driver will fill in the structure. Note that drivers may return
+ <para>To query the capabilities of the DV receiver/transmitter applications
+can call the <constant>VIDIOC_DV_TIMINGS_CAP</constant> ioctl on a video node
+and the driver will fill in the structure. Note that drivers may return
different values after switching the video input or output.</para>
+ <para>When implemented by the driver DV capabilities of subdevices can be
+queried by calling the <constant>VIDIOC_SUBDEV_DV_TIMINGS_CAP</constant> ioctl
+directly on a subdevice node. The capabilities are specific to inputs (for DV
+receivers) or outputs (for DV transmitters), applications must specify the
+desired pad number in the &v4l2-dv-timings-cap; <structfield>pad</structfield>
+field. Attempts to query capabilities on a pad that doesn't support them will
+return an &EINVAL;.</para>
+
<table pgwide="1" frame="none" id="v4l2-bt-timings-cap">
<title>struct <structname>v4l2_bt_timings_cap</structname></title>
<tgroup cols="3">
@@ -127,7 +137,14 @@ different values after switching the video input or output.</para>
</row>
<row>
<entry>__u32</entry>
- <entry><structfield>reserved</structfield>[3]</entry>
+ <entry><structfield>pad</structfield></entry>
+ <entry>Pad number as reported by the media controller API. This field
+ is only used when operating on a subdevice node. When operating on a
+ video node applications must set this field to zero.</entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>reserved</structfield>[2]</entry>
<entry>Reserved for future extensions. Drivers must set the array to zero.</entry>
</row>
<row>
diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml
index b3e17c1..b9fdfea 100644
--- a/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml
@@ -1,11 +1,12 @@
<refentry id="vidioc-enum-dv-timings">
<refmeta>
- <refentrytitle>ioctl VIDIOC_ENUM_DV_TIMINGS</refentrytitle>
+ <refentrytitle>ioctl VIDIOC_ENUM_DV_TIMINGS, VIDIOC_SUBDEV_ENUM_DV_TIMINGS</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_ENUM_DV_TIMINGS</refname>
+ <refname>VIDIOC_SUBDEV_ENUM_DV_TIMINGS</refname>
<refpurpose>Enumerate supported Digital Video timings</refpurpose>
</refnamediv>
@@ -33,7 +34,7 @@
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
- <para>VIDIOC_ENUM_DV_TIMINGS</para>
+ <para>VIDIOC_ENUM_DV_TIMINGS, VIDIOC_SUBDEV_ENUM_DV_TIMINGS</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -61,14 +62,21 @@ standards or even custom timings that are not in this list.</para>
<para>To query the available timings, applications initialize the
<structfield>index</structfield> field and zero the reserved array of &v4l2-enum-dv-timings;
-and call the <constant>VIDIOC_ENUM_DV_TIMINGS</constant> ioctl with a pointer to this
-structure. Drivers fill the rest of the structure or return an
+and call the <constant>VIDIOC_ENUM_DV_TIMINGS</constant> ioctl on a video node with a
+pointer to this structure. Drivers fill the rest of the structure or return an
&EINVAL; when the index is out of bounds. To enumerate all supported DV timings,
applications shall begin at index zero, incrementing by one until the
driver returns <errorcode>EINVAL</errorcode>. Note that drivers may enumerate a
different set of DV timings after switching the video input or
output.</para>
+ <para>When implemented by the driver DV timings of subdevices can be queried
+by calling the <constant>VIDIOC_SUBDEV_ENUM_DV_TIMINGS</constant> ioctl directly
+on a subdevice node. The DV timings are specific to inputs (for DV receivers) or
+outputs (for DV transmitters), applications must specify the desired pad number
+in the &v4l2-enum-dv-timings; <structfield>pad</structfield> field. Attempts to
+enumerate timings on a pad that doesn't support them will return an &EINVAL;.</para>
+
<table pgwide="1" frame="none" id="v4l2-enum-dv-timings">
<title>struct <structname>v4l2_enum_dv_timings</structname></title>
<tgroup cols="3">
@@ -82,8 +90,16 @@ application.</entry>
</row>
<row>
<entry>__u32</entry>
- <entry><structfield>reserved</structfield>[3]</entry>
- <entry>Reserved for future extensions. Drivers must set the array to zero.</entry>
+ <entry><structfield>pad</structfield></entry>
+ <entry>Pad number as reported by the media controller API. This field
+ is only used when operating on a subdevice node. When operating on a
+ video node applications must set this field to zero.</entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>reserved</structfield>[2]</entry>
+ <entry>Reserved for future extensions. Drivers and applications must
+ set the array to zero.</entry>
</row>
<row>
<entry>&v4l2-dv-timings;</entry>
@@ -103,7 +119,7 @@ application.</entry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The &v4l2-enum-dv-timings; <structfield>index</structfield>
-is out of bounds.</para>
+is out of bounds or the <structfield>pad</structfield> number is invalid.</para>
</listitem>
</varlistentry>
<varlistentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
index 5c70b61..17efa87 100644
--- a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
@@ -155,6 +155,26 @@
</entry>
</row>
<row>
+ <entry><constant>V4L2_EVENT_SOURCE_CHANGE</constant></entry>
+ <entry>5</entry>
+ <entry>
+ <para>This event is triggered when a source parameter change is
+ detected during runtime by the video device. It can be a
+ runtime resolution change triggered by a video decoder or the
+ format change happening on an input connector.
+ This event requires that the <structfield>id</structfield>
+ matches the input index (when used with a video device node)
+ or the pad index (when used with a subdevice node) from which
+ you want to receive events.</para>
+
+ <para>This event has a &v4l2-event-src-change; associated
+ with it. The <structfield>changes</structfield> bitfield denotes
+ what has changed for the subscribed pad. If multiple events
+ occurred before application could dequeue them, then the changes
+ will have the ORed value of all the events generated.</para>
+ </entry>
+ </row>
+ <row>
<entry><constant>V4L2_EVENT_PRIVATE_START</constant></entry>
<entry>0x08000000</entry>
<entry>Base event number for driver-private events.</entry>
diff --git a/Documentation/DocBook/writing_musb_glue_layer.tmpl b/Documentation/DocBook/writing_musb_glue_layer.tmpl
new file mode 100644
index 0000000..837eca7
--- /dev/null
+++ b/Documentation/DocBook/writing_musb_glue_layer.tmpl
@@ -0,0 +1,873 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
+
+<book id="Writing-MUSB-Glue-Layer">
+ <bookinfo>
+ <title>Writing an MUSB Glue Layer</title>
+
+ <authorgroup>
+ <author>
+ <firstname>Apelete</firstname>
+ <surname>Seketeli</surname>
+ <affiliation>
+ <address>
+ <email>apelete at seketeli.net</email>
+ </address>
+ </affiliation>
+ </author>
+ </authorgroup>
+
+ <copyright>
+ <year>2014</year>
+ <holder>Apelete Seketeli</holder>
+ </copyright>
+
+ <legalnotice>
+ <para>
+ This documentation is free software; you can redistribute it
+ and/or modify it under the terms of the GNU General Public
+ License as published by the Free Software Foundation; either
+ version 2 of the License, or (at your option) any later version.
+ </para>
+
+ <para>
+ This documentation 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.
+ </para>
+
+ <para>
+ You should have received a copy of the GNU General Public License
+ along with this documentation; if not, write to the Free Software
+ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+ 02111-1307 USA
+ </para>
+
+ <para>
+ For more details see the file COPYING in the Linux kernel source
+ tree.
+ </para>
+ </legalnotice>
+ </bookinfo>
+
+<toc></toc>
+
+ <chapter id="introduction">
+ <title>Introduction</title>
+ <para>
+ The Linux MUSB subsystem is part of the larger Linux USB
+ subsystem. It provides support for embedded USB Device Controllers
+ (UDC) that do not use Universal Host Controller Interface (UHCI)
+ or Open Host Controller Interface (OHCI).
+ </para>
+ <para>
+ Instead, these embedded UDC rely on the USB On-the-Go (OTG)
+ specification which they implement at least partially. The silicon
+ reference design used in most cases is the Multipoint USB
+ Highspeed Dual-Role Controller (MUSB HDRC) found in the Mentor
+ Graphics Inventra™ design.
+ </para>
+ <para>
+ As a self-taught exercise I have written an MUSB glue layer for
+ the Ingenic JZ4740 SoC, modelled after the many MUSB glue layers
+ in the kernel source tree. This layer can be found at
+ drivers/usb/musb/jz4740.c. In this documentation I will walk
+ through the basics of the jz4740.c glue layer, explaining the
+ different pieces and what needs to be done in order to write your
+ own device glue layer.
+ </para>
+ </chapter>
+
+ <chapter id="linux-musb-basics">
+ <title>Linux MUSB Basics</title>
+ <para>
+ To get started on the topic, please read USB On-the-Go Basics (see
+ Resources) which provides an introduction of USB OTG operation at
+ the hardware level. A couple of wiki pages by Texas Instruments
+ and Analog Devices also provide an overview of the Linux kernel
+ MUSB configuration, albeit focused on some specific devices
+ provided by these companies. Finally, getting acquainted with the
+ USB specification at USB home page may come in handy, with
+ practical instance provided through the Writing USB Device Drivers
+ documentation (again, see Resources).
+ </para>
+ <para>
+ Linux USB stack is a layered architecture in which the MUSB
+ controller hardware sits at the lowest. The MUSB controller driver
+ abstract the MUSB controller hardware to the Linux USB stack.
+ </para>
+ <programlisting>
+ ------------------------
+ | | &lt;------- drivers/usb/gadget
+ | Linux USB Core Stack | &lt;------- drivers/usb/host
+ | | &lt;------- drivers/usb/core
+ ------------------------
+ ⬍
+ --------------------------
+ | | &lt;------ drivers/usb/musb/musb_gadget.c
+ | MUSB Controller driver | &lt;------ drivers/usb/musb/musb_host.c
+ | | &lt;------ drivers/usb/musb/musb_core.c
+ --------------------------
+ ⬍
+ ---------------------------------
+ | MUSB Platform Specific Driver |
+ | | &lt;-- drivers/usb/musb/jz4740.c
+ | aka &quot;Glue Layer&quot; |
+ ---------------------------------
+ ⬍
+ ---------------------------------
+ | MUSB Controller Hardware |
+ ---------------------------------
+ </programlisting>
+ <para>
+ As outlined above, the glue layer is actually the platform
+ specific code sitting in between the controller driver and the
+ controller hardware.
+ </para>
+ <para>
+ Just like a Linux USB driver needs to register itself with the
+ Linux USB subsystem, the MUSB glue layer needs first to register
+ itself with the MUSB controller driver. This will allow the
+ controller driver to know about which device the glue layer
+ supports and which functions to call when a supported device is
+ detected or released; remember we are talking about an embedded
+ controller chip here, so no insertion or removal at run-time.
+ </para>
+ <para>
+ All of this information is passed to the MUSB controller driver
+ through a platform_driver structure defined in the glue layer as:
+ </para>
+ <programlisting linenumbering="numbered">
+static struct platform_driver jz4740_driver = {
+ .probe = jz4740_probe,
+ .remove = jz4740_remove,
+ .driver = {
+ .name = "musb-jz4740",
+ },
+};
+ </programlisting>
+ <para>
+ The probe and remove function pointers are called when a matching
+ device is detected and, respectively, released. The name string
+ describes the device supported by this glue layer. In the current
+ case it matches a platform_device structure declared in
+ arch/mips/jz4740/platform.c. Note that we are not using device
+ tree bindings here.
+ </para>
+ <para>
+ In order to register itself to the controller driver, the glue
+ layer goes through a few steps, basically allocating the
+ controller hardware resources and initialising a couple of
+ circuits. To do so, it needs to keep track of the information used
+ throughout these steps. This is done by defining a private
+ jz4740_glue structure:
+ </para>
+ <programlisting linenumbering="numbered">
+struct jz4740_glue {
+ struct device *dev;
+ struct platform_device *musb;
+ struct clk *clk;
+};
+ </programlisting>
+ <para>
+ The dev and musb members are both device structure variables. The
+ first one holds generic information about the device, since it's
+ the basic device structure, and the latter holds information more
+ closely related to the subsystem the device is registered to. The
+ clk variable keeps information related to the device clock
+ operation.
+ </para>
+ <para>
+ Let's go through the steps of the probe function that leads the
+ glue layer to register itself to the controller driver.
+ </para>
+ <para>
+ N.B.: For the sake of readability each function will be split in
+ logical parts, each part being shown as if it was independent from
+ the others.
+ </para>
+ <programlisting linenumbering="numbered">
+static int jz4740_probe(struct platform_device *pdev)
+{
+ struct platform_device *musb;
+ struct jz4740_glue *glue;
+ struct clk *clk;
+ int ret;
+
+ glue = devm_kzalloc(&amp;pdev->dev, sizeof(*glue), GFP_KERNEL);
+ if (!glue)
+ return -ENOMEM;
+
+ musb = platform_device_alloc("musb-hdrc", PLATFORM_DEVID_AUTO);
+ if (!musb) {
+ dev_err(&amp;pdev->dev, "failed to allocate musb device\n");
+ return -ENOMEM;
+ }
+
+ clk = devm_clk_get(&amp;pdev->dev, "udc");
+ if (IS_ERR(clk)) {
+ dev_err(&amp;pdev->dev, "failed to get clock\n");
+ ret = PTR_ERR(clk);
+ goto err_platform_device_put;
+ }
+
+ ret = clk_prepare_enable(clk);
+ if (ret) {
+ dev_err(&amp;pdev->dev, "failed to enable clock\n");
+ goto err_platform_device_put;
+ }
+
+ musb->dev.parent = &amp;pdev->dev;
+
+ glue->dev = &amp;pdev->dev;
+ glue->musb = musb;
+ glue->clk = clk;
+
+ return 0;
+
+err_platform_device_put:
+ platform_device_put(musb);
+ return ret;
+}
+ </programlisting>
+ <para>
+ The first few lines of the probe function allocate and assign the
+ glue, musb and clk variables. The GFP_KERNEL flag (line 8) allows
+ the allocation process to sleep and wait for memory, thus being
+ usable in a blocking situation. The PLATFORM_DEVID_AUTO flag (line
+ 12) allows automatic allocation and management of device IDs in
+ order to avoid device namespace collisions with explicit IDs. With
+ devm_clk_get() (line 18) the glue layer allocates the clock -- the
+ <literal>devm_</literal> prefix indicates that clk_get() is
+ managed: it automatically frees the allocated clock resource data
+ when the device is released -- and enable it.
+ </para>
+ <para>
+ Then comes the registration steps:
+ </para>
+ <programlisting linenumbering="numbered">
+static int jz4740_probe(struct platform_device *pdev)
+{
+ struct musb_hdrc_platform_data *pdata = &amp;jz4740_musb_platform_data;
+
+ pdata->platform_ops = &amp;jz4740_musb_ops;
+
+ platform_set_drvdata(pdev, glue);
+
+ ret = platform_device_add_resources(musb, pdev->resource,
+ pdev->num_resources);
+ if (ret) {
+ dev_err(&amp;pdev->dev, "failed to add resources\n");
+ goto err_clk_disable;
+ }
+
+ ret = platform_device_add_data(musb, pdata, sizeof(*pdata));
+ if (ret) {
+ dev_err(&amp;pdev->dev, "failed to add platform_data\n");
+ goto err_clk_disable;
+ }
+
+ return 0;
+
+err_clk_disable:
+ clk_disable_unprepare(clk);
+err_platform_device_put:
+ platform_device_put(musb);
+ return ret;
+}
+ </programlisting>
+ <para>
+ The first step is to pass the device data privately held by the
+ glue layer on to the controller driver through
+ platform_set_drvdata() (line 7). Next is passing on the device
+ resources information, also privately held at that point, through
+ platform_device_add_resources() (line 9).
+ </para>
+ <para>
+ Finally comes passing on the platform specific data to the
+ controller driver (line 16). Platform data will be discussed in
+ <link linkend="device-platform-data">Chapter 4</link>, but here
+ we are looking at the platform_ops function pointer (line 5) in
+ musb_hdrc_platform_data structure (line 3). This function
+ pointer allows the MUSB controller driver to know which function
+ to call for device operation:
+ </para>
+ <programlisting linenumbering="numbered">
+static const struct musb_platform_ops jz4740_musb_ops = {
+ .init = jz4740_musb_init,
+ .exit = jz4740_musb_exit,
+};
+ </programlisting>
+ <para>
+ Here we have the minimal case where only init and exit functions
+ are called by the controller driver when needed. Fact is the
+ JZ4740 MUSB controller is a basic controller, lacking some
+ features found in other controllers, otherwise we may also have
+ pointers to a few other functions like a power management function
+ or a function to switch between OTG and non-OTG modes, for
+ instance.
+ </para>
+ <para>
+ At that point of the registration process, the controller driver
+ actually calls the init function:
+ </para>
+ <programlisting linenumbering="numbered">
+static int jz4740_musb_init(struct musb *musb)
+{
+ musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2);
+ if (!musb->xceiv) {
+ pr_err("HS UDC: no transceiver configured\n");
+ return -ENODEV;
+ }
+
+ /* Silicon does not implement ConfigData register.
+ * Set dyn_fifo to avoid reading EP config from hardware.
+ */
+ musb->dyn_fifo = true;
+
+ musb->isr = jz4740_musb_interrupt;
+
+ return 0;
+}
+ </programlisting>
+ <para>
+ The goal of jz4740_musb_init() is to get hold of the transceiver
+ driver data of the MUSB controller hardware and pass it on to the
+ MUSB controller driver, as usual. The transceiver is the circuitry
+ inside the controller hardware responsible for sending/receiving
+ the USB data. Since it is an implementation of the physical layer
+ of the OSI model, the transceiver is also referred to as PHY.
+ </para>
+ <para>
+ Getting hold of the MUSB PHY driver data is done with
+ usb_get_phy() which returns a pointer to the structure
+ containing the driver instance data. The next couple of
+ instructions (line 12 and 14) are used as a quirk and to setup
+ IRQ handling respectively. Quirks and IRQ handling will be
+ discussed later in <link linkend="device-quirks">Chapter
+ 5</link> and <link linkend="handling-irqs">Chapter 3</link>.
+ </para>
+ <programlisting linenumbering="numbered">
+static int jz4740_musb_exit(struct musb *musb)
+{
+ usb_put_phy(musb->xceiv);
+
+ return 0;
+}
+ </programlisting>
+ <para>
+ Acting as the counterpart of init, the exit function releases the
+ MUSB PHY driver when the controller hardware itself is about to be
+ released.
+ </para>
+ <para>
+ Again, note that init and exit are fairly simple in this case due
+ to the basic set of features of the JZ4740 controller hardware.
+ When writing an musb glue layer for a more complex controller
+ hardware, you might need to take care of more processing in those
+ two functions.
+ </para>
+ <para>
+ Returning from the init function, the MUSB controller driver jumps
+ back into the probe function:
+ </para>
+ <programlisting linenumbering="numbered">
+static int jz4740_probe(struct platform_device *pdev)
+{
+ ret = platform_device_add(musb);
+ if (ret) {
+ dev_err(&amp;pdev->dev, "failed to register musb device\n");
+ goto err_clk_disable;
+ }
+
+ return 0;
+
+err_clk_disable:
+ clk_disable_unprepare(clk);
+err_platform_device_put:
+ platform_device_put(musb);
+ return ret;
+}
+ </programlisting>
+ <para>
+ This is the last part of the device registration process where the
+ glue layer adds the controller hardware device to Linux kernel
+ device hierarchy: at this stage, all known information about the
+ device is passed on to the Linux USB core stack.
+ </para>
+ <programlisting linenumbering="numbered">
+static int jz4740_remove(struct platform_device *pdev)
+{
+ struct jz4740_glue *glue = platform_get_drvdata(pdev);
+
+ platform_device_unregister(glue->musb);
+ clk_disable_unprepare(glue->clk);
+
+ return 0;
+}
+ </programlisting>
+ <para>
+ Acting as the counterpart of probe, the remove function unregister
+ the MUSB controller hardware (line 5) and disable the clock (line
+ 6), allowing it to be gated.
+ </para>
+ </chapter>
+
+ <chapter id="handling-irqs">
+ <title>Handling IRQs</title>
+ <para>
+ Additionally to the MUSB controller hardware basic setup and
+ registration, the glue layer is also responsible for handling the
+ IRQs:
+ </para>
+ <programlisting linenumbering="numbered">
+static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci)
+{
+ unsigned long flags;
+ irqreturn_t retval = IRQ_NONE;
+ struct musb *musb = __hci;
+
+ spin_lock_irqsave(&amp;musb->lock, flags);
+
+ musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB);
+ musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX);
+ musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX);
+
+ /*
+ * The controller is gadget only, the state of the host mode IRQ bits is
+ * undefined. Mask them to make sure that the musb driver core will
+ * never see them set
+ */
+ musb->int_usb &amp;= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME |
+ MUSB_INTR_RESET | MUSB_INTR_SOF;
+
+ if (musb->int_usb || musb->int_tx || musb->int_rx)
+ retval = musb_interrupt(musb);
+
+ spin_unlock_irqrestore(&amp;musb->lock, flags);
+
+ return retval;
+}
+ </programlisting>
+ <para>
+ Here the glue layer mostly has to read the relevant hardware
+ registers and pass their values on to the controller driver which
+ will handle the actual event that triggered the IRQ.
+ </para>
+ <para>
+ The interrupt handler critical section is protected by the
+ spin_lock_irqsave() and counterpart spin_unlock_irqrestore()
+ functions (line 7 and 24 respectively), which prevent the
+ interrupt handler code to be run by two different threads at the
+ same time.
+ </para>
+ <para>
+ Then the relevant interrupt registers are read (line 9 to 11):
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ MUSB_INTRUSB: indicates which USB interrupts are currently
+ active,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ MUSB_INTRTX: indicates which of the interrupts for TX
+ endpoints are currently active,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ MUSB_INTRRX: indicates which of the interrupts for TX
+ endpoints are currently active.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Note that musb_readb() is used to read 8-bit registers at most,
+ while musb_readw() allows us to read at most 16-bit registers.
+ There are other functions that can be used depending on the size
+ of your device registers. See musb_io.h for more information.
+ </para>
+ <para>
+ Instruction on line 18 is another quirk specific to the JZ4740
+ USB device controller, which will be discussed later in <link
+ linkend="device-quirks">Chapter 5</link>.
+ </para>
+ <para>
+ The glue layer still needs to register the IRQ handler though.
+ Remember the instruction on line 14 of the init function:
+ </para>
+ <programlisting linenumbering="numbered">
+static int jz4740_musb_init(struct musb *musb)
+{
+ musb->isr = jz4740_musb_interrupt;
+
+ return 0;
+}
+ </programlisting>
+ <para>
+ This instruction sets a pointer to the glue layer IRQ handler
+ function, in order for the controller hardware to call the handler
+ back when an IRQ comes from the controller hardware. The interrupt
+ handler is now implemented and registered.
+ </para>
+ </chapter>
+
+ <chapter id="device-platform-data">
+ <title>Device Platform Data</title>
+ <para>
+ In order to write an MUSB glue layer, you need to have some data
+ describing the hardware capabilities of your controller hardware,
+ which is called the platform data.
+ </para>
+ <para>
+ Platform data is specific to your hardware, though it may cover a
+ broad range of devices, and is generally found somewhere in the
+ arch/ directory, depending on your device architecture.
+ </para>
+ <para>
+ For instance, platform data for the JZ4740 SoC is found in
+ arch/mips/jz4740/platform.c. In the platform.c file each device of
+ the JZ4740 SoC is described through a set of structures.
+ </para>
+ <para>
+ Here is the part of arch/mips/jz4740/platform.c that covers the
+ USB Device Controller (UDC):
+ </para>
+ <programlisting linenumbering="numbered">
+/* USB Device Controller */
+struct platform_device jz4740_udc_xceiv_device = {
+ .name = "usb_phy_gen_xceiv",
+ .id = 0,
+};
+
+static struct resource jz4740_udc_resources[] = {
+ [0] = {
+ .start = JZ4740_UDC_BASE_ADDR,
+ .end = JZ4740_UDC_BASE_ADDR + 0x10000 - 1,
+ .flags = IORESOURCE_MEM,
+ },
+ [1] = {
+ .start = JZ4740_IRQ_UDC,
+ .end = JZ4740_IRQ_UDC,
+ .flags = IORESOURCE_IRQ,
+ .name = "mc",
+ },
+};
+
+struct platform_device jz4740_udc_device = {
+ .name = "musb-jz4740",
+ .id = -1,
+ .dev = {
+ .dma_mask = &amp;jz4740_udc_device.dev.coherent_dma_mask,
+ .coherent_dma_mask = DMA_BIT_MASK(32),
+ },
+ .num_resources = ARRAY_SIZE(jz4740_udc_resources),
+ .resource = jz4740_udc_resources,
+};
+ </programlisting>
+ <para>
+ The jz4740_udc_xceiv_device platform device structure (line 2)
+ describes the UDC transceiver with a name and id number.
+ </para>
+ <para>
+ At the time of this writing, note that
+ &quot;usb_phy_gen_xceiv&quot; is the specific name to be used for
+ all transceivers that are either built-in with reference USB IP or
+ autonomous and doesn't require any PHY programming. You will need
+ to set CONFIG_NOP_USB_XCEIV=y in the kernel configuration to make
+ use of the corresponding transceiver driver. The id field could be
+ set to -1 (equivalent to PLATFORM_DEVID_NONE), -2 (equivalent to
+ PLATFORM_DEVID_AUTO) or start with 0 for the first device of this
+ kind if we want a specific id number.
+ </para>
+ <para>
+ The jz4740_udc_resources resource structure (line 7) defines the
+ UDC registers base addresses.
+ </para>
+ <para>
+ The first array (line 9 to 11) defines the UDC registers base
+ memory addresses: start points to the first register memory
+ address, end points to the last register memory address and the
+ flags member defines the type of resource we are dealing with. So
+ IORESOURCE_MEM is used to define the registers memory addresses.
+ The second array (line 14 to 17) defines the UDC IRQ registers
+ addresses. Since there is only one IRQ register available for the
+ JZ4740 UDC, start and end point at the same address. The
+ IORESOURCE_IRQ flag tells that we are dealing with IRQ resources,
+ and the name &quot;mc&quot; is in fact hard-coded in the MUSB core
+ in order for the controller driver to retrieve this IRQ resource
+ by querying it by its name.
+ </para>
+ <para>
+ Finally, the jz4740_udc_device platform device structure (line 21)
+ describes the UDC itself.
+ </para>
+ <para>
+ The &quot;musb-jz4740&quot; name (line 22) defines the MUSB
+ driver that is used for this device; remember this is in fact
+ the name that we used in the jz4740_driver platform driver
+ structure in <link linkend="linux-musb-basics">Chapter
+ 2</link>. The id field (line 23) is set to -1 (equivalent to
+ PLATFORM_DEVID_NONE) since we do not need an id for the device:
+ the MUSB controller driver was already set to allocate an
+ automatic id in <link linkend="linux-musb-basics">Chapter
+ 2</link>. In the dev field we care for DMA related information
+ here. The dma_mask field (line 25) defines the width of the DMA
+ mask that is going to be used, and coherent_dma_mask (line 26)
+ has the same purpose but for the alloc_coherent DMA mappings: in
+ both cases we are using a 32 bits mask. Then the resource field
+ (line 29) is simply a pointer to the resource structure defined
+ before, while the num_resources field (line 28) keeps track of
+ the number of arrays defined in the resource structure (in this
+ case there were two resource arrays defined before).
+ </para>
+ <para>
+ With this quick overview of the UDC platform data at the arch/
+ level now done, let's get back to the MUSB glue layer specific
+ platform data in drivers/usb/musb/jz4740.c:
+ </para>
+ <programlisting linenumbering="numbered">
+static struct musb_hdrc_config jz4740_musb_config = {
+ /* Silicon does not implement USB OTG. */
+ .multipoint = 0,
+ /* Max EPs scanned, driver will decide which EP can be used. */
+ .num_eps = 4,
+ /* RAMbits needed to configure EPs from table */
+ .ram_bits = 9,
+ .fifo_cfg = jz4740_musb_fifo_cfg,
+ .fifo_cfg_size = ARRAY_SIZE(jz4740_musb_fifo_cfg),
+};
+
+static struct musb_hdrc_platform_data jz4740_musb_platform_data = {
+ .mode = MUSB_PERIPHERAL,
+ .config = &amp;jz4740_musb_config,
+};
+ </programlisting>
+ <para>
+ First the glue layer configures some aspects of the controller
+ driver operation related to the controller hardware specifics.
+ This is done through the jz4740_musb_config musb_hdrc_config
+ structure.
+ </para>
+ <para>
+ Defining the OTG capability of the controller hardware, the
+ multipoint member (line 3) is set to 0 (equivalent to false)
+ since the JZ4740 UDC is not OTG compatible. Then num_eps (line
+ 5) defines the number of USB endpoints of the controller
+ hardware, including endpoint 0: here we have 3 endpoints +
+ endpoint 0. Next is ram_bits (line 7) which is the width of the
+ RAM address bus for the MUSB controller hardware. This
+ information is needed when the controller driver cannot
+ automatically configure endpoints by reading the relevant
+ controller hardware registers. This issue will be discussed when
+ we get to device quirks in <link linkend="device-quirks">Chapter
+ 5</link>. Last two fields (line 8 and 9) are also about device
+ quirks: fifo_cfg points to the USB endpoints configuration table
+ and fifo_cfg_size keeps track of the size of the number of
+ entries in that configuration table. More on that later in <link
+ linkend="device-quirks">Chapter 5</link>.
+ </para>
+ <para>
+ Then this configuration is embedded inside
+ jz4740_musb_platform_data musb_hdrc_platform_data structure (line
+ 11): config is a pointer to the configuration structure itself,
+ and mode tells the controller driver if the controller hardware
+ may be used as MUSB_HOST only, MUSB_PERIPHERAL only or MUSB_OTG
+ which is a dual mode.
+ </para>
+ <para>
+ Remember that jz4740_musb_platform_data is then used to convey
+ platform data information as we have seen in the probe function
+ in <link linkend="linux-musb-basics">Chapter 2</link>
+ </para>
+ </chapter>
+
+ <chapter id="device-quirks">
+ <title>Device Quirks</title>
+ <para>
+ Completing the platform data specific to your device, you may also
+ need to write some code in the glue layer to work around some
+ device specific limitations. These quirks may be due to some
+ hardware bugs, or simply be the result of an incomplete
+ implementation of the USB On-the-Go specification.
+ </para>
+ <para>
+ The JZ4740 UDC exhibits such quirks, some of which we will discuss
+ here for the sake of insight even though these might not be found
+ in the controller hardware you are working on.
+ </para>
+ <para>
+ Let's get back to the init function first:
+ </para>
+ <programlisting linenumbering="numbered">
+static int jz4740_musb_init(struct musb *musb)
+{
+ musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2);
+ if (!musb->xceiv) {
+ pr_err("HS UDC: no transceiver configured\n");
+ return -ENODEV;
+ }
+
+ /* Silicon does not implement ConfigData register.
+ * Set dyn_fifo to avoid reading EP config from hardware.
+ */
+ musb->dyn_fifo = true;
+
+ musb->isr = jz4740_musb_interrupt;
+
+ return 0;
+}
+ </programlisting>
+ <para>
+ Instruction on line 12 helps the MUSB controller driver to work
+ around the fact that the controller hardware is missing registers
+ that are used for USB endpoints configuration.
+ </para>
+ <para>
+ Without these registers, the controller driver is unable to read
+ the endpoints configuration from the hardware, so we use line 12
+ instruction to bypass reading the configuration from silicon, and
+ rely on a hard-coded table that describes the endpoints
+ configuration instead:
+ </para>
+ <programlisting linenumbering="numbered">
+static struct musb_fifo_cfg jz4740_musb_fifo_cfg[] = {
+{ .hw_ep_num = 1, .style = FIFO_TX, .maxpacket = 512, },
+{ .hw_ep_num = 1, .style = FIFO_RX, .maxpacket = 512, },
+{ .hw_ep_num = 2, .style = FIFO_TX, .maxpacket = 64, },
+};
+ </programlisting>
+ <para>
+ Looking at the configuration table above, we see that each
+ endpoints is described by three fields: hw_ep_num is the endpoint
+ number, style is its direction (either FIFO_TX for the controller
+ driver to send packets in the controller hardware, or FIFO_RX to
+ receive packets from hardware), and maxpacket defines the maximum
+ size of each data packet that can be transmitted over that
+ endpoint. Reading from the table, the controller driver knows that
+ endpoint 1 can be used to send and receive USB data packets of 512
+ bytes at once (this is in fact a bulk in/out endpoint), and
+ endpoint 2 can be used to send data packets of 64 bytes at once
+ (this is in fact an interrupt endpoint).
+ </para>
+ <para>
+ Note that there is no information about endpoint 0 here: that one
+ is implemented by default in every silicon design, with a
+ predefined configuration according to the USB specification. For
+ more examples of endpoint configuration tables, see musb_core.c.
+ </para>
+ <para>
+ Let's now get back to the interrupt handler function:
+ </para>
+ <programlisting linenumbering="numbered">
+static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci)
+{
+ unsigned long flags;
+ irqreturn_t retval = IRQ_NONE;
+ struct musb *musb = __hci;
+
+ spin_lock_irqsave(&amp;musb->lock, flags);
+
+ musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB);
+ musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX);
+ musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX);
+
+ /*
+ * The controller is gadget only, the state of the host mode IRQ bits is
+ * undefined. Mask them to make sure that the musb driver core will
+ * never see them set
+ */
+ musb->int_usb &amp;= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME |
+ MUSB_INTR_RESET | MUSB_INTR_SOF;
+
+ if (musb->int_usb || musb->int_tx || musb->int_rx)
+ retval = musb_interrupt(musb);
+
+ spin_unlock_irqrestore(&amp;musb->lock, flags);
+
+ return retval;
+}
+ </programlisting>
+ <para>
+ Instruction on line 18 above is a way for the controller driver to
+ work around the fact that some interrupt bits used for USB host
+ mode operation are missing in the MUSB_INTRUSB register, thus left
+ in an undefined hardware state, since this MUSB controller
+ hardware is used in peripheral mode only. As a consequence, the
+ glue layer masks these missing bits out to avoid parasite
+ interrupts by doing a logical AND operation between the value read
+ from MUSB_INTRUSB and the bits that are actually implemented in
+ the register.
+ </para>
+ <para>
+ These are only a couple of the quirks found in the JZ4740 USB
+ device controller. Some others were directly addressed in the MUSB
+ core since the fixes were generic enough to provide a better
+ handling of the issues for others controller hardware eventually.
+ </para>
+ </chapter>
+
+ <chapter id="conclusion">
+ <title>Conclusion</title>
+ <para>
+ Writing a Linux MUSB glue layer should be a more accessible task,
+ as this documentation tries to show the ins and outs of this
+ exercise.
+ </para>
+ <para>
+ The JZ4740 USB device controller being fairly simple, I hope its
+ glue layer serves as a good example for the curious mind. Used
+ with the current MUSB glue layers, this documentation should
+ provide enough guidance to get started; should anything gets out
+ of hand, the linux-usb mailing list archive is another helpful
+ resource to browse through.
+ </para>
+ </chapter>
+
+ <chapter id="acknowledgements">
+ <title>Acknowledgements</title>
+ <para>
+ Many thanks to Lars-Peter Clausen and Maarten ter Huurne for
+ answering my questions while I was writing the JZ4740 glue layer
+ and for helping me out getting the code in good shape.
+ </para>
+ <para>
+ I would also like to thank the Qi-Hardware community at large for
+ its cheerful guidance and support.
+ </para>
+ </chapter>
+
+ <chapter id="resources">
+ <title>Resources</title>
+ <para>
+ USB Home Page:
+ <ulink url="http://www.usb.org">http://www.usb.org</ulink>
+ </para>
+ <para>
+ linux-usb Mailing List Archives:
+ <ulink url="http://marc.info/?l=linux-usb">http://marc.info/?l=linux-usb</ulink>
+ </para>
+ <para>
+ USB On-the-Go Basics:
+ <ulink url="http://www.maximintegrated.com/app-notes/index.mvp/id/1822">http://www.maximintegrated.com/app-notes/index.mvp/id/1822</ulink>
+ </para>
+ <para>
+ Writing USB Device Drivers:
+ <ulink url="https://www.kernel.org/doc/htmldocs/writing_usb_driver/index.html">https://www.kernel.org/doc/htmldocs/writing_usb_driver/index.html</ulink>
+ </para>
+ <para>
+ Texas Instruments USB Configuration Wiki Page:
+ <ulink url="http://processors.wiki.ti.com/index.php/Usbgeneralpage">http://processors.wiki.ti.com/index.php/Usbgeneralpage</ulink>
+ </para>
+ <para>
+ Analog Devices Blackfin MUSB Configuration:
+ <ulink url="http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:musb">http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:musb</ulink>
+ </para>
+ </chapter>
+
+</book>
OpenPOWER on IntegriCloud