Upcoming v4l-utils 1.6.0 release

Upcoming v4l-utils 1.6.0 release

[Gregor Jasny]

Hello,

Mauro was very busy adding Doxygen documentation to libdvbv5. Instead of
cherry picking the (many) individual commits I'd like to release master
as 1.6.0.

Has anyone uncommited pending work? If not I'd like to release on Monday
(29th).

About the DVB API/ABI incompatibility discussed below:

As far as I understand the service_location feature should work but is
an extension to the standard. Does it harm if we keep it until we have
something better in place to handle extensions?

The service list descriptor feature is unimplemented (and thus broken).
Would it help if we return -1 from dvb_desc_service_list_init to reflect
that fact or does it break something else? But I'd keep the symbol in
the library to maintain ABI compatibility.

Is there a reason to expose the individual descriptor functions to the
public API? Aren't dvb_descriptors table and its users enough?

Thanks,
Gregor

On 26/09/14 02:38, Mauro Carvalho Chehab wrote:
> Hi Gregor,
> 
> I'm done with the libdvbv5 API documentation. There are two issues there that
> we should be fixing on a next release:
> 1) one descriptor should likely be removed.
>    It is the one contained at lib/libdvbv5/include/desc_service_location.h
> 
> It is not used anywhere at the code (nor on userspace). I suspect that this
> is wrong, because I was unable to find any documentation about that. It
> looks very similar to an ATSC descriptor. I suspect that this is just
> duplicated (yet, see the comments below).
> 
> 2) one descriptor should have a table fixed or be removed.
>    it is at lib/libdvbv5/include/desc_service_list.h.
> 
> This one have the parsing code commented. This is not that bad, if the
> data structure field needed to store its content weren't also commented.
> 
> Either removing or fixing will break the API/ABI.
> 
> I opted to not add those descriptors at the doxygen documentation. Just
> added the javadoc tags inside their code, with a @bug there.
> 
> So, I think we should try to release 1.4.1 with those changes.
> 
> Please notice that I also added one extra feature at dma-fe-tool: it
> now replaces femon (with is something that people that use to work with
> the legacy dvb-apps generally request).
> 
> Ah, btw if you know who maintains the dtv-scan-tables package on Debian,
> it could be worth to ask him to rebase the package to use the new format.
> The tables there were fully converted to DVBv5 format, and a Makefile
> target was added to generate the tables with the old format.
> 
> Regards,
> Mauro
> 
> 
> Forwarded message:
> 
> Date: Mon, 22 Sep 2014 23:08:35 +0200
> From: André Roth <neolynx@gmail.com>
> To: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
> Subject: Re: Troubles with two descriptor parsers
> 
> 
> On Mon, 22 Sep 2014 13:39:06 -0300
> Mauro Carvalho Chehab <mchehab@osg.samsung.com> wrote:
> 
>> Hi André,
>>
>> I finished to add documentation for the library. There are, however, two
>> issues:
>>
>> 1) I was unable to discover what's this:
>> 	http://git.linuxtv.org/cgit.cgi/v4l-utils.git/commit/?id=dbb24d3a680dc66496e410cb1cab56ef375f1982
>>
>> There is a descriptor like that for ATSC, but didn't find it for DVB.
>> Also, this is not used at descriptors.c.
> 
> this is used as a user extension (0xa1) in DVB-T here. a friend
> implemented it, I need to ask where he got the specs from. It holds GPS
> coordinates of the sending station. not sure whether libdvbv5 should
> implement user extensions as they could vary. 
> we should maybe have an interface for extending the descriptor table ...
>  
>> Is this some left-over?
> 
> kinda, I had planned to implement it in tvd, and maybe show a map with
> the antenna.
> 
>> 2) This is broken:
>> 	http://git.linuxtv.org/cgit.cgi/v4l-utils.git/commit/?id=7ce5581c7504ff03425666e106d198de3475d0e9
>>
>> As the descriptor parser is commented. Why? We can only fix that for a
>> newer version.
> 
> same story I guess. the service list descriptor (0x41) is in the iso
> standard and is maybe used in conjunction with 0xa1.
> 
> I suggest to fix that in the newer version. Please tell me when a newer
> version is planned, so I can reserve some time for that.
> 
> Sorry for the inconvenience,
>  André
> 

Re: Upcoming v4l-utils 1.6.0 release

[Mauro Carvalho Chehab]

Em Sat, 27 Sep 2014 12:57:11 +0200
Gregor Jasny <gjasny@googlemail.com> escreveu:

> Hello,
> 
> Mauro was very busy adding Doxygen documentation to libdvbv5. Instead of
> cherry picking the (many) individual commits I'd like to release master
> as 1.6.0.

Works for me.

