Skip to contentSkip to conversation

V4L/DVB API specifications at linux kernel

DISCUSSION Mauro Carvalho Chehab 3 participants 6 messages Sep 15, 2009 – Sep 16, 2009 Media (V4L/DVB)

lore
Share & tools
lore
#0 lore raw

Something that always bothered me is that the documentation inside the kernel for V4L/DVB were never properly updated, since people that write drivers in general don't bother to keep the docs updated there. After some time, we've removed V4L1 API from kernel (in text format, as far as I can remember), but never added V4L2 API. Also, there weren't there any dvb api specs.

As an effort to change it, I did a work during the last few weeks to port V4L2 API from DocBook v3.1 to DocBook XML v4.1.2. I also ported DVB specs from LaTex into DocBook XML v4.1.2. This way, the API docs are compatible with the DocBook version used in kernel (even eventually not having the same writing style as found there).

I tried to make the port as simple as possible, yet preserving the original text. So, for sure there are space for style reviews, especially at the dvb part, where the LaTex -> xml conversion were harder.

After having both ported, I've rearranged a few chapters and merged them both into just one DocBook book, to allow having some parts shared, like IR.

The final document were broken into 3 parts:
I. Video for Linux Two API Specification
(basically, the same contents found at V4L2 spec version 2.6.32, except for IR chapter)
II. Linux DVB API
(basically, the same contents found at DVB spec version 3)
III. Other API's used by media infrastructure drivers
(basically, the IR chapter taken from V4L2 spec)

The resulting html pages can be seen at: http://linuxtv.org/downloads/v4l_dvb_apis/

The Kernel patches with the Document are at:

http://git.kernel.org/?p=linux/kernel/git/mchehab/linux-next.git;a=commit;h=9444a960e4c7c49e055bb7fa66a0805c46317ba0
http://git.kernel.org/?p=linux/kernel/git/mchehab/linux-next.git;a=commit;h=664efd3215fdb17d5f3f70073af4a6b61d50a96c

Please review. If they're ok, I'm intending to submit them for addition at 2.6.32.

Cheers,
Mauro

#1 lore raw
Quoted 26 lines · On Tue, 15 Sep 2009 16:20:02 -0300 Mauro Carvalho Chehab wrote:

Something that always bothered me is that the documentation inside the kernel for V4L/DVB were never properly updated, since people that write drivers in general don't bother to keep the docs updated there. After some time, we've removed V4L1 API from kernel (in text format, as far as I can remember), but never added V4L2 API. Also, there weren't there any dvb api specs.

As an effort to change it, I did a work during the last few weeks to port V4L2 API from DocBook v3.1 to DocBook XML v4.1.2. I also ported DVB specs from LaTex into DocBook XML v4.1.2. This way, the API docs are compatible with the DocBook version used in kernel (even eventually not having the same writing style as found there).

I tried to make the port as simple as possible, yet preserving the original text. So, for sure there are space for style reviews, especially at the dvb part, where the LaTex -> xml conversion were harder.

After having both ported, I've rearranged a few chapters and merged them both into just one DocBook book, to allow having some parts shared, like IR.

The final document were broken into 3 parts:
I. Video for Linux Two API Specification
(basically, the same contents found at V4L2 spec version 2.6.32, except for IR chapter)
II. Linux DVB API
(basically, the same contents found at DVB spec version 3)
III. Other API's used by media infrastructure drivers
(basically, the IR chapter taken from V4L2 spec)

Quoted 8 lines

The resulting html pages can be seen at: http://linuxtv.org/downloads/v4l_dvb_apis/

The Kernel patches with the Document are at:

http://git.kernel.org/?p=linux/kernel/git/mchehab/linux-next.git;a=commit;h=9444a960e4c7c49e055bb7fa66a0805c46317ba0
http://git.kernel.org/?p=linux/kernel/git/mchehab/linux-next.git;a=commit;h=664efd3215fdb17d5f3f70073af4a6b61d50a96c

Please review. If they're ok, I'm intending to submit them for addition at 2.6.32.

Hi Mauro,

That's large, :) so I'm not planning to review it in great detail.

