diff options
Diffstat (limited to 'Documentation/DocBook')
| -rw-r--r-- | Documentation/DocBook/Makefile | 3 | ||||
| -rw-r--r-- | Documentation/DocBook/drm.tmpl | 12 | ||||
| -rw-r--r-- | Documentation/DocBook/filesystems.tmpl | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/media/Makefile | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/io.xml | 15 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/media-ioc-enum-links.xml | 8 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/pixfmt.xml | 4 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/subdev-formats.xml | 760 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-dqevent.xml | 33 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml | 27 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml | 30 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml | 20 | ||||
| -rw-r--r-- | Documentation/DocBook/writing_musb_glue_layer.tmpl | 873 |
13 files changed, 1759 insertions, 30 deletions
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index b444f2e8fe32..bec06659e0eb 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/drm.tmpl b/Documentation/DocBook/drm.tmpl index 677a02553ec0..ba60d93c1855 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -79,7 +79,7 @@ <partintro> <para> This first part of the DRM Developer's Guide documents core DRM code, - helper libraries for writting drivers and generic userspace interfaces + helper libraries for writing drivers and generic userspace interfaces exposed by DRM drivers. </para> </partintro> @@ -459,7 +459,7 @@ char *date;</synopsis> providing a solution to every graphics memory-related problems, GEM identified common code between drivers and created a support library to share it. GEM has simpler initialization and execution requirements than - TTM, but has no video RAM management capabitilies and is thus limited to + TTM, but has no video RAM management capabilities and is thus limited to UMA devices. </para> <sect2> @@ -889,7 +889,7 @@ int (*prime_fd_to_handle)(struct drm_device *dev, vice versa. Drivers must use the kernel dma-buf buffer sharing framework to manage the PRIME file descriptors. Similar to the mode setting API PRIME is agnostic to the underlying buffer object manager, as - long as handles are 32bit unsinged integers. + long as handles are 32bit unsigned integers. </para> <para> While non-GEM drivers must implement the operations themselves, GEM @@ -2356,7 +2356,7 @@ void intel_crt_init(struct drm_device *dev) first create properties and then create and associate individual instances of those properties to objects. A property can be instantiated multiple times and associated with different objects. Values are stored in property - instances, and all other property information are stored in the propery + instances, and all other property information are stored in the property and shared between all instances of the property. </para> <para> @@ -2697,10 +2697,10 @@ int num_ioctls;</synopsis> <sect1> <title>Legacy Support Code</title> <para> - The section very brievely covers some of the old legacy support code which + The section very briefly covers some of the old legacy support code which is only used by old DRM drivers which have done a so-called shadow-attach to the underlying device instead of registering as a real driver. This - also includes some of the old generic buffer mangement and command + also includes some of the old generic buffer management and command submission code. Do not use any of this in new and modern drivers. </para> diff --git a/Documentation/DocBook/filesystems.tmpl b/Documentation/DocBook/filesystems.tmpl index 4f676838da06..bcdfdb9a9277 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 f9fd615427fb..1d27f0a1abd1 100644 --- a/Documentation/DocBook/media/Makefile +++ b/Documentation/DocBook/media/Makefile @@ -195,7 +195,7 @@ DVB_DOCUMENTED = \ # install_media_images = \ - $(Q)cp $(OBJIMGFILES) $(MEDIA_SRC_DIR)/v4l/*.svg $(MEDIA_OBJ_DIR)/media_api + $(Q)-cp $(OBJIMGFILES) $(MEDIA_SRC_DIR)/v4l/*.svg $(MEDIA_OBJ_DIR)/media_api $(MEDIA_OBJ_DIR)/%: $(MEDIA_SRC_DIR)/%.b64 $(Q)base64 -d $< >$@ diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index 97a69bf6f3eb..a086a5db7a18 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 cf8548556c7d..74fb394ec667 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 ea514d6075c5..91dcbc84f3f8 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 7331ce116f4c..b2d5a0363cba 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 89891adb928a..820f86e8744b 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 cd7720d404ea..28a8c1e1c705 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 b3e17c1dfaf5..b9fdfeacdbcb 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 5c70b616d818..17efa870d4d2 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 000000000000..837eca77f274 --- /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> + ------------------------ + | | <------- drivers/usb/gadget + | Linux USB Core Stack | <------- drivers/usb/host + | | <------- drivers/usb/core + ------------------------ + ⬍ + -------------------------- + | | <------ drivers/usb/musb/musb_gadget.c + | MUSB Controller driver | <------ drivers/usb/musb/musb_host.c + | | <------ drivers/usb/musb/musb_core.c + -------------------------- + ⬍ + --------------------------------- + | MUSB Platform Specific Driver | + | | <-- drivers/usb/musb/jz4740.c + | aka "Glue Layer" | + --------------------------------- + ⬍ + --------------------------------- + | 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(&pdev->dev, sizeof(*glue), GFP_KERNEL); + if (!glue) + return -ENOMEM; + + musb = platform_device_alloc("musb-hdrc", PLATFORM_DEVID_AUTO); + if (!musb) { + dev_err(&pdev->dev, "failed to allocate musb device\n"); + return -ENOMEM; + } + + clk = devm_clk_get(&pdev->dev, "udc"); + if (IS_ERR(clk)) { + dev_err(&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(&pdev->dev, "failed to enable clock\n"); + goto err_platform_device_put; + } + + musb->dev.parent = &pdev->dev; + + glue->dev = &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 = &jz4740_musb_platform_data; + + pdata->platform_ops = &jz4740_musb_ops; + + platform_set_drvdata(pdev, glue); + + ret = platform_device_add_resources(musb, pdev->resource, + pdev->num_resources); + if (ret) { + dev_err(&pdev->dev, "failed to add resources\n"); + goto err_clk_disable; + } + + ret = platform_device_add_data(musb, pdata, sizeof(*pdata)); + if (ret) { + dev_err(&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(&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(&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 &= 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(&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 = &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 + "usb_phy_gen_xceiv" 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 "mc" 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 "musb-jz4740" 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 = &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(&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 &= 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(&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> |