> Has anyone uncommited pending work? If not I'd like to release on Monday
> (29th).
> 
> About the DVB API/ABI incompatibility discussed below:
> 
> As far as I understand the service_location feature should work but is
> an extension to the standard. Does it harm if we keep it until we have
> something better in place to handle extensions?

I'm not sure if it works, as the table parser doesn't call that code.
Ok, some library client could use it, but I don't think that this is
actually being used on tvdaemon.

> The service list descriptor feature is unimplemented (and thus broken).
> Would it help if we return -1 from dvb_desc_service_list_init to reflect
> that fact or does it break something else? But I'd keep the symbol in
> the library to maintain ABI compatibility.

The big problem with the service list descriptor is that there's a
field commented on its structure. Once we decide to implement it,
we'll need to uncomment such field or to replace it with something
else. At the moment we do that, we'll be breaking ABI compatibility.

I would actually prefer if we could get rid of those two broken
descriptors on some release, and to re-add them only when they're
actually working.

> Is there a reason to expose the individual descriptor functions to the
> public API? Aren't dvb_descriptors table and its users enough?

That depends on the usecase. For applications like dvbv5 tools,
that only use the library to scan channels and tune, there's no need.

However, if the application wants to do something more fancy, like
parsing the program guide, it will need to look inside the EIT
descriptors, where the program guide is stored.

There's also a feature that André is working to add to tvdaemon and to
the libdvbv5 library. He can comment a little more about his needs.

As far of what I understood, he wants to use the library to produce
a MPEG-TS, probably to generate what is called MPEG remux.

MPEG remux means to be able to create a new MPEG-TS with a subset of 
the elementary streams that are found on the original stream. In other
words, imagine a stream with 6 independent channels multiplexed inside a 
single MPEG-TS (this is common on DVB-C). A remuxed MPEG could contain
just one of those channels.

In order to be able to create a MPEG-TS, the application need to
be able to handle all tables/descriptors required to produce it.

Regards,
Mauro

Re: Upcoming v4l-utils 1.6.0 release

[Gregor Jasny]

Hello,

On 27/09/14 13:54, Mauro Carvalho Chehab wrote:
> Em Sat, 27 Sep 2014 12:57:11 +0200
> Gregor Jasny <gjasny@googlemail.com> escreveu:
>> As far as I understand the service_location feature should work but is
>> an extension to the standard. Does it harm if we keep it until we have
>> something better in place to handle extensions?
>>
>> The service list descriptor feature is unimplemented (and thus broken).
>> Would it help if we return -1 from dvb_desc_service_list_init to reflect
>> that fact or does it break something else? But I'd keep the symbol in
>> the library to maintain ABI compatibility.

> I would actually prefer if we could get rid of those two broken
> descriptors on some release, and to re-add them only when they're
> actually working.

I have sent a patch series to remove the public headers of this two
descriptors and provide stubs to maintain SONAME compatibility.

Could you please ACK it?

Thanks,
Gregor

Re: Upcoming v4l-utils 1.6.0 release

[Hans de Goede]

Hi,

On 09/30/2014 05:20 PM, Gregor Jasny wrote:
> Hello,
>
> On 27/09/14 13:54, Mauro Carvalho Chehab wrote:
>> Em Sat, 27 Sep 2014 12:57:11 +0200
>> Gregor Jasny <gjasny@googlemail.com> escreveu:
>>> As far as I understand the service_location feature should work but is
>>> an extension to the standard. Does it harm if we keep it until we have
>>> something better in place to handle extensions?
>>>
>>> The service list descriptor feature is unimplemented (and thus broken).
>>> Would it help if we return -1 from dvb_desc_service_list_init to reflect
>>> that fact or does it break something else? But I'd keep the symbol in
>>> the library to maintain ABI compatibility.
>
>> I would actually prefer if we could get rid of those two broken
>> descriptors on some release, and to re-add them only when they're
>> actually working.
>
> I have sent a patch series to remove the public headers of this two
> descriptors and provide stubs to maintain SONAME compatibility.
>
> Could you please ACK it?

About the 1.6.0 release, please do not release it until the series
fixing the regression in 1.4.0 with gstreamer which I've posted
today. A review of that series would be appreciated. If you're ok
with the series feel free to push it to master.

Regards,

Hans

Re: Upcoming v4l-utils 1.6.0 release

[Mauro Carvalho Chehab]

Em Tue, 30 Sep 2014 18:29:26 +0200
Hans de Goede <hdegoede@redhat.com> escreveu:

> Hi,
> 
> On 09/30/2014 05:20 PM, Gregor Jasny wrote:
> > Hello,
> >
> > On 27/09/14 13:54, Mauro Carvalho Chehab wrote:
> >> Em Sat, 27 Sep 2014 12:57:11 +0200
> >> Gregor Jasny <gjasny@googlemail.com> escreveu:
> >>> As far as I understand the service_location feature should work but is
> >>> an extension to the standard. Does it harm if we keep it until we have
> >>> something better in place to handle extensions?
> >>>
> >>> The service list descriptor feature is unimplemented (and thus broken).
> >>> Would it help if we return -1 from dvb_desc_service_list_init to reflect
> >>> that fact or does it break something else? But I'd keep the symbol in
> >>> the library to maintain ABI compatibility.
> >
> >> I would actually prefer if we could get rid of those two broken
> >> descriptors on some release, and to re-add them only when they're
> >> actually working.
> >
> > I have sent a patch series to remove the public headers of this two
> > descriptors and provide stubs to maintain SONAME compatibility.
> >
> > Could you please ACK it?
> 
> About the 1.6.0 release, please do not release it until the series
> fixing the regression in 1.4.0 with gstreamer which I've posted
> today. A review of that series would be appreciated. If you're ok
> with the series feel free to push it to master.

>From my side, I'm happy with the changes made at libdvbv5 side.

I did several changes during this week:

- Added user pages for the 4 dvbv5 tools;
- Cleaned up all Valgrind errors;
- Cleaned up a nasty double-free bug;
- Solved all the issues pointed for it at Coverity.
- Added the package version on all section 1 man pages. Those are now
  created during ./configure.

I also did some tests here with DVB-C and ISDB-T and everything seems to
be working fine.

So, at least from dvbv5 utils and libdvbv5, I think we're ready for
version 1.6.

Regards,
Mauro

Re: Upcoming v4l-utils 1.6.0 release

[Gregor Jasny]

Hello,

On 04/10/14 16:22, Mauro Carvalho Chehab wrote:
> Em Tue, 30 Sep 2014 18:29:26 +0200
> Hans de Goede <hdegoede@redhat.com> escreveu:
>> About the 1.6.0 release, please do not release it until the series
>> fixing the regression in 1.4.0 with gstreamer which I've posted
>> today. A review of that series would be appreciated. If you're ok
>> with the series feel free to push it to master.

I pushed the changes to master ans built a Debian package with the
changes. The bug reported verified that it properly fixed the bug.

> From my side, I'm happy with the changes made at libdvbv5 side.
> 
> I did several changes during this week:
> 
> - Added user pages for the 4 dvbv5 tools;
> - Cleaned up all Valgrind errors;
> - Cleaned up a nasty double-free bug;
> - Solved all the issues pointed for it at Coverity.
> - Added the package version on all section 1 man pages. Those are now
>   created during ./configure.
> 
> I also did some tests here with DVB-C and ISDB-T and everything seems to
> be working fine.
> 
> So, at least from dvbv5 utils and libdvbv5, I think we're ready for
> version 1.6.

I made some changes to the man pages to silence Lintian warnings and put
the release stamp on the tree.

Thanks,
Gregor

Re: Upcoming v4l-utils 1.6.0 release

[Mauro Carvalho Chehab]

Em Sun, 05 Oct 2014 21:38:45 +0200
Gregor Jasny <gjasny@googlemail.com> escreveu:

> Hello,
> 
> On 04/10/14 16:22, Mauro Carvalho Chehab wrote:
> > Em Tue, 30 Sep 2014 18:29:26 +0200
> > Hans de Goede <hdegoede@redhat.com> escreveu:
> >> About the 1.6.0 release, please do not release it until the series
> >> fixing the regression in 1.4.0 with gstreamer which I've posted
> >> today. A review of that series would be appreciated. If you're ok
> >> with the series feel free to push it to master.
> 
> I pushed the changes to master ans built a Debian package with the
> changes. The bug reported verified that it properly fixed the bug.
> 
> > From my side, I'm happy with the changes made at libdvbv5 side.
> > 
> > I did several changes during this week:
> > 
> > - Added user pages for the 4 dvbv5 tools;
> > - Cleaned up all Valgrind errors;
> > - Cleaned up a nasty double-free bug;
> > - Solved all the issues pointed for it at Coverity.
> > - Added the package version on all section 1 man pages. Those are now
> >   created during ./configure.
> > 
> > I also did some tests here with DVB-C and ISDB-T and everything seems to
> > be working fine.
> > 
> > So, at least from dvbv5 utils and libdvbv5, I think we're ready for
> > version 1.6.
> 
> I made some changes to the man pages to silence Lintian warnings and put
> the release stamp on the tree.

Seemed OK from my side. I also built the Fedora packages:

	Fedora 22: http://koji.fedoraproject.org/koji/buildinfo?buildID=582762
	Fedora 21: http://koji.fedoraproject.org/koji/buildinfo?buildID=582763
	Fedora 20: http://koji.fedoraproject.org/koji/buildinfo?buildID=582802

Regards,
Mauro

Re: Upcoming v4l-utils 1.6.0 release