Here are some comments on it:

1. http://linuxtv.org/downloads/v4l_dvb_apis/index.html

List of Figures:

where are the figures? how do I see them?

2. http://linuxtv.org/downloads/v4l_dvb_apis/ch01.html

"
In /etc/modules.conf this may be written as:

alias char-major-81-0 mydriver
alias char-major-81-1 mydriver
alias char-major-81-64 mydriver 1
options mydriver video_nr=0,1 radio_nr=0,1 2
"

The trailing 1 and 2 there are not part of the modules.conf file, are they? Are they footnote pointers? They are a bit confusing.

3. http://linuxtv.org/downloads/v4l_dvb_apis/ch01s10.html

footnote 11:
"Enumerating formats an application has no a-priori knowledge of (otherwise it could explicitely ask for them and need not enumerate) seems useless, but there are applications serving as proxy between drivers and the actual video applications for which this is useful."

s/explicitely/explicitly/

4. http://linuxtv.org/downloads/v4l_dvb_apis/ch04s09.html

The URL:http://home.pages.de/~videotext/ is not found. Checking more of them might be in order.

5. http://linuxtv.org/downloads/v4l_dvb_apis/apc.html

" * This program were got from V4L2 API, Draft 0.20"

s/were got/was taken/

6. http://linuxtv.org/downloads/v4l_dvb_apis/ch17.html

"It is not rare that the same manufacturer to ship different types of controls, depending on the device."

-->
It is not rare for the same manufacturer to ship ...

"Unfortunately, during several years, there weren't any effort to uniform the IR keycodes under different boards. This resulted that the same IR keyname to be mapped completely different on different IR's. Due to that, V4L2 API now specifies a standard for mapping Media keys on IR."

--> (possibly:)
Unfortunately, for several years, there was no effort to create uniform IR keycodes for different devices. This caused the same IR keyname to be mapped completely differently on different IR devices. ....

Anyway, lots of good info there. Please push it.

Thanks,
---
~Randy
LPC 2009, Sept. 23-25, Portland, Oregon
http://linuxplumbersconf.org/2009/

#2 lore raw

Em Tue, 15 Sep 2009 14:06:34 -0700
Randy Dunlap <[email protected]> escreveu:

Quoted 42 lines · On Tue, 15 Sep 2009 16:20:02 -0300 Mauro Carvalho Chehab wrote:
Quoted 27 lines

Something that always bothered me is that the documentation inside the kernel for V4L/DVB were never properly updated, since people that write drivers in general don't bother to keep the docs updated there. After some time, we've removed V4L1 API from kernel (in text format, as far as I can remember), but never added V4L2 API. Also, there weren't there any dvb api specs.

As an effort to change it, I did a work during the last few weeks to port V4L2 API from DocBook v3.1 to DocBook XML v4.1.2. I also ported DVB specs from LaTex into DocBook XML v4.1.2. This way, the API docs are compatible with the DocBook version used in kernel (even eventually not having the same writing style as found there).

I tried to make the port as simple as possible, yet preserving the original text. So, for sure there are space for style reviews, especially at the dvb part, where the LaTex -> xml conversion were harder.

After having both ported, I've rearranged a few chapters and merged them both into just one DocBook book, to allow having some parts shared, like IR.

The final document were broken into 3 parts:
I. Video for Linux Two API Specification
(basically, the same contents found at V4L2 spec version 2.6.32, except for IR chapter)
II. Linux DVB API
(basically, the same contents found at DVB spec version 3)
III. Other API's used by media infrastructure drivers
(basically, the IR chapter taken from V4L2 spec)

Quoted 8 lines

The resulting html pages can be seen at: http://linuxtv.org/downloads/v4l_dvb_apis/

The Kernel patches with the Document are at:

http://git.kernel.org/?p=linux/kernel/git/mchehab/linux-next.git;a=commit;h=9444a960e4c7c49e055bb7fa66a0805c46317ba0
http://git.kernel.org/?p=linux/kernel/git/mchehab/linux-next.git;a=commit;h=664efd3215fdb17d5f3f70073af4a6b61d50a96c

