From 6d1724925d4da49b84161f1440912205576b7935 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab <mchehab@redhat.com>
Date: Tue, 5 Jul 2011 10:07:37 -0300
Subject: [PATCH] [media] DocBook: Add a chapter to describe media errors

There are several errors reported by V4L that aren't described.
They can occur on almost all ioctl's. Instead of adding them
into each ioctl, create a new chapter.

For V4L, the new chapter will automatically be listed on all
places, as there's a macro used everywhere there.

Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
---
 Documentation/DocBook/.gitignore               |  2 ++
 Documentation/DocBook/media/Makefile           | 42 ++++++++++++++++++++++++--
 Documentation/DocBook/media/v4l/gen-errors.xml | 17 +++++++++++
 Documentation/DocBook/media_api.tmpl           |  7 ++++-
 4 files changed, 64 insertions(+), 4 deletions(-)
 create mode 100644 Documentation/DocBook/media/v4l/gen-errors.xml

diff --git a/Documentation/DocBook/.gitignore b/Documentation/DocBook/.gitignore
index 25214a5..720f245 100644
--- a/Documentation/DocBook/.gitignore
+++ b/Documentation/DocBook/.gitignore
@@ -8,5 +8,7 @@
 *.dvi
 *.log
 *.out
+*.png
+*.gif
 media-indices.tmpl
 media-entities.tmpl
diff --git a/Documentation/DocBook/media/Makefile b/Documentation/DocBook/media/Makefile
index 8cb27f3..6628b4b 100644
--- a/Documentation/DocBook/media/Makefile
+++ b/Documentation/DocBook/media/Makefile
@@ -100,23 +100,59 @@ STRUCTS = \
 	$(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/linux/v4l2-mediabus.h)
 
 ERRORS = \
+	E2BIG \
 	EACCES \
 	EAGAIN \
 	EBADF \
+	EBADFD \
+	EBADR \
+	EBADRQC \
 	EBUSY \
+	ECHILD \
+	ECONNRESET \
+	EDEADLK \
+	EDOM \
+	EEXIST \
 	EFAULT \
-	EIO \
+	EFBIG \
+	EILSEQ \
+	EINIT \
+	EINPROGRESS \
 	EINTR \
 	EINVAL \
+	EIO \
+	EMFILE \
 	ENFILE \
+	ENOBUFS \
+	ENODATA \
+	ENODEV \
+	ENOENT \
+	ENOIOCTLCMD \
 	ENOMEM \
 	ENOSPC \
+	ENOSR \
+	ENOSYS \
+	ENOTSUP \
+	ENOTSUPP \
 	ENOTTY \
 	ENXIO \
-	EMFILE \
+	EOPNOTSUPP \
+	EOVERFLOW \
 	EPERM \
-	ERANGE \
 	EPIPE \
+	EPROTO \
+	ERANGE \
+	EREMOTE \
+	EREMOTEIO \
+	ERESTART \
+	ERESTARTSYS \
+	ESHUTDOWN \
+	ESPIPE \
+	ETIME \
+	ETIMEDOUT \
+	EUSERS \
+	EWOULDBLOCK \
+	EXDEV \
 
 ESCAPE = \
 	-e "s/&/\\&amp;/g" \
diff --git a/Documentation/DocBook/media/v4l/gen-errors.xml b/Documentation/DocBook/media/v4l/gen-errors.xml
new file mode 100644
index 0000000..1efc688
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/gen-errors.xml
@@ -0,0 +1,17 @@
+<title>Generic Error Codes</title>
+
+<table frame="none" pgwide="1" id="gen-errors">
+  <title>Generic error codes</title>
+  <tgroup cols="2">
+    &cs-str;
+    <tbody valign="top">
+      <row>
+	<entry>EBUSY</entry>
+	<entry>The ioctl can't be handled because the device is busy. This is
+	       typically return while device is streaming, and an ioctl tried to
+	       change something that would affect the stream, or would require the
+	       usage of a hardware resource that was already allocated.</entry>
+      </row>
+    </tbody>
+  </tgroup>
+</table>
diff --git a/Documentation/DocBook/media_api.tmpl b/Documentation/DocBook/media_api.tmpl
index 88f2cc6..c273e3c 100644
--- a/Documentation/DocBook/media_api.tmpl
+++ b/Documentation/DocBook/media_api.tmpl
@@ -8,7 +8,7 @@
 <!ENTITY ie                     "i.&nbsp;e.">
 <!ENTITY fd                     "File descriptor returned by <link linkend='func-open'><function>open()</function></link>.">
 <!ENTITY i2c                    "I<superscript>2</superscript>C">
-<!ENTITY return-value		"<title>Return Value</title><para>On success <returnvalue>0</returnvalue> is returned, on error <returnvalue>-1</returnvalue> and the <varname>errno</varname> variable is set appropriately:</para>">
+<!ENTITY return-value		"<title>Return Value</title><para>On success <returnvalue>0</returnvalue> is returned, on error <returnvalue>-1</returnvalue> and the <varname>errno</varname> variable is set appropriately. The generic error codes are described at the <link linkend='gen-errors'>Generic Error Codes</link> chapter.</para>">
 <!ENTITY manvol                 "<manvolnum>2</manvolnum>">
 
 <!-- Table templates: structs, structs w/union, defines. -->
@@ -110,6 +110,11 @@ Foundation. A copy of the license is included in the chapter entitled
 &sub-media-controller;
 </part>
 
+<chapter id="gen_errors">
+&sub-gen-errors;
+</chapter>
+
+
 &sub-fdl-appendix;
 
 </book>
-- 
2.7.4