FE_READ_SNR and FE_READ_SIGNAL_STRENGTH docs

FE_READ_SNR and FE_READ_SIGNAL_STRENGTH docs

[Georgi Chorbadzhiyski]

Hi guys, I'm confused the documentation on:

http://linuxtv.org/downloads/v4l-dvb-apis/frontend_fcalls.html#FE_READ_SNR
http://linuxtv.org/downloads/v4l-dvb-apis/frontend_fcalls.html#FE_READ_SIGNAL_STRENGTH

states that these ioctls return int16_t values but frontend.h states:

https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/dvb/frontend.h

#define FE_READ_SIGNAL_STRENGTH  _IOR('o', 71, __u16)
#define FE_READ_SNR              _IOR('o', 72, __u16)

So which one is true?

-- 
Georgi Chorbadzhiyski | http://georgi.unixsol.org/ | http://github.com/gfto/

Re: FE_READ_SNR and FE_READ_SIGNAL_STRENGTH docs

[Mauro Carvalho Chehab]

Em Tue, 14 Jan 2014 17:16:10 +0200
Georgi Chorbadzhiyski <gf@unixsol.org> escreveu:

> Hi guys, I'm confused the documentation on:
> 
> http://linuxtv.org/downloads/v4l-dvb-apis/frontend_fcalls.html#FE_READ_SNR
> http://linuxtv.org/downloads/v4l-dvb-apis/frontend_fcalls.html#FE_READ_SIGNAL_STRENGTH
> 
> states that these ioctls return int16_t values but frontend.h states:
> 
> https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/dvb/frontend.h
> 
> #define FE_READ_SIGNAL_STRENGTH  _IOR('o', 71, __u16)
> #define FE_READ_SNR              _IOR('o', 72, __u16)
> 
> So which one is true?

Documentation is wrong. The returned values are unsigned. Would you mind send
us a patch fixing it?

Btw, the better is to use the new statistics API, when it is
available:
	http://linuxtv.org/downloads/v4l-dvb-apis/FE_GET_SET_PROPERTY.html#frontend-stat-properties

As it properly specifies the scale of each value.

If you're working in userspace, the libdvbv5 has functions that use
the new API automatically when the DVBv5 statistics are available on
a DVB driver, via  dvb_fe_retrieve_stats():

	http://git.linuxtv.org/v4l-utils.git/blob/HEAD:/lib/include/dvb-fe.h

-- 

Cheers,
Mauro

Re: FE_READ_SNR and FE_READ_SIGNAL_STRENGTH docs

[Georgi Chorbadzhiyski]

Around 01/14/2014 05:30 PM, Mauro Carvalho Chehab scribbled:
> Em Tue, 14 Jan 2014 17:16:10 +0200
> Georgi Chorbadzhiyski <gf@unixsol.org> escreveu:
> 
>> Hi guys, I'm confused the documentation on:
>>
>> http://linuxtv.org/downloads/v4l-dvb-apis/frontend_fcalls.html#FE_READ_SNR
>> http://linuxtv.org/downloads/v4l-dvb-apis/frontend_fcalls.html#FE_READ_SIGNAL_STRENGTH
>>
>> states that these ioctls return int16_t values but frontend.h states:
>>
>> https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/dvb/frontend.h
>>
>> #define FE_READ_SIGNAL_STRENGTH  _IOR('o', 71, __u16)
>> #define FE_READ_SNR              _IOR('o', 72, __u16)
>>
>> So which one is true?
> 
> Documentation is wrong. The returned values are unsigned. Would you mind send
> us a patch fixing it?

I would be happy to, but I can't find the repo that holds the documentation.

> Btw, the better is to use the new statistics API, when it is
> available:
> 	http://linuxtv.org/downloads/v4l-dvb-apis/FE_GET_SET_PROPERTY.html#frontend-stat-properties
> 
> As it properly specifies the scale of each value.

When it's ready, I'll add support for the API in dvblast.

-- 
Georgi Chorbadzhiyski | http://georgi.unixsol.org/ | http://github.com/gfto/

Re: FE_READ_SNR and FE_READ_SIGNAL_STRENGTH docs

[Mauro Carvalho Chehab]

Em Tue, 14 Jan 2014 17:55:19 +0200
Georgi Chorbadzhiyski <gf@unixsol.org> escreveu:

> Around 01/14/2014 05:30 PM, Mauro Carvalho Chehab scribbled:
> > Em Tue, 14 Jan 2014 17:16:10 +0200
> > Georgi Chorbadzhiyski <gf@unixsol.org> escreveu:
> > 
> >> Hi guys, I'm confused the documentation on:
> >>
> >> http://linuxtv.org/downloads/v4l-dvb-apis/frontend_fcalls.html#FE_READ_SNR
> >> http://linuxtv.org/downloads/v4l-dvb-apis/frontend_fcalls.html#FE_READ_SIGNAL_STRENGTH
> >>
> >> states that these ioctls return int16_t values but frontend.h states:
> >>
> >> https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/dvb/frontend.h
> >>
> >> #define FE_READ_SIGNAL_STRENGTH  _IOR('o', 71, __u16)
> >> #define FE_READ_SNR              _IOR('o', 72, __u16)
> >>
> >> So which one is true?
> > 
> > Documentation is wrong. The returned values are unsigned. Would you mind send
> > us a patch fixing it?
> 
> I would be happy to, but I can't find the repo that holds the documentation.