Please review. If they're ok, I'm intending to submit them for addition at 2.6.32.

Hi Mauro,

That's large, :) so I'm not planning to review it in great detail.

Quoted 8 lines

Here are some comments on it:

1. http://linuxtv.org/downloads/v4l_dvb_apis/index.html

List of Figures:

where are the figures? how do I see them?

Hmm... Makefile magic... It needs to be copied to the right place ;) I'll add some Makefile glue for it. Nothing sophisticated, but it will work.

Quoted 8 lines

2. http://linuxtv.org/downloads/v4l_dvb_apis/ch01.html

"
In /etc/modules.conf this may be written as:

Quoted 8 lines

alias char-major-81-0 mydriver
alias char-major-81-1 mydriver
alias char-major-81-64 mydriver 1
options mydriver video_nr=0,1 radio_nr=0,1 2
"

The trailing 1 and 2 there are not part of the modules.conf file, are they? Are they footnote pointers? They are a bit confusing.

They are generated via callout's. I'll use the suggestion here to disable them:
http://www.sagehill.net/docbookxsl/Icons.html

They'll now be better displayed as text. I've changed the xsl file. They'll be now shown as (1) and (2).

Quoted 6 lines

3. http://linuxtv.org/downloads/v4l_dvb_apis/ch01s10.html

footnote 11:
"Enumerating formats an application has no a-priori knowledge of (otherwise it could explicitely ask for them and need not enumerate) seems useless, but there are applications serving as proxy between drivers and the actual video applications for which this is useful."

s/explicitely/explicitly/

Fixed.

Quoted 5 lines

4. http://linuxtv.org/downloads/v4l_dvb_apis/ch04s09.html

The URL:http://home.pages.de/~videotext/ is not found. Checking more of them might be in order.

Ok, I fixed most of the refs. Still, there are two SGI links that are outdated, and I couldn't find the current place. Helps are wanted to solve this ;)

Quoted 7 lines

5. http://linuxtv.org/downloads/v4l_dvb_apis/apc.html

" * This program were got from V4L2 API, Draft 0.20"

s/were got/was taken/

Better to rewrite the entire text to:

* This program is provided with V4L2 API
* see http://linuxtv.org/docs.php for more information

We might eventually just remove, but this program is also distributed together with the development tree, so, it is better to point it to the complete docs.

Quoted 8 lines

6. http://linuxtv.org/downloads/v4l_dvb_apis/ch17.html

"It is not rare that the same manufacturer to ship different types of controls, depending on the device."

-->
It is not rare for the same manufacturer to ship ...

Quoted 6 lines

"Unfortunately, during several years, there weren't any effort to uniform the IR keycodes under different boards. This resulted that the same IR keyname to be mapped completely different on different IR's. Due to that, V4L2 API now specifies a standard for mapping Media keys on IR."

--> (possibly:)
Unfortunately, for several years, there was no effort to create uniform IR keycodes for different devices. This caused the same IR keyname to be mapped completely differently on different IR devices. ....

Replaced.

Quoted 2 lines

Anyway, lots of good info there. Please push it.

Thanks. I'll be updating the site and my linux-next tree soon.

Quoted 6 lines

Thanks,
---
~Randy
LPC 2009, Sept. 23-25, Portland, Oregon
http://linuxplumbersconf.org/2009/

Cheers,
Mauro

#3 lore raw
In reply to Mauro Carvalho Chehab
Quoted 26 lines · On Tuesday 15 September 2009 21:20:02 Mauro Carvalho Chehab wrote:

Something that always bothered me is that the documentation inside the kernel for V4L/DVB were never properly updated, since people that write drivers in general don't bother to keep the docs updated there. After some time, we've removed V4L1 API from kernel (in text format, as far as I can remember), but never added V4L2 API. Also, there weren't there any dvb api specs.

As an effort to change it, I did a work during the last few weeks to port V4L2 API from DocBook v3.1 to DocBook XML v4.1.2. I also ported DVB specs from LaTex into DocBook XML v4.1.2. This way, the API docs are compatible with the DocBook version used in kernel (even eventually not having the same writing style as found there).