[Mauro Carvalho Chehab]

Hi Gregor,

Em Sun, 05 Oct 2014 21:38:45 +0200
Gregor Jasny <gjasny@googlemail.com> escreveu:

> Hello,
> 
> On 04/10/14 16:22, Mauro Carvalho Chehab wrote:
> > Em Tue, 30 Sep 2014 18:29:26 +0200
> > Hans de Goede <hdegoede@redhat.com> escreveu:
> >> About the 1.6.0 release, please do not release it until the series
> >> fixing the regression in 1.4.0 with gstreamer which I've posted
> >> today. A review of that series would be appreciated. If you're ok
> >> with the series feel free to push it to master.
> 
> I pushed the changes to master ans built a Debian package with the
> changes. The bug reported verified that it properly fixed the bug.

While waiting for this package to get enough carma to merge it on F21,
I was wandering that, as we don't quite follow http://semver.org/
versioning, we should document it. So, I wrote the enclosed patch.

Please review.

Regards,
Mauro

README: better document the package

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


diff --git a/README b/README
index a9f8089..f12b37d 100644
--- a/README
+++ b/README
@@ -1,20 +1,124 @@
 v4l-utils
 ---------
 
-Linux V4L2 and DVB API utilities and v4l libraries (libv4l).
+Linux utilities and libraries to handle media devices (TV devices,
+capture devices, radio devices, remote controllers).
+
 You can always find the latest development v4l-utils in the git repo:
-http://git.linuxtv.org/v4l-utils.git
+	http://git.linuxtv.org/v4l-utils.git
 
+Those utilities follow the latest Linux Kernel media API, as documented
+at:
+	http://linuxtv.org/downloads/v4l-dvb-apis/
 
-v4l libraries (libv4l, libdvbv5)
---------------------------------
+----------
+versioning
+----------
 
-See README.libv4l for more information on libv4l, libv4l is released
-under the GNU Lesser General Public License.
+The v4l-utils doesn't quite follow the release versioning defined
+at semver.org.
 
+Instead, since version 1.0, it uses:
 
-v4l-utils
+	MAJOR.MINOR.PATCH
+
+Where:
+
+	MINOR - an odd number means a development version. When
+		the development is closed, we release an even
+		numbered version and start a newer odd version;
+
+	MAJOR - It is incremented when MINOR number starts to be
+		too big. The last change occurred from 0.9.x to 1.0.
+
+	All numbers start with 0.
+
+All versions have their own tags, except for the current
+deveopment version (with uses the master branch at the git tree).
+
+The PATCH meaning actually depends if the version is stable
+or developent.
+
+For even MAJOR.MINOR versions (1.0, 1.2, 1.4, 1.6, ...)
+
+	PATCH is incremented when just bug fixes are added;
+
+For odd MAJOR.MINOR versions (1.1, 1.3, 1.5, 1.7, ...)
+	PATCH is incremented for release candidate versions.
+
+API/ABI stability:
+-----------------
+
+There should not have any API/ABI changes when PATCH is incremented.
+
+When MAJOR and/or MINOR are incremented, the API/ABI for the
+libraries might change, although we do all the efforts for not
+doing it, except when inevitable.
+
+The TODO files should specify the events that will generate
+API/ABI breaks.
+
+---------------
+media libraries
+---------------
+
+There are currently three media libraries defined at /lib directory,
+meant to be used internally and by other applications.
+
+libv4l
+------
+
+This library is meant to be used by applications that need to
+talk with V4L2 devices (webcams, analog TV, stream grabbers).
+
+It can be found on the following directories:
+	lib/libv4l1
+	lib/libv4l2
+	lib/libv4l-mplane
+	lib/libv4lconvert
+
+See README.libv4l for more information on libv4l.
+
+The libv4l is released under the GNU Lesser General Public License.
+
+libdvbv5
+--------
+
+This library is meant to be used by digital TV applications that
+need to talk with media hardware.
+
+Full documentation is provided via Doxygen. It can be built,
+after configuring the package, with:
+	$ make doxygen-run
+
+It is possible to generate documentation in html, man pages and pdf
+formats.
+
+The documentation is also available via web, at:
+	http://linuxtv.org/docs/libdvbv5/
+
+It can be found on the following directory:
+	lib/libdvbv5
+
+The libdvbv5 is released under GPL version 2.
+
+
+libv4l2rds
+----------
+
+This library provides support for RDS radio applications.
+
+It can be found on the following directory:
+	lib/libv4l2rds
+
+The libv4l is released under the GNU Lesser General Public License.
+
+---------
+Utilities
 ---------
+
+The utilities are stored under /util directory.
+
 The (for now for v4l-utils private use only) libv4l2util library is
 released under the GNU Lesser General Public License, all other code is
 released under the GNU General Public License.