It is in the Kernel tree, under Documentation/DocBook/media/dvb.

> 
> > Btw, the better is to use the new statistics API, when it is
> > available:
> > 	http://linuxtv.org/downloads/v4l-dvb-apis/FE_GET_SET_PROPERTY.html#frontend-stat-properties
> > 
> > As it properly specifies the scale of each value.
> 
> When it's ready, I'll add support for the API in dvblast.

Good.

-- 

Cheers,
Mauro

Re: FE_READ_SNR and FE_READ_SIGNAL_STRENGTH docs

[Georgi Chorbadzhiyski]

[-- Attachment #1: Type: text/plain, Size: 1293 bytes --]

Around 01/14/2014 06:07 PM, Mauro Carvalho Chehab scribbled:
> Em Tue, 14 Jan 2014 17:55:19 +0200
> Georgi Chorbadzhiyski <gf@unixsol.org> escreveu:
>> Around 01/14/2014 05:30 PM, Mauro Carvalho Chehab scribbled:
>>> Em Tue, 14 Jan 2014 17:16:10 +0200
>>> Georgi Chorbadzhiyski <gf@unixsol.org> escreveu:
>>>
>>>> Hi guys, I'm confused the documentation on:
>>>>
>>>> http://linuxtv.org/downloads/v4l-dvb-apis/frontend_fcalls.html#FE_READ_SNR
>>>> http://linuxtv.org/downloads/v4l-dvb-apis/frontend_fcalls.html#FE_READ_SIGNAL_STRENGTH
>>>>
>>>> states that these ioctls return int16_t values but frontend.h states:
>>>>
>>>> https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/dvb/frontend.h
>>>>
>>>> #define FE_READ_SIGNAL_STRENGTH  _IOR('o', 71, __u16)
>>>> #define FE_READ_SNR              _IOR('o', 72, __u16)
>>>>
>>>> So which one is true?
>>>
>>> Documentation is wrong. The returned values are unsigned. Would you mind send
>>> us a patch fixing it?
>>
>> I would be happy to, but I can't find the repo that holds the documentation.
> 
> It is in the Kernel tree, under Documentation/DocBook/media/dvb.

The attached file contains the discussed documentation fixes.

-- 
Georgi Chorbadzhiyski | http://georgi.unixsol.org/ | http://github.com/gfto/

[-- Attachment #2: 0001-doc-Fix-FE_READ_SNR-and-FE_READ_SIGNAL_STRENGTH-para.patch --]
[-- Type: text/plain, Size: 2015 bytes --]

>From 2a633a125e616e8a9e701c34f088d7a4cc020ff8 Mon Sep 17 00:00:00 2001
From: Georgi Chorbadzhiyski <gf@unixsol.org>
Date: Thu, 16 Jan 2014 17:04:55 +0200
Subject: [PATCH] doc: Fix FE_READ_SNR and FE_READ_SIGNAL_STRENGTH parameter
 types.

The proper types returned from FE_READ_SNR and FE_READ_SIGNAL_STRENGTH
are uint16_t not int16_t.
---
 Documentation/DocBook/media/dvb/frontend.xml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/DocBook/media/dvb/frontend.xml b/Documentation/DocBook/media/dvb/frontend.xml
index 0d6e81b..8a6a6ff 100644
--- a/Documentation/DocBook/media/dvb/frontend.xml
+++ b/Documentation/DocBook/media/dvb/frontend.xml
@@ -744,7 +744,7 @@ typedef enum fe_hierarchy {
 </para>
 <informaltable><tgroup cols="1"><tbody><row><entry
  align="char">
-<para>int ioctl(int fd, int request = <link linkend="FE_READ_SNR">FE_READ_SNR</link>, int16_t
+<para>int ioctl(int fd, int request = <link linkend="FE_READ_SNR">FE_READ_SNR</link>, uint16_t
  &#x22C6;snr);</para>
 </entry>
  </row></tbody></tgroup></informaltable>
@@ -766,7 +766,7 @@ typedef enum fe_hierarchy {
 </entry>
  </row><row><entry
  align="char">
-<para>int16_t *snr</para>
+<para>uint16_t *snr</para>
 </entry><entry
  align="char">
 <para>The signal-to-noise ratio is stored into *snr.</para>
@@ -791,7 +791,7 @@ typedef enum fe_hierarchy {
 <informaltable><tgroup cols="1"><tbody><row><entry
  align="char">
 <para>int ioctl( int fd, int request =
- <link linkend="FE_READ_SIGNAL_STRENGTH">FE_READ_SIGNAL_STRENGTH</link>, int16_t &#x22C6;strength);</para>
+ <link linkend="FE_READ_SIGNAL_STRENGTH">FE_READ_SIGNAL_STRENGTH</link>, uint16_t &#x22C6;strength);</para>
 </entry>
  </row></tbody></tgroup></informaltable>
 
@@ -814,7 +814,7 @@ typedef enum fe_hierarchy {
 </entry>
  </row><row><entry
  align="char">
-<para>int16_t *strength</para>
+<para>uint16_t *strength</para>
 </entry><entry
  align="char">
 <para>The signal strength value is stored into *strength.</para>
-- 
1.8.4