I tried to make the port as simple as possible, yet preserving the original text. So, for sure there are space for style reviews, especially at the dvb part, where the LaTex -> xml conversion were harder.

After having both ported, I've rearranged a few chapters and merged them both into just one DocBook book, to allow having some parts shared, like IR.

The final document were broken into 3 parts:
I. Video for Linux Two API Specification
(basically, the same contents found at V4L2 spec version 2.6.32, except for IR chapter)
II. Linux DVB API
(basically, the same contents found at DVB spec version 3)
III. Other API's used by media infrastructure drivers
(basically, the IR chapter taken from V4L2 spec)

Quoted 8 lines

The resulting html pages can be seen at: http://linuxtv.org/downloads/v4l_dvb_apis/

The Kernel patches with the Document are at:

http://git.kernel.org/?p=linux/kernel/git/mchehab/linux-next.git;a=commit;h=9444a960e4c7c49e055bb7fa66a0805c46317ba0
http://git.kernel.org/?p=linux/kernel/git/mchehab/linux-next.git;a=commit;h=664efd3215fdb17d5f3f70073af4a6b61d50a96c

Please review. If they're ok, I'm intending to submit them for addition at 2.6.32.

Good work!

Some suggestions:

Drop the 'Satellite Receivers' topic in the 'Tuners and Modulators' section. That's now handled by the DVB API.

Drop section 5 (V4L2 Driver Programming). Eventually we might move the v4l2-framework.txt documentation there, but for now it can safely be removed.

Do we really want section 7 (Changes) as part of the kernel documentation? I'm not sure if it belongs there.

Regards,

Hans

Signature · 1 line
Hans Verkuil - video4linux developer - sponsored by TANDBERG Telecom
#4 lore raw

Em Tue, 15 Sep 2009 23:16:05 +0200
Hans Verkuil <[email protected]> escreveu:

Quoted 34 lines · On Tuesday 15 September 2009 21:20:02 Mauro Carvalho Chehab wrote:
Quoted 33 lines

Something that always bothered me is that the documentation inside the kernel for V4L/DVB were never properly updated, since people that write drivers in general don't bother to keep the docs updated there. After some time, we've removed V4L1 API from kernel (in text format, as far as I can remember), but never added V4L2 API. Also, there weren't there any dvb api specs.

As an effort to change it, I did a work during the last few weeks to port V4L2 API from DocBook v3.1 to DocBook XML v4.1.2. I also ported DVB specs from LaTex into DocBook XML v4.1.2. This way, the API docs are compatible with the DocBook version used in kernel (even eventually not having the same writing style as found there).

I tried to make the port as simple as possible, yet preserving the original text. So, for sure there are space for style reviews, especially at the dvb part, where the LaTex -> xml conversion were harder.

After having both ported, I've rearranged a few chapters and merged them both into just one DocBook book, to allow having some parts shared, like IR.

The final document were broken into 3 parts:
I. Video for Linux Two API Specification
(basically, the same contents found at V4L2 spec version 2.6.32, except for IR chapter)
II. Linux DVB API
(basically, the same contents found at DVB spec version 3)
III. Other API's used by media infrastructure drivers
(basically, the IR chapter taken from V4L2 spec)

The resulting html pages can be seen at: http://linuxtv.org/downloads/v4l_dvb_apis/

The Kernel patches with the Document are at:

http://git.kernel.org/?p=linux/kernel/git/mchehab/linux-next.git;a=commit;h=9444a960e4c7c49e055bb7fa66a0805c46317ba0
http://git.kernel.org/?p=linux/kernel/git/mchehab/linux-next.git;a=commit;h=664efd3215fdb17d5f3f70073af4a6b61d50a96c

Quoted 8 lines
Quoted 1 line

Please review. If they're ok, I'm intending to submit them for addition at 2.6.32.

Good work!

Some suggestions:

Drop the 'Satellite Receivers' topic in the 'Tuners and Modulators' section. That's now handled by the DVB API.

Done.

Quoted 2 lines

Drop section 5 (V4L2 Driver Programming). Eventually we might move the v4l2-framework.txt documentation there, but for now it can safely be removed.

