[PATCH RFCv3 14/17] [media] DocBook/dvb: Use generic descriptions for the frontend API

Mauro Carvalho Chehab
2011-07-06T18:04:39Z

Move generic stuff into gen-errors.xml, and remove them from
DVB API. While here, removes two bogus error codes that aren't
supported or used on Linux: EINTERNAL and ENOSIGNAL.

Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

diff --git a/Documentation/DocBook/media/dvb/dvbproperty.xml b/Documentation/DocBook/media/dvb/dvbproperty.xml
index 33274bc..207e1a5 100644
--- a/Documentation/DocBook/media/dvb/dvbproperty.xml
+++ b/Documentation/DocBook/media/dvb/dvbproperty.xml
@@ -82,15 +82,6 @@ struct dtv_properties {
</row> </tgroup></informaltable>
&return-value-dvb;
<informaltable><tgroup cols="2"> <row>
- <entry align="char"> EINVAL </entry>
- <entry align="char"> Invalid parameter(s) received or number of parameters out of the range. </entry>
- </row><row>
- <entry align="char"> ENOMEM </entry>
- <entry align="char"> Out of memory. </entry>
- </row><row>
- <entry align="char"> EFAULT </entry>
- <entry align="char"> Failure while copying data from/to userspace. </entry>
- </row><row>
<entry align="char"> EOPNOTSUPP </entry>
<entry align="char"> Property type not supported. </entry>
</row> </tgroup></informaltable>
@@ -139,15 +130,6 @@ struct dtv_properties {
</row> </tgroup></informaltable>
&return-value-dvb;
<informaltable><tgroup cols="2"> <row>
- <entry align="char"> EINVAL </entry>
- <entry align="char"> Invalid parameter(s) received or number of parameters out of the range. </entry>
- </row><row>
- <entry align="char"> ENOMEM </entry>
- <entry align="char"> Out of memory. </entry>
- </row><row>
- <entry align="char"> EFAULT </entry>
- <entry align="char"> Failure while copying data from/to userspace. </entry>
- </row><row>
<entry align="char"> EOPNOTSUPP </entry>
<entry align="char"> Property type not supported. </entry>
</row> </tgroup></informaltable>
diff --git a/Documentation/DocBook/media/dvb/frontend.xml b/Documentation/DocBook/media/dvb/frontend.xml
index c5a5cb4..61407ea 100644
--- a/Documentation/DocBook/media/dvb/frontend.xml
+++ b/Documentation/DocBook/media/dvb/frontend.xml
@@ -575,7 +575,7 @@ typedef enum fe_hierarchy {
File descriptor returned by a previous call to open().
</entry>
</row> </tgroup></informaltable>
-&return-value-dvb;
+ RETURN VALUE
<informaltable><tgroup cols="2"> <row><entry
align="char">
EBADF
@@ -692,37 +692,8 @@ typedef enum fe_hierarchy {
The bit error rate is stored into *ber.
</entry>
</row> </tgroup></informaltable>
+
&return-value-dvb;
-<informaltable><tgroup cols="2"> <row><entry
- align="char">
- EBADF
-</entry><entry
- align="char">
- fd is not a valid open file descriptor.
-</entry>
- </row><row><entry
- align="char">
- EFAULT
-</entry><entry
- align="char">
- ber points to invalid address.
-</entry>
- </row><row><entry
- align="char">
- ENOSIGNAL
-</entry><entry
- align="char">
- There is no signal, thus no meaningful bit error rate. Also
- returned if the front-end is not turned on.
-</entry>
- </row><row><entry
- align="char">
- ENOSYS
-</entry><entry
- align="char">
- Function not available for this device.
-</entry>
- </row> </tgroup></informaltable>



@@ -770,36 +741,6 @@ typedef enum fe_hierarchy {
</row> </tgroup></informaltable>

&return-value-dvb;
-<informaltable><tgroup cols="2"> <row><entry
- align="char">
- EBADF
-</entry><entry
- align="char">
- fd is not a valid open file descriptor.
-</entry>
- </row><row><entry
- align="char">
- EFAULT
-</entry><entry
- align="char">
- snr points to invalid address.
-</entry>
- </row><row><entry
- align="char">
- ENOSIGNAL
-</entry><entry
- align="char">
- There is no signal, thus no meaningful signal strength
- value. Also returned if front-end is not turned on.
-</entry>
- </row><row><entry
- align="char">
- ENOSYS
-</entry><entry
- align="char">
- Function not available for this device.
-</entry>
- </row> </tgroup></informaltable>



@@ -846,37 +787,8 @@ typedef enum fe_hierarchy {
The signal strength value is stored into *strength.
</entry>
</row> </tgroup></informaltable>
+
&return-value-dvb;
-<informaltable><tgroup cols="2"> <row><entry
- align="char">
- EBADF
-</entry><entry
- align="char">
- fd is not a valid open file descriptor.
-</entry>
- </row><row><entry
- align="char">
- EFAULT
-</entry><entry
- align="char">
- status points to invalid address.
-</entry>
- </row><row><entry
- align="char">
- ENOSIGNAL
-</entry><entry
- align="char">
- There is no signal, thus no meaningful signal strength
- value. Also returned if front-end is not turned on.
-</entry>
- </row><row><entry
- align="char">
- ENOSYS
-</entry><entry
- align="char">
- Function not available for this device.
-</entry>
- </row> </tgroup></informaltable>



@@ -930,29 +842,8 @@ typedef enum fe_hierarchy {
so far.
</entry>
</row> </tgroup></informaltable>
+
&return-value-dvb;
-<informaltable><tgroup cols="2"> <row><entry
- align="char">
- EBADF
-</entry><entry
- align="char">
- fd is not a valid open file descriptor.
-</entry>
- </row><row><entry
- align="char">
- EFAULT
-</entry><entry
- align="char">
- ublocks points to invalid address.
-</entry>
- </row><row><entry
- align="char">
- ENOSYS
-</entry><entry
- align="char">
- Function not available for this device.
-</entry>
- </row> </tgroup></informaltable>



@@ -1005,23 +896,10 @@ typedef enum fe_hierarchy {
Points to parameters for tuning operation.
</entry>
</row> </tgroup></informaltable>
+
&return-value-dvb;
<informaltable><tgroup cols="2"> <row><entry
align="char">
- EBADF
-</entry><entry
- align="char">
- fd is not a valid open file descriptor.
-</entry>
- </row><row><entry
- align="char">
- EFAULT
-</entry><entry
- align="char">
- p points to invalid address.
-</entry>
- </row><row><entry
- align="char">
EINVAL
</entry><entry
align="char">
@@ -1078,23 +956,8 @@ typedef enum fe_hierarchy {
</row> </tgroup></informaltable>

&return-value-dvb;
-
<informaltable><tgroup cols="2"> <row><entry
align="char">
- EBADF
-</entry><entry
- align="char">
- fd is not a valid open file descriptor.
-</entry>
- </row><row><entry
- align="char">
- EFAULT
-</entry><entry
- align="char">
- p points to invalid address.
-</entry>
- </row><row><entry
- align="char">
EINVAL
</entry><entry
align="char">
@@ -1181,20 +1044,6 @@ typedef enum fe_hierarchy {
&return-value-dvb;
<informaltable><tgroup cols="2"> <row><entry
align="char">
- EBADF
-</entry><entry
- align="char">
- fd is not a valid open file descriptor.
-</entry>
- </row><row><entry
- align="char">
- EFAULT
-</entry><entry
- align="char">
- ev points to invalid address.
-</entry>
- </row><row><entry
- align="char">
EWOULDBLOCK
</entry><entry
align="char">
@@ -1206,11 +1055,6 @@ typedef enum fe_hierarchy {
EOVERFLOW
</entry><entry
align="char">
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
Overflow in event queue - one or more events were lost.
</entry>
</row> </tgroup></informaltable>
@@ -1264,21 +1108,6 @@ typedef enum fe_hierarchy {
</entry>
</row> </tgroup></informaltable>
&return-value-dvb;
-<informaltable><tgroup cols="2"> <row><entry
- align="char">
- EBADF
-</entry><entry
- align="char">
- fd is not a valid open file descriptor.
-</entry>
- </row><row><entry
- align="char">
- EFAULT
-</entry><entry
- align="char">
- info points to invalid address.
-</entry>
-</row> </tgroup></informaltable>



@@ -1322,28 +1151,6 @@ typedef enum fe_hierarchy {
</row> </tgroup></informaltable>

&return-value-dvb;
-<informaltable><tgroup cols="2"> <row><entry
- align="char">
- EBADF
-</entry><entry
- align="char">
- fd is not a valid file descriptor.
-</entry>
- </row><row><entry
- align="char">
- EPERM
-</entry><entry
- align="char">
- Permission denied (needs read/write access).
-</entry>
- </row><row><entry
- align="char">
- EINTERNAL
-</entry><entry
- align="char">
- Internal error in the device driver.
-</entry>
-</row> </tgroup></informaltable>



@@ -1394,43 +1201,6 @@ typedef enum fe_hierarchy {
</row> </tgroup></informaltable>

&return-value-dvb;
-<informaltable><tgroup cols="2"> <row><entry
- align="char">
- EBADF
-</entry><entry
- align="char">
- fd is not a valid file descriptor.
-</entry>
- </row><row><entry
- align="char">
- EFAULT
-</entry><entry
- align="char">
- Seq points to an invalid address.
-</entry>
- </row><row><entry
- align="char">
- EINVAL
-</entry><entry
- align="char">
- The data structure referred to by seq is invalid in some
- way.
-</entry>
- </row><row><entry
- align="char">
- EPERM
-</entry><entry
- align="char">
- Permission denied (needs read/write access).
-</entry>
- </row><row><entry
- align="char">
- EINTERNAL
-</entry><entry
- align="char">
- Internal error in the device driver.
-</entry>
-</row> </tgroup></informaltable>



@@ -1481,43 +1251,6 @@ typedef enum fe_hierarchy {
</entry>
</row> </tgroup></informaltable>
&return-value-dvb;
-<informaltable><tgroup cols="2"> <row><entry
- align="char">
- EBADF
-</entry><entry
- align="char">
- fd is not a valid file descriptor.
-</entry>
- </row><row><entry
- align="char">
- EFAULT
-</entry><entry
- align="char">
- Seq points to an invalid address.
-</entry>
- </row><row><entry
- align="char">
- EINVAL
-</entry><entry
- align="char">
- The data structure referred to by seq is invalid in some
- way.
-</entry>
- </row><row><entry
- align="char">
- EPERM
-</entry><entry
- align="char">
- Permission denied (needs read/write access).
-</entry>
- </row><row><entry
- align="char">
- EINTERNAL
-</entry><entry
- align="char">
- Internal error in the device driver.
-</entry>
- </row> </tgroup></informaltable>



@@ -1566,43 +1299,6 @@ typedef enum fe_hierarchy {
</row> </tgroup></informaltable>

&return-value-dvb;
-<informaltable><tgroup cols="2"> <row><entry
- align="char">
- EBADF
-</entry><entry
- align="char">
- fd is not a valid file descriptor.
-</entry>
- </row><row><entry
- align="char">
- EFAULT
-</entry><entry
- align="char">
- Seq points to an invalid address.
-</entry>
- </row><row><entry
- align="char">
- EINVAL
-</entry><entry
- align="char">
- The data structure referred to by seq is invalid in some
- way.
-</entry>
- </row><row><entry
- align="char">
- EPERM
-</entry><entry
- align="char">
- Permission denied (needs read/write access).
-</entry>
- </row><row><entry
- align="char">
- EINTERNAL
-</entry><entry
- align="char">
- Internal error in the device driver.
-</entry>
-</row> </tgroup></informaltable>



@@ -1649,42 +1345,6 @@ typedef enum fe_hierarchy {
</entry>
</row> </tgroup></informaltable>
&return-value-dvb;
-<informaltable><tgroup cols="2"> <row><entry
- align="char">
- ENODEV
-</entry><entry
- align="char">
- Device driver not loaded/available.
-</entry>
- </row><row><entry
- align="char">
- EBUSY
-</entry><entry
- align="char">
- Device or resource busy.
-</entry>
- </row><row><entry
- align="char">
- EINVAL
-</entry><entry
- align="char">
- Invalid argument.
-</entry>
- </row><row><entry
- align="char">
- EPERM
-</entry><entry
- align="char">
- File not opened with read permissions.
-</entry>
- </row><row><entry
- align="char">
- EINTERNAL
-</entry><entry
- align="char">
- Internal error in the device driver.
-</entry>
-</row> </tgroup></informaltable>



@@ -1733,42 +1393,6 @@ typedef enum fe_hierarchy {
</row> </tgroup></informaltable>

&return-value-dvb;
-<informaltable><tgroup cols="2"> <row><entry
- align="char">
- ENODEV
-</entry><entry
- align="char">
- Device driver not loaded/available.
-</entry>
- </row><row><entry
- align="char">
- EBUSY
-</entry><entry
- align="char">
- Device or resource busy.
-</entry>
- </row><row><entry
- align="char">
- EINVAL
-</entry><entry
- align="char">
- Invalid argument.
-</entry>
- </row><row><entry
- align="char">
- EPERM
-</entry><entry
- align="char">
- File not opened with read permissions.
-</entry>
- </row><row><entry
- align="char">
- EINTERNAL
-</entry><entry
- align="char">
- Internal error in the device driver.
-</entry>
- </row> </tgroup></informaltable>



@@ -1818,42 +1442,6 @@ typedef enum fe_hierarchy {
</row> </tgroup></informaltable>

&return-value-dvb;
-<informaltable><tgroup cols="2"> <row><entry
- align="char">
- ENODEV
-</entry><entry
- align="char">
- Device driver not loaded/available.
-</entry>
- </row><row><entry
- align="char">
- EBUSY
-</entry><entry
- align="char">
- Device or resource busy.
-</entry>
- </row><row><entry
- align="char">
- EINVAL
-</entry><entry
- align="char">
- Invalid argument.
-</entry>
- </row><row><entry
- align="char">
- EPERM
-</entry><entry
- align="char">
- File not opened with read permissions.
-</entry>
- </row><row><entry
- align="char">
- EINTERNAL
-</entry><entry
- align="char">
- Internal error in the device driver.
-</entry>
- </row> </tgroup></informaltable>



@@ -1886,10 +1474,6 @@ FE_TUNE_MODE_ONESHOT When set, this flag will disable any zigzagging or other "n
</row> </tgroup></informaltable>

&return-value-dvb;
-<informaltable><tgroup cols="2"> <row>
-<entry align="char"> EINVAL </entry>
-<entry align="char"> Invalid argument. </entry>
- </row> </tgroup></informaltable>



@@ -1924,11 +1508,6 @@ sends the specified raw cmd to the dish via DISEqC.
</row> </tgroup></informaltable>

&return-value-dvb;
-<informaltable><tgroup cols="1"> <row>
-<entry align="char">
- There are no errors in use for this call
-</entry>
-</row> </tgroup></informaltable>



diff --git a/Documentation/DocBook/media/v4l/gen-errors.xml b/Documentation/DocBook/media/v4l/gen-errors.xml
index 3e6ddd9..dedcc90 100644
--- a/Documentation/DocBook/media/v4l/gen-errors.xml
+++ b/Documentation/DocBook/media/v4l/gen-errors.xml
@@ -8,7 +8,7 @@

<row>
<entry>EBADF</entry>
- <entry><parameter>fd</parameter> is not a valid open file descriptor.</entry>
+ <entry>The file descriptor is not a valid.</entry>
</row>
<row>
<entry>EBUSY</entry>
@@ -21,18 +21,20 @@
</row>
<row>
<entry>EFAULT</entry>
- <entry><parameter>fd</parameter> is not a valid open file descriptor.</entry>
+ <entry>There was a failure while copying data from/to userspace.</entry>
</row>
<row>
<entry>EINVAL</entry>
- <entry>One or more of the ioctl parameters are invalid. This is a widely
- error code. see the individual ioctl requests for actual causes.</entry>
+ <entry>One or more of the ioctl parameters are invalid or out of the
+ allowed range. This is a widely error code. See the individual
+ ioctl requests for specific causes.</entry>
</row>
<row>
<entry>EINVAL or ENOTTY</entry>
<entry>The ioctl is not supported by the driver, actually meaning that
the required functionality is not available, or the file
- descriptor is not for a media device.</entry>
+ descriptor is not for a media device. The usage of EINVAL is
+ deprecated and will be fixed on a latter patch.</entry>
</row>
<row>
<entry>ENODEV</entry>
@@ -49,6 +51,17 @@
for periodic transfers (up to 80% of the USB bandwidth).</entry>
</row>
<row>
+ <entry>ENOSYS or EOPNOTSUPP</entry>
+ <entry>Function not available for this device (dvb API only. Will likely
+ be replaced anytime soon by ENOTTY).</entry>
+ </row>
+ <row>
+ <entry>EPERM</entry>
+ <entry>Permission denied. Can be returned if the device needs write
+ permission, or some special capabilities is needed
+ (e. g. root)</entry>
+ </row>
+ <row>
<entry>EWOULDBLOCK</entry>
<entry>Operation would block. Used when the ioctl would need to wait
for an event, but the device was opened in non-blocking mode.</entry>
--
1.7.1