Hmm.. in fact, driver.xml has some start, currently commented. IMHO, it is better to keep it there for a while, since something useful may be there.

Quoted 3 lines

Do we really want section 7 (Changes) as part of the kernel documentation? I'm not sure if it belongs there.

Maybe we can drop it in the future, but, as this is the first kernel version for the docs, it seems a good idea to commit it there, to preserve the documentation history. Also, maintaining it separate doesn't make sense.

In the future, we may clean it up, for example converting it into revision marks, or, if we decide that no history is needed, just drop it and be happy.

Cheers,
Mauro

#5 lore raw
Quoted 46 lines · On Wednesday 16 September 2009 02:15:30 Mauro Carvalho Chehab wrote:

Em Tue, 15 Sep 2009 23:16:05 +0200
Hans Verkuil <[email protected]> escreveu:

Quoted 34 lines · On Tuesday 15 September 2009 21:20:02 Mauro Carvalho Chehab wrote:
Quoted 33 lines

Something that always bothered me is that the documentation inside the kernel for V4L/DVB were never properly updated, since people that write drivers in general don't bother to keep the docs updated there. After some time, we've removed V4L1 API from kernel (in text format, as far as I can remember), but never added V4L2 API. Also, there weren't there any dvb api specs.

As an effort to change it, I did a work during the last few weeks to port V4L2 API from DocBook v3.1 to DocBook XML v4.1.2. I also ported DVB specs from LaTex into DocBook XML v4.1.2. This way, the API docs are compatible with the DocBook version used in kernel (even eventually not having the same writing style as found there).

I tried to make the port as simple as possible, yet preserving the original text. So, for sure there are space for style reviews, especially at the dvb part, where the LaTex -> xml conversion were harder.

After having both ported, I've rearranged a few chapters and merged them both into just one DocBook book, to allow having some parts shared, like IR.

The final document were broken into 3 parts:
I. Video for Linux Two API Specification
(basically, the same contents found at V4L2 spec version 2.6.32, except for IR chapter)
II. Linux DVB API
(basically, the same contents found at DVB spec version 3)
III. Other API's used by media infrastructure drivers
(basically, the IR chapter taken from V4L2 spec)

The resulting html pages can be seen at: http://linuxtv.org/downloads/v4l_dvb_apis/

The Kernel patches with the Document are at:

http://git.kernel.org/?p=linux/kernel/git/mchehab/linux-next.git;a=commit;h=9444a960e4c7c49e055bb7fa66a0805c46317ba0
http://git.kernel.org/?p=linux/kernel/git/mchehab/linux-next.git;a=commit;h=664efd3215fdb17d5f3f70073af4a6b61d50a96c

Quoted 8 lines
Quoted 1 line

Please review. If they're ok, I'm intending to submit them for addition at 2.6.32.

Good work!

Some suggestions:

Drop the 'Satellite Receivers' topic in the 'Tuners and Modulators' section. That's now handled by the DVB API.

Quoted 7 lines

Done.

Quoted 2 lines

Drop section 5 (V4L2 Driver Programming). Eventually we might move the v4l2-framework.txt documentation there, but for now it can safely be removed.

Hmm.. in fact, driver.xml has some start, currently commented. IMHO, it is better to keep it there for a while, since something useful may be there.

I just looked at it, and there is nothing useful there. If we are going to add a section like this, then it will be based around v4l2-framework.txt.

It might actually be a reasonable alternative to just convert that text file into xml and have it replace driver.xml.

Regards,

Hans

Quoted 19 lines
Quoted 2 lines

Do we really want section 7 (Changes) as part of the kernel documentation? I'm not sure if it belongs there.

Maybe we can drop it in the future, but, as this is the first kernel version for the docs, it seems a good idea to commit it there, to preserve the documentation history. Also, maintaining it separate doesn't make sense.

In the future, we may clean it up, for example converting it into revision marks, or, if we decide that no history is needed, just drop it and be happy.

Cheers,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to [email protected]
More majordomo info at http://vger.kernel.org/majordomo-info.html

Signature · 1 line
Hans Verkuil - video4linux developer - sponsored by TANDBERG Telecom