Future of the SAA7146 drivers

Future of the SAA7146 drivers

[Stefan Herdler]

Hello everyone.

This mail is a little bit long, I'm sorry for that.
But I have to describe the TV-situation in Germany roughly. Without that
knowledge it is definitely not understandable why this DVB-S cards are
still very useful here.
Reader familiar with this crazy situation may proceed to the driver
section below.

I'm primary a user of this cards but have profound knowledge about the
Hardware. I used to repair the cards for me and other users back then.

I own Fullfeatured and Budget-cards and use them daily in my VDR-System.
In Germany many channels are free-to-air in the DVB-S version only. I
would like to use these cards for a few more years until DVB-S is
deactivated or the HD-Versions of the channels become free-to-air.
I'm not willing to pay 75 Euro a year for TV-commercials in HD and I'm
not the only one with this opinion.
14 million of the 17 million satelite-tv-households in Germany watch
this channels in SD-quality only (~82%)![1]
In addition uses the encrypting-system a proprietary CAM extension which
makes it impossible to watch this channels on a HTPC legally.
This situation won't change until 2025 (by a kind of law!). What then
happens is currently completely uncertain.


The driver topic however is new to me, the cards where always working
out of the box. I noticed the upcoming removal right before my first mail.

Honestly I was a little shocked that the driver may be removed from Kernel.

The card may be old and not produced any more, but they are not rare and
easily obtainable second hand. There are always multiple offers for
reasonable prices on the common platforms.
And the cards are running flawless on current mainboards with PCIe-PCI
Bridge.

There must be a lot of SAA7146 based cards been sold in Europe. Many
brands sold them, mostly rebranded Technotrend cards.
Even Hauppauge, the most important brand, sold the TT-Budged as "Nova"
and the Fullfeatured as "Nexus" for years. Their own Connexant based
designs came pretty late, short before the PCIe-cards.

I carefully estimate, at least 50% of all PCI-DVB-cards sold in Europe
where SAA7146 based.
There must be still a number of users out there.

The relevance of SAA7146 for PCI-DVB-cards is almost like the Bttv-Chips
for analog TV a few years before. At least in Europe.
And the bttv driver not deprecated despite older and using videobuf1 API!


SAA7146 driver
==============

I've read a lot in the last days and the main issue with the SAA7146
driver seems to be the missing maintainer.
All other issues seem to be a result of that.
Right?

And the driver desperately needs someone with expertise about the cards
and the driver.
I've spotted a big chunk of unused code just by knowing which cards have
been build and which not.

Sören Moch offered to maintain the complete SAA7146 driver in the
VDRportal and in this list too. This offer includes the videobuf2
conversion too.
On condition that the support of the fullfeatured cards stays in the
kernel.
I understand that. He only owns fullfeatured cards.
And I am interested in keeping my fullfeatured cards operational too.

I'm convinced Sören could handle the driver well and he is the only one
I know who probably could do that. And he is actively offering to do the
job.


That leads to the DVB-API part for the AV7110 which should be removed.

An API conversion for the AV7110 does not make sense any more. 10 years
ago maybe, but not now.
Working software would be broken and there will be no benefit for the
user at all.

Converting is however not easy and a driver specific UAPI would be
necessary in any case.
The ioctl "VIDEO_SELECT_SOURCE" needed and definitely missing in the
V4l2-API (see ivtv driver).
The OSD of the FF-Cards is more canvas like, not a framebuffer. The OSD
ioctl are also needed and I haven't found anything in V4l2-API to
replace them.

What about putting the 3 API-files into one driver specific UAPI file?
The deprecated DVB-API part could be officially removed and the
maintainer of the av7110 driver would become responsible for the API.
Could that be an acceptable solution for everybody?
Or do the ~10Kb of possible redundancy in the header hurt so much?


The further deferring of the removal by a few years would be a kind of
solution for me too.
But I don't think it's a good one.


Any other ideas?


As a pragmatic user I'm interested in a solution to keep my cards running.
Probably finding a compromise all parties can live with.
I'm not interested in a lengthy discussion about APIs leading to nowhere.

Regards
Stefan



1.
https://www.dwdl.de/magazin/88023/sdrepublik_deutschland_privatsender_mit_hdstrategie_gescheitert/?
In German only, sorry.

Re: Future of the SAA7146 drivers

[Hans Verkuil]

Hi Stefan,

On 30/01/2023 23:19, Stefan Herdler wrote:
> Hello everyone.
> 
> This mail is a little bit long, I'm sorry for that.
> But I have to describe the TV-situation in Germany roughly. Without that
> knowledge it is definitely not understandable why this DVB-S cards are
> still very useful here.
> Reader familiar with this crazy situation may proceed to the driver
> section below.
> 
> I'm primary a user of this cards but have profound knowledge about the
> Hardware. I used to repair the cards for me and other users back then.
> 
> I own Fullfeatured and Budget-cards and use them daily in my VDR-System.
> In Germany many channels are free-to-air in the DVB-S version only. I
> would like to use these cards for a few more years until DVB-S is
> deactivated or the HD-Versions of the channels become free-to-air.
> I'm not willing to pay 75 Euro a year for TV-commercials in HD and I'm
> not the only one with this opinion.
> 14 million of the 17 million satelite-tv-households in Germany watch
> this channels in SD-quality only (~82%)![1]
> In addition uses the encrypting-system a proprietary CAM extension which
> makes it impossible to watch this channels on a HTPC legally.
> This situation won't change until 2025 (by a kind of law!). What then
> happens is currently completely uncertain.
> 
> 
> The driver topic however is new to me, the cards where always working
> out of the box. I noticed the upcoming removal right before my first mail.
> 
> Honestly I was a little shocked that the driver may be removed from Kernel.

Don't worry, the saa7146 driver won't be removed. I admit that that was
my initial plan, but you are not the only one who contacted me to let me
know that the DVB functionality is still in use. I had not expected that
for such old hardware, but it is clear that this driver can't be removed.

> The card may be old and not produced any more, but they are not rare and
> easily obtainable second hand. There are always multiple offers for
> reasonable prices on the common platforms.
> And the cards are running flawless on current mainboards with PCIe-PCI
> Bridge.
> 
> There must be a lot of SAA7146 based cards been sold in Europe. Many
> brands sold them, mostly rebranded Technotrend cards.
> Even Hauppauge, the most important brand, sold the TT-Budged as "Nova"
> and the Fullfeatured as "Nexus" for years. Their own Connexant based
> designs came pretty late, short before the PCIe-cards.
> 
> I carefully estimate, at least 50% of all PCI-DVB-cards sold in Europe
> where SAA7146 based.
> There must be still a number of users out there.
> 
> The relevance of SAA7146 for PCI-DVB-cards is almost like the Bttv-Chips
> for analog TV a few years before. At least in Europe.
> And the bttv driver not deprecated despite older and using videobuf1 API!

The underlying reason for deprecating this driver in the first place was
the use of the old videobuf framework for analog TV in this driver: we
want to get rid of that, either by removing such drivers, or converting
it to vb2 (we plan to do that for bttv and cx18). For the saa7146 there
is another option: dropping the analog TV support only.

> 
> 
> SAA7146 driver
> ==============
> 
> I've read a lot in the last days and the main issue with the SAA7146
> driver seems to be the missing maintainer.
> All other issues seem to be a result of that.
> Right?

Right. I'm on record as the maintainer, but I really don't have the time
to do a substantial job like the vb2 conversion.

> And the driver desperately needs someone with expertise about the cards
> and the driver.
> I've spotted a big chunk of unused code just by knowing which cards have
> been build and which not.
> 
> Sören Moch offered to maintain the complete SAA7146 driver in the
> VDRportal and in this list too. This offer includes the videobuf2
> conversion too.
> On condition that the support of the fullfeatured cards stays in the
> kernel.
> I understand that. He only owns fullfeatured cards.
> And I am interested in keeping my fullfeatured cards operational too.
> 
> I'm convinced Sören could handle the driver well and he is the only one
> I know who probably could do that. And he is actively offering to do the
> job.

Honestly, that would be great. We really need to get rid of the old videobuf
framework, it is awful. I found someone to do the bttv conversion, and I plan
to do the cx18 conversion. So that leaves the saa7146: it's either converted
to vb2, or analog video support (that's the part that uses videobuf) has to
be removed.

Obviously, if someone wants to do the vb2 conversion, then that would be
perfect. I was looking at removing analog video support, and that doesn't
look as easy as I thought it would be.

I can certainly advice how to go about converting to vb2 as I've done it a
few times in the past. It's rather painful, mostly because it is a 'big bang'
change: it ends up as a single large and mostly unreviewable patch.

> 
> 
> That leads to the DVB-API part for the AV7110 which should be removed.
> 
> An API conversion for the AV7110 does not make sense any more. 10 years
> ago maybe, but not now.
> Working software would be broken and there will be no benefit for the
> user at all.
> 
> Converting is however not easy and a driver specific UAPI would be
> necessary in any case.
> The ioctl "VIDEO_SELECT_SOURCE" needed and definitely missing in the
> V4l2-API (see ivtv driver).
> The OSD of the FF-Cards is more canvas like, not a framebuffer. The OSD
> ioctl are also needed and I haven't found anything in V4l2-API to
> replace them.
> 
> What about putting the 3 API-files into one driver specific UAPI file?
> The deprecated DVB-API part could be officially removed and the
> maintainer of the av7110 driver would become responsible for the API.
> Could that be an acceptable solution for everybody?
> Or do the ~10Kb of possible redundancy in the header hurt so much?

I think this can be something that can be discussed later. It's not my
main concern and not the reason why I originally planned to remove the
driver. The use of videobuf is the main problem.

If Sören wants to become an active maintainer for this driver, then the
vb2 conversion would be the first step. But there is a lot more that can
be done, I'm sure.

> 
> 
> The further deferring of the removal by a few years would be a kind of
> solution for me too.
> But I don't think it's a good one.
> 
> 
> Any other ideas?
> 
> 
> As a pragmatic user I'm interested in a solution to keep my cards running.
> Probably finding a compromise all parties can live with.
> I'm not interested in a lengthy discussion about APIs leading to nowhere.

Me neither.

Right now there are two options:

1) removal of the analog video support, keeping DVB support

2) convert the driver to vb2

If Sören steps up as the new maintainer and does the vb2 conversion, then
that would be the best solution. If nobody steps in, then I will most likely
choose option 1 in a few months.

Regards,

	Hans

Re: Future of the SAA7146 drivers

[Stefan Herdler]

Hello Hans,

I'm glad to read that at least the saa7146 driver won't be removed
completely.


On 31/01/23 09:45, Hans Verkuil wrote:
> Hi Stefan,
>
> On 30/01/2023 23:19, Stefan Herdler wrote:
>> Hello everyone.
>>
>> This mail is a little bit long, I'm sorry for that.
>> But I have to describe the TV-situation in Germany roughly. Without that
>> knowledge it is definitely not understandable why this DVB-S cards are
>> still very useful here.
>> Reader familiar with this crazy situation may proceed to the driver
>> section below.
>>
>> I'm primary a user of this cards but have profound knowledge about the
>> Hardware. I used to repair the cards for me and other users back then.
>>
>> I own Fullfeatured and Budget-cards and use them daily in my VDR-System.
>> In Germany many channels are free-to-air in the DVB-S version only. I
>> would like to use these cards for a few more years until DVB-S is
>> deactivated or the HD-Versions of the channels become free-to-air.
>> I'm not willing to pay 75 Euro a year for TV-commercials in HD and I'm
>> not the only one with this opinion.
>> 14 million of the 17 million satelite-tv-households in Germany watch
>> this channels in SD-quality only (~82%)![1]
>> In addition uses the encrypting-system a proprietary CAM extension which
>> makes it impossible to watch this channels on a HTPC legally.
>> This situation won't change until 2025 (by a kind of law!). What then
>> happens is currently completely uncertain.
>>
>>
>> The driver topic however is new to me, the cards where always working
>> out of the box. I noticed the upcoming removal right before my first mail.
>>
>> Honestly I was a little shocked that the driver may be removed from Kernel.
>
> Don't worry, the saa7146 driver won't be removed. I admit that that was
> my initial plan, but you are not the only one who contacted me to let me
> know that the DVB functionality is still in use. I had not expected that
> for such old hardware, but it is clear that this driver can't be removed.
>
>> The card may be old and not produced any more, but they are not rare and
>> easily obtainable second hand. There are always multiple offers for
>> reasonable prices on the common platforms.
>> And the cards are running flawless on current mainboards with PCIe-PCI
>> Bridge.
>>
>> There must be a lot of SAA7146 based cards been sold in Europe. Many
>> brands sold them, mostly rebranded Technotrend cards.
>> Even Hauppauge, the most important brand, sold the TT-Budged as "Nova"
>> and the Fullfeatured as "Nexus" for years. Their own Connexant based
>> designs came pretty late, short before the PCIe-cards.
>>
>> I carefully estimate, at least 50% of all PCI-DVB-cards sold in Europe
>> where SAA7146 based.
>> There must be still a number of users out there.
>>
>> The relevance of SAA7146 for PCI-DVB-cards is almost like the Bttv-Chips
>> for analog TV a few years before. At least in Europe.
>> And the bttv driver not deprecated despite older and using videobuf1 API!
>
> The underlying reason for deprecating this driver in the first place was
> the use of the old videobuf framework for analog TV in this driver: we
> want to get rid of that, either by removing such drivers, or converting
> it to vb2 (we plan to do that for bttv and cx18). For the saa7146 there
> is another option: dropping the analog TV support only.
>
>>
>>
>> SAA7146 driver
>> ==============
>>
>> I've read a lot in the last days and the main issue with the SAA7146
>> driver seems to be the missing maintainer.
>> All other issues seem to be a result of that.
>> Right?
>
> Right. I'm on record as the maintainer, but I really don't have the time
> to do a substantial job like the vb2 conversion.
>
>> And the driver desperately needs someone with expertise about the cards
>> and the driver.
>> I've spotted a big chunk of unused code just by knowing which cards have
>> been build and which not.
>>
>> Sören Moch offered to maintain the complete SAA7146 driver in the
>> VDRportal and in this list too. This offer includes the videobuf2
>> conversion too.
>> On condition that the support of the fullfeatured cards stays in the
>> kernel.
>> I understand that. He only owns fullfeatured cards.
>> And I am interested in keeping my fullfeatured cards operational too.
>>
>> I'm convinced Sören could handle the driver well and he is the only one
>> I know who probably could do that. And he is actively offering to do the
>> job.
>
> Honestly, that would be great. We really need to get rid of the old videobuf
> framework, it is awful. I found someone to do the bttv conversion, and I plan
> to do the cx18 conversion. So that leaves the saa7146: it's either converted
> to vb2, or analog video support (that's the part that uses videobuf) has to
> be removed.
>
> Obviously, if someone wants to do the vb2 conversion, then that would be
> perfect. I was looking at removing analog video support, and that doesn't
> look as easy as I thought it would be.
>
The SAA7146 driver suite is a kind of beast ;-).

I guess it is mainly caused by the DVB-C Budget-Cards.
There are some having analog support too.

> I can certainly advice how to go about converting to vb2 as I've done it a
> few times in the past. It's rather painful, mostly because it is a 'big bang'
> change: it ends up as a single large and mostly unreviewable patch.
>
Indeed, I've searched for some patches and all are huge.
I have some basic C knowledge, but no experience with kerneldrivers nor
vb1 nor vb2. Unfortunately such a conversion would be out of scope for
me. At least if it should be done in a reasonable time frame.

Sören wrote the conversion would't be a big deal for him and it would be
done within a few weeks.

>>
>>
>> That leads to the DVB-API part for the AV7110 which should be removed.
>>
>> An API conversion for the AV7110 does not make sense any more. 10 years
>> ago maybe, but not now.
>> Working software would be broken and there will be no benefit for the
>> user at all.
>>
>> Converting is however not easy and a driver specific UAPI would be
>> necessary in any case.
>> The ioctl "VIDEO_SELECT_SOURCE" needed and definitely missing in the
>> V4l2-API (see ivtv driver).
>> The OSD of the FF-Cards is more canvas like, not a framebuffer. The OSD
>> ioctl are also needed and I haven't found anything in V4l2-API to
>> replace them.
>>
>> What about putting the 3 API-files into one driver specific UAPI file?
>> The deprecated DVB-API part could be officially removed and the
>> maintainer of the av7110 driver would become responsible for the API.
>> Could that be an acceptable solution for everybody?
>> Or do the ~10Kb of possible redundancy in the header hurt so much?
>
> I think this can be something that can be discussed later. It's not my
> main concern and not the reason why I originally planned to remove the
> driver. The use of videobuf is the main problem.
>
> If Sören wants to become an active maintainer for this driver, then the
> vb2 conversion would be the first step. But there is a lot more that can
> be done, I'm sure.
>
Yes he wants, that is his offer to the VDR-community.

He just wants a kind of guarantee, that the driver for the fullfeatured
cards he owns stays in the kernel.
That is understandable for me, he would do the job voluntary without
been payed.

There is a long lasting controversy about the deprecated 3 DVB-API-files
for the av7110 driver.
Sören stated he is tired about that discussions and looking for
permanent solution without having to rewrite the whole driver.

In this case I'm just the messenger, but I would also prefer a permanent
solution.
That is why I made the suggestion with the driver specific UAPI file.
The av7110 driver is only driver using this API-part.
And the modification is fairly easy and the impact minimal.



May that be a compromise all parties can live with?

Regards,
Stefan




>>
>>
>> The further deferring of the removal by a few years would be a kind of
>> solution for me too.
>> But I don't think it's a good one.
>>
>>
>> Any other ideas?
>>
>>
>> As a pragmatic user I'm interested in a solution to keep my cards running.
>> Probably finding a compromise all parties can live with.
>> I'm not interested in a lengthy discussion about APIs leading to nowhere.
>
> Me neither.
>
> Right now there are two options:
>
> 1) removal of the analog video support, keeping DVB support
>
> 2) convert the driver to vb2
>
> If Sören steps up as the new maintainer and does the vb2 conversion, then
> that would be the best solution. If nobody steps in, then I will most likely
> choose option 1 in a few months.
>
> Regards,
>
> 	Hans

Re: Future of the SAA7146 drivers

[Hans Verkuil]

Hi Stefan, Sören,

On 01/02/2023 00:56, Stefan Herdler wrote:
> Hello Hans,
> 
> I'm glad to read that at least the saa7146 driver won't be removed
> completely.
> 
> 
> On 31/01/23 09:45, Hans Verkuil wrote:
>> Hi Stefan,
>>
>> On 30/01/2023 23:19, Stefan Herdler wrote:
>>> Hello everyone.
>>>
>>> This mail is a little bit long, I'm sorry for that.
>>> But I have to describe the TV-situation in Germany roughly. Without that
>>> knowledge it is definitely not understandable why this DVB-S cards are
>>> still very useful here.
>>> Reader familiar with this crazy situation may proceed to the driver
>>> section below.
>>>
>>> I'm primary a user of this cards but have profound knowledge about the
>>> Hardware. I used to repair the cards for me and other users back then.
>>>
>>> I own Fullfeatured and Budget-cards and use them daily in my VDR-System.
>>> In Germany many channels are free-to-air in the DVB-S version only. I
>>> would like to use these cards for a few more years until DVB-S is
>>> deactivated or the HD-Versions of the channels become free-to-air.
>>> I'm not willing to pay 75 Euro a year for TV-commercials in HD and I'm
>>> not the only one with this opinion.
>>> 14 million of the 17 million satelite-tv-households in Germany watch
>>> this channels in SD-quality only (~82%)![1]
>>> In addition uses the encrypting-system a proprietary CAM extension which
>>> makes it impossible to watch this channels on a HTPC legally.
>>> This situation won't change until 2025 (by a kind of law!). What then
>>> happens is currently completely uncertain.
>>>
>>>
>>> The driver topic however is new to me, the cards where always working
>>> out of the box. I noticed the upcoming removal right before my first mail.
>>>
>>> Honestly I was a little shocked that the driver may be removed from Kernel.
>>
>> Don't worry, the saa7146 driver won't be removed. I admit that that was
>> my initial plan, but you are not the only one who contacted me to let me
>> know that the DVB functionality is still in use. I had not expected that
>> for such old hardware, but it is clear that this driver can't be removed.
>>
>>> The card may be old and not produced any more, but they are not rare and
>>> easily obtainable second hand. There are always multiple offers for
>>> reasonable prices on the common platforms.
>>> And the cards are running flawless on current mainboards with PCIe-PCI
>>> Bridge.
>>>
>>> There must be a lot of SAA7146 based cards been sold in Europe. Many
>>> brands sold them, mostly rebranded Technotrend cards.
>>> Even Hauppauge, the most important brand, sold the TT-Budged as "Nova"
>>> and the Fullfeatured as "Nexus" for years. Their own Connexant based
>>> designs came pretty late, short before the PCIe-cards.
>>>
>>> I carefully estimate, at least 50% of all PCI-DVB-cards sold in Europe
>>> where SAA7146 based.
>>> There must be still a number of users out there.
>>>
>>> The relevance of SAA7146 for PCI-DVB-cards is almost like the Bttv-Chips
>>> for analog TV a few years before. At least in Europe.
>>> And the bttv driver not deprecated despite older and using videobuf1 API!
>>
>> The underlying reason for deprecating this driver in the first place was
>> the use of the old videobuf framework for analog TV in this driver: we
>> want to get rid of that, either by removing such drivers, or converting
>> it to vb2 (we plan to do that for bttv and cx18). For the saa7146 there
>> is another option: dropping the analog TV support only.
>>
>>>
>>>
>>> SAA7146 driver
>>> ==============
>>>
>>> I've read a lot in the last days and the main issue with the SAA7146
>>> driver seems to be the missing maintainer.
>>> All other issues seem to be a result of that.
>>> Right?
>>
>> Right. I'm on record as the maintainer, but I really don't have the time
>> to do a substantial job like the vb2 conversion.
>>
>>> And the driver desperately needs someone with expertise about the cards
>>> and the driver.
>>> I've spotted a big chunk of unused code just by knowing which cards have
>>> been build and which not.
>>>
>>> Sören Moch offered to maintain the complete SAA7146 driver in the
>>> VDRportal and in this list too. This offer includes the videobuf2
>>> conversion too.
>>> On condition that the support of the fullfeatured cards stays in the
>>> kernel.
>>> I understand that. He only owns fullfeatured cards.
>>> And I am interested in keeping my fullfeatured cards operational too.
>>>
>>> I'm convinced Sören could handle the driver well and he is the only one
>>> I know who probably could do that. And he is actively offering to do the
>>> job.
>>
>> Honestly, that would be great. We really need to get rid of the old videobuf
>> framework, it is awful. I found someone to do the bttv conversion, and I plan
>> to do the cx18 conversion. So that leaves the saa7146: it's either converted
>> to vb2, or analog video support (that's the part that uses videobuf) has to
>> be removed.
>>
>> Obviously, if someone wants to do the vb2 conversion, then that would be
>> perfect. I was looking at removing analog video support, and that doesn't
>> look as easy as I thought it would be.
>>
> The SAA7146 driver suite is a kind of beast ;-).
> 
> I guess it is mainly caused by the DVB-C Budget-Cards.
> There are some having analog support too.
> 
>> I can certainly advice how to go about converting to vb2 as I've done it a
>> few times in the past. It's rather painful, mostly because it is a 'big bang'
>> change: it ends up as a single large and mostly unreviewable patch.
>>
> Indeed, I've searched for some patches and all are huge.
> I have some basic C knowledge, but no experience with kerneldrivers nor
> vb1 nor vb2. Unfortunately such a conversion would be out of scope for
> me. At least if it should be done in a reasonable time frame.
> 
> Sören wrote the conversion would't be a big deal for him and it would be
> done within a few weeks.
> 
>>>
>>>
>>> That leads to the DVB-API part for the AV7110 which should be removed.
>>>
>>> An API conversion for the AV7110 does not make sense any more. 10 years
>>> ago maybe, but not now.
>>> Working software would be broken and there will be no benefit for the
>>> user at all.
>>>
>>> Converting is however not easy and a driver specific UAPI would be
>>> necessary in any case.
>>> The ioctl "VIDEO_SELECT_SOURCE" needed and definitely missing in the
>>> V4l2-API (see ivtv driver).
>>> The OSD of the FF-Cards is more canvas like, not a framebuffer. The OSD
>>> ioctl are also needed and I haven't found anything in V4l2-API to
>>> replace them.
>>>
>>> What about putting the 3 API-files into one driver specific UAPI file?
>>> The deprecated DVB-API part could be officially removed and the
>>> maintainer of the av7110 driver would become responsible for the API.
>>> Could that be an acceptable solution for everybody?
>>> Or do the ~10Kb of possible redundancy in the header hurt so much?
>>
>> I think this can be something that can be discussed later. It's not my
>> main concern and not the reason why I originally planned to remove the
>> driver. The use of videobuf is the main problem.
>>
>> If Sören wants to become an active maintainer for this driver, then the
>> vb2 conversion would be the first step. But there is a lot more that can
>> be done, I'm sure.
>>
> Yes he wants, that is his offer to the VDR-community.
> 
> He just wants a kind of guarantee, that the driver for the fullfeatured
> cards he owns stays in the kernel.
> That is understandable for me, he would do the job voluntary without
> been payed.

Once it is converted to vb2 the driver can stay.

Note that the driver might need a bit more work: we use the v4l2-compliance
utility to test V4L2 API compliance of a driver, and after the vb2
conversion the driver should pass this test. So the compliance test might
find some other things that do not work as they should, and it would be
really good to clean that up as well. Usually the things it finds are pretty
easy to fix.

> 
> There is a long lasting controversy about the deprecated 3 DVB-API-files
> for the av7110 driver.
> Sören stated he is tired about that discussions and looking for
> permanent solution without having to rewrite the whole driver.
> 
> In this case I'm just the messenger, but I would also prefer a permanent
> solution.
> That is why I made the suggestion with the driver specific UAPI file.
> The av7110 driver is only driver using this API-part.
> And the modification is fairly easy and the impact minimal.
> 
> May that be a compromise all parties can live with?

Moving it to a public av7110.h header makes sense to me.

It's a nice-to-have in my view, and moving it to a driver-specific API
should avoid future discussions. The fact remains that as long as
people use this API we can't remove it, however much we would want to.

I think the main problem has always been that we are surprised at how
many people still use these cards. It's very similar in that respect
to the bttv driver: very old, but still in use.

The difference appears to be that the use of saa7146 cards is confined
to a specific region (esp. Germany), whereas bttv is in use worldwide.

Because of that we just miss that it is still in use.

Having an active maintainer should help with that.

Regards,

	Hans

Re: Future of the SAA7146 drivers

[Soeren Moch]

Hi Hans, Stefan, all,

On 01.02.23 10:15, Hans Verkuil wrote:
> Hi Stefan, Sören,
>
> On 01/02/2023 00:56, Stefan Herdler wrote:
>> Hello Hans,
>>
>> I'm glad to read that at least the saa7146 driver won't be removed
>> completely.
>>
>>
>> On 31/01/23 09:45, Hans Verkuil wrote:
>>> Hi Stefan,
>>>
>>> On 30/01/2023 23:19, Stefan Herdler wrote:
>>>> Hello everyone.
>>>>
>>>> This mail is a little bit long, I'm sorry for that.
>>>> But I have to describe the TV-situation in Germany roughly. Without that
>>>> knowledge it is definitely not understandable why this DVB-S cards are
>>>> still very useful here.
>>>> Reader familiar with this crazy situation may proceed to the driver
>>>> section below.
>>>>
>>>> I'm primary a user of this cards but have profound knowledge about the
>>>> Hardware. I used to repair the cards for me and other users back then.
>>>>
>>>> I own Fullfeatured and Budget-cards and use them daily in my VDR-System.
>>>> In Germany many channels are free-to-air in the DVB-S version only. I
>>>> would like to use these cards for a few more years until DVB-S is
>>>> deactivated or the HD-Versions of the channels become free-to-air.
>>>> I'm not willing to pay 75 Euro a year for TV-commercials in HD and I'm
>>>> not the only one with this opinion.
>>>> 14 million of the 17 million satelite-tv-households in Germany watch
>>>> this channels in SD-quality only (~82%)![1]
>>>> In addition uses the encrypting-system a proprietary CAM extension which
>>>> makes it impossible to watch this channels on a HTPC legally.
>>>> This situation won't change until 2025 (by a kind of law!). What then
>>>> happens is currently completely uncertain.
>>>>
>>>>
>>>> The driver topic however is new to me, the cards where always working
>>>> out of the box. I noticed the upcoming removal right before my first mail.
>>>>
>>>> Honestly I was a little shocked that the driver may be removed from Kernel.
>>> Don't worry, the saa7146 driver won't be removed. I admit that that was
>>> my initial plan, but you are not the only one who contacted me to let me
>>> know that the DVB functionality is still in use. I had not expected that
>>> for such old hardware, but it is clear that this driver can't be removed.
I'm glad to read this.
>>>> The card may be old and not produced any more, but they are not rare and
>>>> easily obtainable second hand. There are always multiple offers for
>>>> reasonable prices on the common platforms.
>>>> And the cards are running flawless on current mainboards with PCIe-PCI
>>>> Bridge.
>>>>
>>>> There must be a lot of SAA7146 based cards been sold in Europe. Many
>>>> brands sold them, mostly rebranded Technotrend cards.
>>>> Even Hauppauge, the most important brand, sold the TT-Budged as "Nova"
>>>> and the Fullfeatured as "Nexus" for years. Their own Connexant based
>>>> designs came pretty late, short before the PCIe-cards.
>>>>
>>>> I carefully estimate, at least 50% of all PCI-DVB-cards sold in Europe
>>>> where SAA7146 based.
>>>> There must be still a number of users out there.
>>>>
>>>> The relevance of SAA7146 for PCI-DVB-cards is almost like the Bttv-Chips
>>>> for analog TV a few years before. At least in Europe.
>>>> And the bttv driver not deprecated despite older and using videobuf1 API!
>>> The underlying reason for deprecating this driver in the first place was
>>> the use of the old videobuf framework for analog TV in this driver: we
>>> want to get rid of that, either by removing such drivers, or converting
>>> it to vb2 (we plan to do that for bttv and cx18). For the saa7146 there
>>> is another option: dropping the analog TV support only.
I totally agree to the vb2 conversion and would be happy to help with that.
>>>>
>>>> SAA7146 driver
>>>> ==============
>>>>
>>>> I've read a lot in the last days and the main issue with the SAA7146
>>>> driver seems to be the missing maintainer.
>>>> All other issues seem to be a result of that.
>>>> Right?
>>> Right. I'm on record as the maintainer, but I really don't have the time
>>> to do a substantial job like the vb2 conversion.
As hobbyist linux developer I also have not much time for this driver
work. Nevertheless, I want to keep the DVB full-featured cards alive and
I would spend some time on that.
>>>> And the driver desperately needs someone with expertise about the cards
>>>> and the driver.
>>>> I've spotted a big chunk of unused code just by knowing which cards have
>>>> been build and which not.
Maybe we should start to remove all the unused code. With luck there is
not much left for conversion.
>>>> Sören Moch offered to maintain the complete SAA7146 driver in the
>>>> VDRportal and in this list too. This offer includes the videobuf2
>>>> conversion too.
>>>> On condition that the support of the fullfeatured cards stays in the
>>>> kernel.
>>>> I understand that. He only owns fullfeatured cards.
>>>> And I am interested in keeping my fullfeatured cards operational too.
>>>>
>>>> I'm convinced Sören could handle the driver well and he is the only one
>>>> I know who probably could do that. And he is actively offering to do the
>>>> job.
>>> Honestly, that would be great. We really need to get rid of the old videobuf
>>> framework, it is awful. I found someone to do the bttv conversion, and I plan
>>> to do the cx18 conversion. So that leaves the saa7146: it's either converted
>>> to vb2, or analog video support (that's the part that uses videobuf) has to
>>> be removed.
>>>
>>> Obviously, if someone wants to do the vb2 conversion, then that would be
>>> perfect. I was looking at removing analog video support, and that doesn't
>>> look as easy as I thought it would be.
>>>
I only own full-featured (Nexus) cards, modified to also support a mode
of operation like budget cards. In full-featured cards there is a
possibility to re-read the decoded video output signal back, which could
be similar to how analog cards work. But I never had access to
analog/hybrid saa7146 cards, so I'm not sure I can test this mode. I
also don't know anybody with such card who could help testing.
I personally do not care much about analog card support in the driver,
but will at least check which part of analog functionality is used in
full-featured cards. Maybe the support for analog/hybrid cards and some
test coverage comes for free with full support for full-featured cards.
>> The SAA7146 driver suite is a kind of beast ;-).
>>
>> I guess it is mainly caused by the DVB-C Budget-Cards.
>> There are some having analog support too.
>>
>>> I can certainly advice how to go about converting to vb2 as I've done it a
>>> few times in the past. It's rather painful, mostly because it is a 'big bang'
>>> change: it ends up as a single large and mostly unreviewable patch.
OK, thanks.
>> Indeed, I've searched for some patches and all are huge.
>> I have some basic C knowledge, but no experience with kerneldrivers nor
>> vb1 nor vb2. Unfortunately such a conversion would be out of scope for
>> me. At least if it should be done in a reasonable time frame.
>>
>> Sören wrote the conversion would't be a big deal for him and it would be
>> done within a few weeks.
>>
>>>>
>>>> That leads to the DVB-API part for the AV7110 which should be removed.
>>>>
>>>> An API conversion for the AV7110 does not make sense any more. 10 years
>>>> ago maybe, but not now.
>>>> Working software would be broken and there will be no benefit for the
>>>> user at all.
>>>>
>>>> Converting is however not easy and a driver specific UAPI would be
>>>> necessary in any case.
>>>> The ioctl "VIDEO_SELECT_SOURCE" needed and definitely missing in the
>>>> V4l2-API (see ivtv driver).
>>>> The OSD of the FF-Cards is more canvas like, not a framebuffer. The OSD
>>>> ioctl are also needed and I haven't found anything in V4l2-API to
>>>> replace them.
>>>>
>>>> What about putting the 3 API-files into one driver specific UAPI file?
>>>> The deprecated DVB-API part could be officially removed and the
>>>> maintainer of the av7110 driver would become responsible for the API.
>>>> Could that be an acceptable solution for everybody?
>>>> Or do the ~10Kb of possible redundancy in the header hurt so much?
>>> I think this can be something that can be discussed later. It's not my
>>> main concern and not the reason why I originally planned to remove the
>>> driver. The use of videobuf is the main problem.
As already explained, my main concern are full-featured cards. With all
the required conversions for these cards done, also budget cards and
maybe analog/hybrid cards can be supported. If (full) analog support is
not testable, I also would take care of removing the remaining old
videobuf code.

But, all this only makes sense to me when full-featured cards and the
output part of the DVB API remain supported in mainline.
>>> If Sören wants to become an active maintainer for this driver, then the
>>> vb2 conversion would be the first step. But there is a lot more that can
>>> be done, I'm sure.
>>>
>> Yes he wants, that is his offer to the VDR-community.
For almost 10 years I maintain the saa716x driver [1] for
high-definition full-featured cards and related budget cards. The HD-FF
cards are the successor of the saa7146 based full-featured cards, with
the same API, very similar driver structure, and same application area
(mainly VDR). It would make much sense to maintain both drivers together
in mainline. That would be a big win for everyone, users, distributors,
and developers. But yes, first step would be to get the saa7146 driver
out of staging/deprecated.
>>
>> He just wants a kind of guarantee, that the driver for the fullfeatured
>> cards he owns stays in the kernel.
>> That is understandable for me, he would do the job voluntary without
>> been payed.
> Once it is converted to vb2 the driver can stay.
So, Hans, you will also move ttpci, av7110, and the DVB output API
documentation back from staging, when all the old videobuf code is
removed? And give up the strange attitude of "Cleanup patches for the
drivers here won't be accepted." for av7110 [2]?
> Note that the driver might need a bit more work: we use the v4l2-compliance
> utility to test V4L2 API compliance of a driver, and after the vb2
> conversion the driver should pass this test. So the compliance test might
> find some other things that do not work as they should, and it would be
> really good to clean that up as well. Usually the things it finds are pretty
> easy to fix.
I totally agree that all available compliance tests should pass.
Most parts of the driver are implementing the DVB API, though. Probably
only for the analog parts we use v4l2. Especially for full-featured
cards the read-back of the analog output signal is more like a debug
mode (for DVB OSD applications, VDR skin plugins) and probably not
working in isolation like a fully compliant v4l2 input device. But I'm
happy to make this as compliant as possible.
>> There is a long lasting controversy about the deprecated 3 DVB-API-files
>> for the av7110 driver.
>> Sören stated he is tired about that discussions and looking for
>> permanent solution without having to rewrite the whole driver.
>>
>> In this case I'm just the messenger, but I would also prefer a permanent
>> solution.
>> That is why I made the suggestion with the driver specific UAPI file.
>> The av7110 driver is only driver using this API-part.
>> And the modification is fairly easy and the impact minimal.
>>
>> May that be a compromise all parties can live with?
> Moving it to a public av7110.h header makes sense to me.
>
> It's a nice-to-have in my view, and moving it to a driver-specific API
> should avoid future discussions.
For me this looks it little bit different. I would like to keep all
parts of the DVB API separate, because at least 2 different drivers
(saa7146/av7110 and saa716x) are using these APIs. And again, I would be
more than happy to get saa716x upstream, so that both DVB output drivers
are in mainline. For HD full-featured cards there are most likely even
more users than for SD-FF cards.
> The fact remains that as long as
> people use this API we can't remove it, however much we would want to.
> I think the main problem has always been that we are surprised at how
> many people still use these cards. It's very similar in that respect
> to the bttv driver: very old, but still in use.
>
> The difference appears to be that the use of saa7146 cards is confined
> to a specific region (esp. Germany), whereas bttv is in use worldwide.
>
> Because of that we just miss that it is still in use.
>
> Having an active maintainer should help with that.
I already offered several times to maintain one or preferably both
drivers in linux-media. Thanks for providing such offer now. I'm really
glad to see linux-media/DVB starting to work together with the community
like any other linux subsystem.

Regards,
Soeren

[1] https://github.com/s-moch/linux-saa716x
[2]
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/staging/media/deprecated/saa7146/av7110/TODO?h=v6.2-rc6

Re: Future of the SAA7146 drivers

[Hans Verkuil]

Hi Sören,

On 01/02/2023 12:35, Soeren Moch wrote:

<snip>

>>>> Obviously, if someone wants to do the vb2 conversion, then that would be
>>>> perfect. I was looking at removing analog video support, and that doesn't
>>>> look as easy as I thought it would be.
>>>>
> I only own full-featured (Nexus) cards, modified to also support a mode
> of operation like budget cards. In full-featured cards there is a
> possibility to re-read the decoded video output signal back, which could
> be similar to how analog cards work. But I never had access to
> analog/hybrid saa7146 cards, so I'm not sure I can test this mode. I
> also don't know anybody with such card who could help testing.
> I personally do not care much about analog card support in the driver,
> but will at least check which part of analog functionality is used in
> full-featured cards. Maybe the support for analog/hybrid cards and some
> test coverage comes for free with full support for full-featured cards.

It's the analog video streaming that uses vb2, so being able to test that
is critical.

So I decided to do this differently:

1) I'll revert the move of saa7146 to staging, it will go back to
   mainline. av7110 stays in staging for now (that might change, I
   just don't want to make more changes than strictly necessary).

2) I will do the vb2 conversion. I have the analog video hardware,
   so I can test this.

I didn't want to spend time on that originally, but since these drivers
are still in use, it is probably best if I bite the bullet and just do it.

I'm now almost done with the vb2 conversion of cx18, and it was about
2 days work, which isn't that bad. I'll try to get this saa7146 vb2
conversion done this month.

The PR reverting this has just been posted:

https://patchwork.linuxtv.org/project/linux-media/patch/5902a4f2-da31-816c-f3cf-020340dbaddf@xs4all.nl/

Regards,

	Hans

Re: Future of the SAA7146 drivers

[Soeren Moch]

On 01.02.23 14:51, Hans Verkuil wrote:
> Hi Sören,
>
> On 01/02/2023 12:35, Soeren Moch wrote:
>
> <snip>
>
>>>>> Obviously, if someone wants to do the vb2 conversion, then that would be
>>>>> perfect. I was looking at removing analog video support, and that doesn't
>>>>> look as easy as I thought it would be.
>>>>>
>> I only own full-featured (Nexus) cards, modified to also support a mode
>> of operation like budget cards. In full-featured cards there is a
>> possibility to re-read the decoded video output signal back, which could
>> be similar to how analog cards work. But I never had access to
>> analog/hybrid saa7146 cards, so I'm not sure I can test this mode. I
>> also don't know anybody with such card who could help testing.
>> I personally do not care much about analog card support in the driver,
>> but will at least check which part of analog functionality is used in
>> full-featured cards. Maybe the support for analog/hybrid cards and some
>> test coverage comes for free with full support for full-featured cards.
> It's the analog video streaming that uses vb2, so being able to test that
> is critical.
>
> So I decided to do this differently:
>
> 1) I'll revert the move of saa7146 to staging, it will go back to
>     mainline. av7110 stays in staging for now (that might change, I
>     just don't want to make more changes than strictly necessary).
Hm, you wrote earlier, all this staging is about vb2 conversion.
There is no videobuf in av7110. Why this part needs to stay in staging?

How can I help here?
>
> 2) I will do the vb2 conversion. I have the analog video hardware,
>     so I can test this.
Great! Thanks for this!

Regards,
Soeren
>
> I didn't want to spend time on that originally, but since these drivers
> are still in use, it is probably best if I bite the bullet and just do it.
>
> I'm now almost done with the vb2 conversion of cx18, and it was about
> 2 days work, which isn't that bad. I'll try to get this saa7146 vb2
> conversion done this month.
>
> The PR reverting this has just been posted:
>
> https://patchwork.linuxtv.org/project/linux-media/patch/5902a4f2-da31-816c-f3cf-020340dbaddf@xs4all.nl/
>
> Regards,
>
> 	Hans

Re: Future of the SAA7146 drivers

[Hans Verkuil]

On 01/02/2023 16:20, Soeren Moch wrote:
> 
> 
> On 01.02.23 14:51, Hans Verkuil wrote:
>> Hi Sören,
>>
>> On 01/02/2023 12:35, Soeren Moch wrote:
>>
>> <snip>
>>
>>>>>> Obviously, if someone wants to do the vb2 conversion, then that would be
>>>>>> perfect. I was looking at removing analog video support, and that doesn't
>>>>>> look as easy as I thought it would be.
>>>>>>
>>> I only own full-featured (Nexus) cards, modified to also support a mode
>>> of operation like budget cards. In full-featured cards there is a
>>> possibility to re-read the decoded video output signal back, which could
>>> be similar to how analog cards work. But I never had access to
>>> analog/hybrid saa7146 cards, so I'm not sure I can test this mode. I
>>> also don't know anybody with such card who could help testing.
>>> I personally do not care much about analog card support in the driver,
>>> but will at least check which part of analog functionality is used in
>>> full-featured cards. Maybe the support for analog/hybrid cards and some
>>> test coverage comes for free with full support for full-featured cards.
>> It's the analog video streaming that uses vb2, so being able to test that
>> is critical.
>>
>> So I decided to do this differently:
>>
>> 1) I'll revert the move of saa7146 to staging, it will go back to
>>     mainline. av7110 stays in staging for now (that might change, I
>>     just don't want to make more changes than strictly necessary).
> Hm, you wrote earlier, all this staging is about vb2 conversion.
> There is no videobuf in av7110. Why this part needs to stay in staging?
> 
> How can I help here?

Right, there are two different issues here: av7110 in staging (and I wasn't
aware that these boards have no analog support) and the removal of the old videobuf.

I have not really been involved in the move of av7110 to staging, but
given the fact that it is still used, I think it would make sense to just
make the 'problematic' part of the API an av7110 driver-specific API, and
then it can be moved back.

But this is something where Mauro (CC-ed) needs to give his thoughts as well.

In any case, this is something to do after the vb2 conversion.

Regards,

	Hans

>>
>> 2) I will do the vb2 conversion. I have the analog video hardware,
>>     so I can test this.
> Great! Thanks for this!
> 
> Regards,
> Soeren
>>
>> I didn't want to spend time on that originally, but since these drivers
>> are still in use, it is probably best if I bite the bullet and just do it.
>>
>> I'm now almost done with the vb2 conversion of cx18, and it was about
>> 2 days work, which isn't that bad. I'll try to get this saa7146 vb2
>> conversion done this month.
>>
>> The PR reverting this has just been posted:
>>
>> https://patchwork.linuxtv.org/project/linux-media/patch/5902a4f2-da31-816c-f3cf-020340dbaddf@xs4all.nl/
>>
>> Regards,
>>
>>     Hans
> 

Re: Future of the SAA7146 drivers

[Stefan Herdler]

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

Hi Hans, Sören,

On 01/02/23, 10:15 Hans Verkuil wrote:

[...]
>
> Once it is converted to vb2 the driver can stay.
>
> Note that the driver might need a bit more work: we use the v4l2-compliance
> utility to test V4L2 API compliance of a driver, and after the vb2
> conversion the driver should pass this test. So the compliance test might
> find some other things that do not work as they should, and it would be
> really good to clean that up as well. Usually the things it finds are pretty
> easy to fix.
>
For the records, as long I remember it:
The "Buget Patch" driver is superfluous and can be removed.
This driver is for an experimental hardware-mod which never really
worked. No such hardware was ever produced.
I was really surprised to see it.
>>
>> There is a long lasting controversy about the deprecated 3 DVB-API-files
>> for the av7110 driver.
>> Sören stated he is tired about that discussions and looking for
>> permanent solution without having to rewrite the whole driver.
>>
>> In this case I'm just the messenger, but I would also prefer a permanent
>> solution.
>> That is why I made the suggestion with the driver specific UAPI file.
>> The av7110 driver is only driver using this API-part.
>> And the modification is fairly easy and the impact minimal.
>>
>> May that be a compromise all parties can live with?
>
> Moving it to a public av7110.h header makes sense to me.

I've done this already.
Primary for my self to see if and how it may work.
I'll attach the patch, maybe it is helpful.

Theoretically there shouldn't be a difference whether the headers are in
1 or 3 files.
Unused symbols should be removed by the compiler while optimization the
result should be identical.
I was just curious and decided to try it.

Unfortunately I couldn't test it yet. But hopefully next weekend.
There seems to be an issue with new kernel and my Nvidia graphics-card.
But the kernel builds and boots into text console.

>
> It's a nice-to-have in my view, and moving it to a driver-specific API
> should avoid future discussions. The fact remains that as long as
> people use this API we can't remove it, however much we would want to.
>
> I think the main problem has always been that we are surprised at how
> many people still use these cards. It's very similar in that respect
> to the bttv driver: very old, but still in use.

I own one too.
Such cards can still be handy for digitizing family videos and stuff.

>
> The difference appears to be that the use of saa7146 cards is confined
> to a specific region (esp. Germany), whereas bttv is in use worldwide.

Until recently I wasn't aware that there are no saa7146 cards for ATSC
nor ISDB.

>
> Because of that we just miss that it is still in use.
>
> Having an active maintainer should help with that.
>
> Regards,
>
> 	Hans





On 01/02/23, 14:51 Hans Verkuil wrote:

[...]
>
> It's the analog video streaming that uses vb2, so being able to test that
> is critical.
>
The DVB data always uses one specific of the 2 video ports. The other
one is not able to handle DVB-data.
It is always the path through BRS and FIFO3, if I remember correctly.

The analog video data has to use the remaining video port and FIFO1 if a
DVB-Tuner is present.
Input data format is YUV and output RGB. At least at the FF cards.

(I may have confused the Ports, but in general it should be correct.)

I don't have a combined budget-card and don't know how the driver
handles analog inputs. But because of this hardware limitation there
shouldn't be much difference between the decoded video of the FF and the
video-input of a combined DVB-budget.
Maybe testing on a FF is sufficient?


> So I decided to do this differently:
>
> 1) I'll revert the move of saa7146 to staging, it will go back to
>     mainline. av7110 stays in staging for now (that might change, I
>     just don't want to make more changes than strictly necessary).
>
> 2) I will do the vb2 conversion. I have the analog video hardware,
>     so I can test this.
>
> I didn't want to spend time on that originally, but since these drivers
> are still in use, it is probably best if I bite the bullet and just do it.
>
> I'm now almost done with the vb2 conversion of cx18, and it was about
> 2 days work, which isn't that bad. I'll try to get this saa7146 vb2
> conversion done this month.
>
> The PR reverting this has just been posted:
>
> https://patchwork.linuxtv.org/project/linux-media/patch/5902a4f2-da31-816c-f3cf-020340dbaddf@xs4all.nl/
>

Great news, thanks!

Regards

Stefan

> Regards,
>
> 	Hans

[-- Attachment #2: av7110api.diff --]
[-- Type: text/x-patch, Size: 33334 bytes --]

--- ./linux-source-6.1-original/drivers/staging/media/deprecated/saa7146/av7110/av7110.h	2023-01-18 11:58:34.000000000 +0100
+++ ./linux-source-6.1-incmodi/drivers/staging/media/deprecated/saa7146/av7110/av7110.h	2023-01-28 22:07:25.460618320 +0100
@@ -9,11 +9,9 @@
 #include <linux/input.h>
 #include <linux/time.h>
 
-#include <linux/dvb/video.h>
-#include <linux/dvb/audio.h>
+#include <linux/av7110.h>
 #include <linux/dvb/dmx.h>
 #include <linux/dvb/ca.h>
-#include <linux/dvb/osd.h>
 #include <linux/dvb/net.h>
 #include <linux/mutex.h>
 
--- ./linux-source-6.1-original/include/uapi/linux/dvb/audio.h	2023-01-18 11:58:34.000000000 +0100
+++ ./linux-source-6.1-incmodi/include/uapi/linux/dvb/audio.h	1970-01-01 01:00:00.000000000 +0100
@@ -1,101 +0,0 @@
-/* SPDX-License-Identifier: LGPL-2.1+ WITH Linux-syscall-note */
-/*
- * audio.h - DEPRECATED MPEG-TS audio decoder API
- *
- * NOTE: should not be used on future drivers
- *
- * Copyright (C) 2000 Ralph  Metzler <ralph@convergence.de>
- *                  & Marcus Metzler <marcus@convergence.de>
- *                    for convergence integrated media GmbH
- *
- * This program is free software; you can redistribute it and/or
- * modify it under the terms of the GNU General Lesser Public License
- * as published by the Free Software Foundation; either version 2.1
- * of the License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
- *
- */
-
-#ifndef _DVBAUDIO_H_
-#define _DVBAUDIO_H_
-
-#include <linux/types.h>
-
-typedef enum {
-	AUDIO_SOURCE_DEMUX, /* Select the demux as the main source */
-	AUDIO_SOURCE_MEMORY /* Select internal memory as the main source */
-} audio_stream_source_t;
-
-
-typedef enum {
-	AUDIO_STOPPED,      /* Device is stopped */
-	AUDIO_PLAYING,      /* Device is currently playing */
-	AUDIO_PAUSED        /* Device is paused */
-} audio_play_state_t;
-
-
-typedef enum {
-	AUDIO_STEREO,
-	AUDIO_MONO_LEFT,
-	AUDIO_MONO_RIGHT,
-	AUDIO_MONO,
-	AUDIO_STEREO_SWAPPED
-} audio_channel_select_t;
-
-
-typedef struct audio_mixer {
-	unsigned int volume_left;
-	unsigned int volume_right;
-  /* what else do we need? bass, pass-through, ... */
-} audio_mixer_t;
-
-
-typedef struct audio_status {
-	int                    AV_sync_state;  /* sync audio and video? */
-	int                    mute_state;     /* audio is muted */
-	audio_play_state_t     play_state;     /* current playback state */
-	audio_stream_source_t  stream_source;  /* current stream source */
-	audio_channel_select_t channel_select; /* currently selected channel */
-	int                    bypass_mode;    /* pass on audio data to */
-	audio_mixer_t	       mixer_state;    /* current mixer state */
-} audio_status_t;                              /* separate decoder hardware */
-
-
-/* for GET_CAPABILITIES and SET_FORMAT, the latter should only set one bit */
-#define AUDIO_CAP_DTS    1
-#define AUDIO_CAP_LPCM   2
-#define AUDIO_CAP_MP1    4
-#define AUDIO_CAP_MP2    8
-#define AUDIO_CAP_MP3   16
-#define AUDIO_CAP_AAC   32
-#define AUDIO_CAP_OGG   64
-#define AUDIO_CAP_SDDS 128
-#define AUDIO_CAP_AC3  256
-
-#define AUDIO_STOP                 _IO('o', 1)
-#define AUDIO_PLAY                 _IO('o', 2)
-#define AUDIO_PAUSE                _IO('o', 3)
-#define AUDIO_CONTINUE             _IO('o', 4)
-#define AUDIO_SELECT_SOURCE        _IO('o', 5)
-#define AUDIO_SET_MUTE             _IO('o', 6)
-#define AUDIO_SET_AV_SYNC          _IO('o', 7)
-#define AUDIO_SET_BYPASS_MODE      _IO('o', 8)
-#define AUDIO_CHANNEL_SELECT       _IO('o', 9)
-#define AUDIO_GET_STATUS           _IOR('o', 10, audio_status_t)
-
-#define AUDIO_GET_CAPABILITIES     _IOR('o', 11, unsigned int)
-#define AUDIO_CLEAR_BUFFER         _IO('o',  12)
-#define AUDIO_SET_ID               _IO('o', 13)
-#define AUDIO_SET_MIXER            _IOW('o', 14, audio_mixer_t)
-#define AUDIO_SET_STREAMTYPE       _IO('o', 15)
-#define AUDIO_BILINGUAL_CHANNEL_SELECT _IO('o', 20)
-
-#endif /* _DVBAUDIO_H_ */
--- ./linux-source-6.1-original/include/uapi/linux/dvb/osd.h	2023-01-18 11:58:34.000000000 +0100
+++ ./linux-source-6.1-incmodi/include/uapi/linux/dvb/osd.h	1970-01-01 01:00:00.000000000 +0100
@@ -1,181 +0,0 @@
-/* SPDX-License-Identifier: LGPL-2.1+ WITH Linux-syscall-note */
-/*
- * osd.h - DEPRECATED On Screen Display API
- *
- * NOTE: should not be used on future drivers
- *
- * Copyright (C) 2001 Ralph  Metzler <ralph@convergence.de>
- *                  & Marcus Metzler <marcus@convergence.de>
- *                    for convergence integrated media GmbH
- *
- * This program is free software; you can redistribute it and/or
- * modify it under the terms of the GNU General Lesser Public License
- * as published by the Free Software Foundation; either version 2.1
- * of the License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
- *
- */
-
-#ifndef _DVBOSD_H_
-#define _DVBOSD_H_
-
-#include <linux/compiler.h>
-
-typedef enum {
-	/* All functions return -2 on "not open" */
-	OSD_Close = 1,	/* () */
-	/*
-	 * Disables OSD and releases the buffers
-	 * returns 0 on success
-	 */
-	OSD_Open,	/* (x0,y0,x1,y1,BitPerPixel[2/4/8](color&0x0F),mix[0..15](color&0xF0)) */
-	/*
-	 * Opens OSD with this size and bit depth
-	 * returns 0 on success, -1 on DRAM allocation error, -2 on "already open"
-	 */
-	OSD_Show,	/* () */
-	/*
-	 * enables OSD mode
-	 * returns 0 on success
-	 */
-	OSD_Hide,	/* () */
-	/*
-	 * disables OSD mode
-	 * returns 0 on success
-	 */
-	OSD_Clear,	/* () */
-	/*
-	 * Sets all pixel to color 0
-	 * returns 0 on success
-	 */
-	OSD_Fill,	/* (color) */
-	/*
-	 * Sets all pixel to color <col>
-	 * returns 0 on success
-	 */
-	OSD_SetColor,	/* (color,R{x0},G{y0},B{x1},opacity{y1}) */
-	/*
-	 * set palette entry <num> to <r,g,b>, <mix> and <trans> apply
-	 * R,G,B: 0..255
-	 * R=Red, G=Green, B=Blue
-	 * opacity=0:      pixel opacity 0% (only video pixel shows)
-	 * opacity=1..254: pixel opacity as specified in header
-	 * opacity=255:    pixel opacity 100% (only OSD pixel shows)
-	 * returns 0 on success, -1 on error
-	 */
-	OSD_SetPalette,	/* (firstcolor{color},lastcolor{x0},data) */
-	/*
-	 * Set a number of entries in the palette
-	 * sets the entries "firstcolor" through "lastcolor" from the array "data"
-	 * data has 4 byte for each color:
-	 * R,G,B, and a opacity value: 0->transparent, 1..254->mix, 255->pixel
-	 */
-	OSD_SetTrans,	/* (transparency{color}) */
-	/*
-	 * Sets transparency of mixed pixel (0..15)
-	 * returns 0 on success
-	 */
-	OSD_SetPixel,	/* (x0,y0,color) */
-	/*
-	 * sets pixel <x>,<y> to color number <col>
-	 * returns 0 on success, -1 on error
-	 */
-	OSD_GetPixel,	/* (x0,y0) */
-	/* returns color number of pixel <x>,<y>,  or -1 */
-	OSD_SetRow,	/* (x0,y0,x1,data) */
-	/*
-	 * fills pixels x0,y through  x1,y with the content of data[]
-	 * returns 0 on success, -1 on clipping all pixel (no pixel drawn)
-	 */
-	OSD_SetBlock,	/* (x0,y0,x1,y1,increment{color},data) */
-	/*
-	 * fills pixels x0,y0 through  x1,y1 with the content of data[]
-	 * inc contains the width of one line in the data block,
-	 * inc<=0 uses blockwidth as linewidth
-	 * returns 0 on success, -1 on clipping all pixel
-	 */
-	OSD_FillRow,	/* (x0,y0,x1,color) */
-	/*
-	 * fills pixels x0,y through  x1,y with the color <col>
-	 * returns 0 on success, -1 on clipping all pixel
-	 */
-	OSD_FillBlock,	/* (x0,y0,x1,y1,color) */
-	/*
-	 * fills pixels x0,y0 through  x1,y1 with the color <col>
-	 * returns 0 on success, -1 on clipping all pixel
-	 */
-	OSD_Line,	/* (x0,y0,x1,y1,color) */
-	/*
-	 * draw a line from x0,y0 to x1,y1 with the color <col>
-	 * returns 0 on success
-	 */
-	OSD_Query,	/* (x0,y0,x1,y1,xasp{color}}), yasp=11 */
-	/*
-	 * fills parameters with the picture dimensions and the pixel aspect ratio
-	 * returns 0 on success
-	 */
-	OSD_Test,       /* () */
-	/*
-	 * draws a test picture. for debugging purposes only
-	 * returns 0 on success
-	 * TODO: remove "test" in final version
-	 */
-	OSD_Text,	/* (x0,y0,size,color,text) */
-	OSD_SetWindow,	/* (x0) set window with number 0<x0<8 as current */
-	OSD_MoveWindow,	/* move current window to (x0, y0) */
-	OSD_OpenRaw,	/* Open other types of OSD windows */
-} OSD_Command;
-
-typedef struct osd_cmd_s {
-	OSD_Command cmd;
-	int x0;
-	int y0;
-	int x1;
-	int y1;
-	int color;
-	void __user *data;
-} osd_cmd_t;
-
-/* OSD_OpenRaw: set 'color' to desired window type */
-typedef enum {
-	OSD_BITMAP1,           /* 1 bit bitmap */
-	OSD_BITMAP2,           /* 2 bit bitmap */
-	OSD_BITMAP4,           /* 4 bit bitmap */
-	OSD_BITMAP8,           /* 8 bit bitmap */
-	OSD_BITMAP1HR,         /* 1 Bit bitmap half resolution */
-	OSD_BITMAP2HR,         /* 2 bit bitmap half resolution */
-	OSD_BITMAP4HR,         /* 4 bit bitmap half resolution */
-	OSD_BITMAP8HR,         /* 8 bit bitmap half resolution */
-	OSD_YCRCB422,          /* 4:2:2 YCRCB Graphic Display */
-	OSD_YCRCB444,          /* 4:4:4 YCRCB Graphic Display */
-	OSD_YCRCB444HR,        /* 4:4:4 YCRCB graphic half resolution */
-	OSD_VIDEOTSIZE,        /* True Size Normal MPEG Video Display */
-	OSD_VIDEOHSIZE,        /* MPEG Video Display Half Resolution */
-	OSD_VIDEOQSIZE,        /* MPEG Video Display Quarter Resolution */
-	OSD_VIDEODSIZE,        /* MPEG Video Display Double Resolution */
-	OSD_VIDEOTHSIZE,       /* True Size MPEG Video Display Half Resolution */
-	OSD_VIDEOTQSIZE,       /* True Size MPEG Video Display Quarter Resolution*/
-	OSD_VIDEOTDSIZE,       /* True Size MPEG Video Display Double Resolution */
-	OSD_VIDEONSIZE,        /* Full Size MPEG Video Display */
-	OSD_CURSOR             /* Cursor */
-} osd_raw_window_t;
-
-typedef struct osd_cap_s {
-	int  cmd;
-#define OSD_CAP_MEMSIZE         1  /* memory size */
-	long val;
-} osd_cap_t;
-
-
-#define OSD_SEND_CMD            _IOW('o', 160, osd_cmd_t)
-#define OSD_GET_CAPABILITY      _IOR('o', 161, osd_cap_t)
-
-#endif
--- ./linux-source-6.1-original/include/uapi/linux/dvb/video.h	2023-01-18 11:58:34.000000000 +0100
+++ ./linux-source-6.1-incmodi/include/uapi/linux/dvb/video.h	1970-01-01 01:00:00.000000000 +0100
@@ -1,220 +0,0 @@
-/* SPDX-License-Identifier: LGPL-2.1+ WITH Linux-syscall-note */
-/*
- * video.h - DEPRECATED MPEG-TS video decoder API
- *
- * NOTE: should not be used on future drivers
- *
- * Copyright (C) 2000 Marcus Metzler <marcus@convergence.de>
- *                  & Ralph  Metzler <ralph@convergence.de>
- *                    for convergence integrated media GmbH
- *
- * This program is free software; you can redistribute it and/or
- * modify it under the terms of the GNU Lesser General Public License
- * as published by the Free Software Foundation; either version 2.1
- * of the License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
- *
- */
-
-#ifndef _UAPI_DVBVIDEO_H_
-#define _UAPI_DVBVIDEO_H_
-
-#include <linux/types.h>
-#ifndef __KERNEL__
-#include <time.h>
-#endif
-
-typedef enum {
-	VIDEO_FORMAT_4_3,     /* Select 4:3 format */
-	VIDEO_FORMAT_16_9,    /* Select 16:9 format. */
-	VIDEO_FORMAT_221_1    /* 2.21:1 */
-} video_format_t;
-
-
-typedef enum {
-	VIDEO_PAN_SCAN,       /* use pan and scan format */
-	VIDEO_LETTER_BOX,     /* use letterbox format */
-	VIDEO_CENTER_CUT_OUT  /* use center cut out format */
-} video_displayformat_t;
-
-typedef struct {
-	int w;
-	int h;
-	video_format_t aspect_ratio;
-} video_size_t;
-
-typedef enum {
-	VIDEO_SOURCE_DEMUX, /* Select the demux as the main source */
-	VIDEO_SOURCE_MEMORY /* If this source is selected, the stream
-			       comes from the user through the write
-			       system call */
-} video_stream_source_t;
-
-
-typedef enum {
-	VIDEO_STOPPED, /* Video is stopped */
-	VIDEO_PLAYING, /* Video is currently playing */
-	VIDEO_FREEZED  /* Video is freezed */
-} video_play_state_t;
-
-
-/* Decoder commands */
-#define VIDEO_CMD_PLAY        (0)
-#define VIDEO_CMD_STOP        (1)
-#define VIDEO_CMD_FREEZE      (2)
-#define VIDEO_CMD_CONTINUE    (3)
-
-/* Flags for VIDEO_CMD_FREEZE */
-#define VIDEO_CMD_FREEZE_TO_BLACK	(1 << 0)
-
-/* Flags for VIDEO_CMD_STOP */
-#define VIDEO_CMD_STOP_TO_BLACK		(1 << 0)
-#define VIDEO_CMD_STOP_IMMEDIATELY	(1 << 1)
-
-/* Play input formats: */
-/* The decoder has no special format requirements */
-#define VIDEO_PLAY_FMT_NONE         (0)
-/* The decoder requires full GOPs */
-#define VIDEO_PLAY_FMT_GOP          (1)
-
-/* The structure must be zeroed before use by the application
-   This ensures it can be extended safely in the future. */
-struct video_command {
-	__u32 cmd;
-	__u32 flags;
-	union {
-		struct {
-			__u64 pts;
-		} stop;
-
-		struct {
-			/* 0 or 1000 specifies normal speed,
-			   1 specifies forward single stepping,
-			   -1 specifies backward single stepping,
-			   >1: playback at speed/1000 of the normal speed,
-			   <-1: reverse playback at (-speed/1000) of the normal speed. */
-			__s32 speed;
-			__u32 format;
-		} play;
-
-		struct {
-			__u32 data[16];
-		} raw;
-	};
-};
-
-/* FIELD_UNKNOWN can be used if the hardware does not know whether
-   the Vsync is for an odd, even or progressive (i.e. non-interlaced)
-   field. */
-#define VIDEO_VSYNC_FIELD_UNKNOWN	(0)
-#define VIDEO_VSYNC_FIELD_ODD		(1)
-#define VIDEO_VSYNC_FIELD_EVEN		(2)
-#define VIDEO_VSYNC_FIELD_PROGRESSIVE	(3)
-
-struct video_event {
-	__s32 type;
-#define VIDEO_EVENT_SIZE_CHANGED	1
-#define VIDEO_EVENT_FRAME_RATE_CHANGED	2
-#define VIDEO_EVENT_DECODER_STOPPED	3
-#define VIDEO_EVENT_VSYNC		4
-	/* unused, make sure to use atomic time for y2038 if it ever gets used */
-	long timestamp;
-	union {
-		video_size_t size;
-		unsigned int frame_rate;	/* in frames per 1000sec */
-		unsigned char vsync_field;	/* unknown/odd/even/progressive */
-	} u;
-};
-
-
-struct video_status {
-	int                   video_blank;   /* blank video on freeze? */
-	video_play_state_t    play_state;    /* current state of playback */
-	video_stream_source_t stream_source; /* current source (demux/memory) */
-	video_format_t        video_format;  /* current aspect ratio of stream*/
-	video_displayformat_t display_format;/* selected cropping mode */
-};
-
-
-struct video_still_picture {
-	char __user *iFrame;        /* pointer to a single iframe in memory */
-	__s32 size;
-};
-
-
-typedef __u16 video_attributes_t;
-/*   bits: descr. */
-/*   15-14 Video compression mode (0=MPEG-1, 1=MPEG-2) */
-/*   13-12 TV system (0=525/60, 1=625/50) */
-/*   11-10 Aspect ratio (0=4:3, 3=16:9) */
-/*    9- 8 permitted display mode on 4:3 monitor (0=both, 1=only pan-sca */
-/*    7    line 21-1 data present in GOP (1=yes, 0=no) */
-/*    6    line 21-2 data present in GOP (1=yes, 0=no) */
-/*    5- 3 source resolution (0=720x480/576, 1=704x480/576, 2=352x480/57 */
-/*    2    source letterboxed (1=yes, 0=no) */
-/*    0    film/camera mode (0=
- *camera, 1=film (625/50 only)) */
-
-
-/* bit definitions for capabilities: */
-/* can the hardware decode MPEG1 and/or MPEG2? */
-#define VIDEO_CAP_MPEG1   1
-#define VIDEO_CAP_MPEG2   2
-/* can you send a system and/or program stream to video device?
-   (you still have to open the video and the audio device but only
-    send the stream to the video device) */
-#define VIDEO_CAP_SYS     4
-#define VIDEO_CAP_PROG    8
-/* can the driver also handle SPU, NAVI and CSS encoded data?
-   (CSS API is not present yet) */
-#define VIDEO_CAP_SPU    16
-#define VIDEO_CAP_NAVI   32
-#define VIDEO_CAP_CSS    64
-
-
-#define VIDEO_STOP                 _IO('o', 21)
-#define VIDEO_PLAY                 _IO('o', 22)
-#define VIDEO_FREEZE               _IO('o', 23)
-#define VIDEO_CONTINUE             _IO('o', 24)
-#define VIDEO_SELECT_SOURCE        _IO('o', 25)
-#define VIDEO_SET_BLANK            _IO('o', 26)
-#define VIDEO_GET_STATUS           _IOR('o', 27, struct video_status)
-#define VIDEO_GET_EVENT            _IOR('o', 28, struct video_event)
-#define VIDEO_SET_DISPLAY_FORMAT   _IO('o', 29)
-#define VIDEO_STILLPICTURE         _IOW('o', 30, struct video_still_picture)
-#define VIDEO_FAST_FORWARD         _IO('o', 31)
-#define VIDEO_SLOWMOTION           _IO('o', 32)
-#define VIDEO_GET_CAPABILITIES     _IOR('o', 33, unsigned int)
-#define VIDEO_CLEAR_BUFFER         _IO('o',  34)
-#define VIDEO_SET_STREAMTYPE       _IO('o', 36)
-#define VIDEO_SET_FORMAT           _IO('o', 37)
-#define VIDEO_GET_SIZE             _IOR('o', 55, video_size_t)
-
-/**
- * VIDEO_GET_PTS
- *
- * Read the 33 bit presentation time stamp as defined
- * in ITU T-REC-H.222.0 / ISO/IEC 13818-1.
- *
- * The PTS should belong to the currently played
- * frame if possible, but may also be a value close to it
- * like the PTS of the last decoded frame or the last PTS
- * extracted by the PES parser.
- */
-#define VIDEO_GET_PTS              _IOR('o', 57, __u64)
-
-/* Read the number of displayed frames since the decoder was started */
-#define VIDEO_GET_FRAME_COUNT	   _IOR('o', 58, __u64)
-
-#define VIDEO_COMMAND		   _IOWR('o', 59, struct video_command)
-#define VIDEO_TRY_COMMAND	   _IOWR('o', 60, struct video_command)
-
-#endif /* _UAPI_DVBVIDEO_H_ */
--- ./linux-source-6.1-original/include/uapi/linux/av7110.h	1970-01-01 01:00:00.000000000 +0100
+++ ./linux-source-6.1-incmodi/include/uapi/linux/av7110.h	2023-01-28 21:56:50.227065324 +0100
@@ -0,0 +1,442 @@
+/* SPDX-License-Identifier: LGPL-2.1+ WITH Linux-syscall-note */
+/*
+ * av7119.h - AV7110 MPEG-TS decoder API
+ *
+ * Copyright (C) 2000 Ralph  Metzler <ralph@convergence.de>
+ *                  & Marcus Metzler <marcus@convergence.de>
+ *                    for convergence integrated media GmbH
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Lesser Public License
+ * as published by the Free Software Foundation; either version 2.1
+ * of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+ *
+ */
+
+#ifndef _UAPI_AV7110_H_
+#define _UAPI_AV7110_H_
+
+#include <linux/types.h>
+#ifndef __KERNEL__
+#include <time.h>
+#endif
+
+/* AV7110 audio */
+
+typedef enum {
+	AUDIO_SOURCE_DEMUX, /* Select the demux as the main source */
+	AUDIO_SOURCE_MEMORY /* Select internal memory as the main source */
+} audio_stream_source_t;
+
+
+typedef enum {
+	AUDIO_STOPPED,      /* Device is stopped */
+	AUDIO_PLAYING,      /* Device is currently playing */
+	AUDIO_PAUSED        /* Device is paused */
+} audio_play_state_t;
+
+
+typedef enum {
+	AUDIO_STEREO,
+	AUDIO_MONO_LEFT,
+	AUDIO_MONO_RIGHT,
+	AUDIO_MONO,
+	AUDIO_STEREO_SWAPPED
+} audio_channel_select_t;
+
+
+typedef struct audio_mixer {
+	unsigned int volume_left;
+	unsigned int volume_right;
+  /* what else do we need? bass, pass-through, ... */
+} audio_mixer_t;
+
+
+typedef struct audio_status {
+	int                    AV_sync_state;  /* sync audio and video? */
+	int                    mute_state;     /* audio is muted */
+	audio_play_state_t     play_state;     /* current playback state */
+	audio_stream_source_t  stream_source;  /* current stream source */
+	audio_channel_select_t channel_select; /* currently selected channel */
+	int                    bypass_mode;    /* pass on audio data to */
+	audio_mixer_t	       mixer_state;    /* current mixer state */
+} audio_status_t;                              /* separate decoder hardware */
+
+
+/* for GET_CAPABILITIES and SET_FORMAT, the latter should only set one bit */
+#define AUDIO_CAP_DTS    1
+#define AUDIO_CAP_LPCM   2
+#define AUDIO_CAP_MP1    4
+#define AUDIO_CAP_MP2    8
+#define AUDIO_CAP_MP3   16
+#define AUDIO_CAP_AAC   32
+#define AUDIO_CAP_OGG   64
+#define AUDIO_CAP_SDDS 128
+#define AUDIO_CAP_AC3  256
+
+#define AUDIO_STOP                 _IO('o', 1)
+#define AUDIO_PLAY                 _IO('o', 2)
+#define AUDIO_PAUSE                _IO('o', 3)
+#define AUDIO_CONTINUE             _IO('o', 4)
+#define AUDIO_SELECT_SOURCE        _IO('o', 5)
+#define AUDIO_SET_MUTE             _IO('o', 6)
+#define AUDIO_SET_AV_SYNC          _IO('o', 7)
+#define AUDIO_SET_BYPASS_MODE      _IO('o', 8)
+#define AUDIO_CHANNEL_SELECT       _IO('o', 9)
+#define AUDIO_GET_STATUS           _IOR('o', 10, audio_status_t)
+
+#define AUDIO_GET_CAPABILITIES     _IOR('o', 11, unsigned int)
+#define AUDIO_CLEAR_BUFFER         _IO('o',  12)
+#define AUDIO_SET_ID               _IO('o', 13)
+#define AUDIO_SET_MIXER            _IOW('o', 14, audio_mixer_t)
+#define AUDIO_SET_STREAMTYPE       _IO('o', 15)
+#define AUDIO_BILINGUAL_CHANNEL_SELECT _IO('o', 20)
+
+/* AV7110 osd */
+
+typedef enum {
+	/* All functions return -2 on "not open" */
+	OSD_Close = 1,	/* () */
+	/*
+	 * Disables OSD and releases the buffers
+	 * returns 0 on success
+	 */
+	OSD_Open,	/* (x0,y0,x1,y1,BitPerPixel[2/4/8](color&0x0F),mix[0..15](color&0xF0)) */
+	/*
+	 * Opens OSD with this size and bit depth
+	 * returns 0 on success, -1 on DRAM allocation error, -2 on "already open"
+	 */
+	OSD_Show,	/* () */
+	/*
+	 * enables OSD mode
+	 * returns 0 on success
+	 */
+	OSD_Hide,	/* () */
+	/*
+	 * disables OSD mode
+	 * returns 0 on success
+	 */
+	OSD_Clear,	/* () */
+	/*
+	 * Sets all pixel to color 0
+	 * returns 0 on success
+	 */
+	OSD_Fill,	/* (color) */
+	/*
+	 * Sets all pixel to color <col>
+	 * returns 0 on success
+	 */
+	OSD_SetColor,	/* (color,R{x0},G{y0},B{x1},opacity{y1}) */
+	/*
+	 * set palette entry <num> to <r,g,b>, <mix> and <trans> apply
+	 * R,G,B: 0..255
+	 * R=Red, G=Green, B=Blue
+	 * opacity=0:      pixel opacity 0% (only video pixel shows)
+	 * opacity=1..254: pixel opacity as specified in header
+	 * opacity=255:    pixel opacity 100% (only OSD pixel shows)
+	 * returns 0 on success, -1 on error
+	 */
+	OSD_SetPalette,	/* (firstcolor{color},lastcolor{x0},data) */
+	/*
+	 * Set a number of entries in the palette
+	 * sets the entries "firstcolor" through "lastcolor" from the array "data"
+	 * data has 4 byte for each color:
+	 * R,G,B, and a opacity value: 0->transparent, 1..254->mix, 255->pixel
+	 */
+	OSD_SetTrans,	/* (transparency{color}) */
+	/*
+	 * Sets transparency of mixed pixel (0..15)
+	 * returns 0 on success
+	 */
+	OSD_SetPixel,	/* (x0,y0,color) */
+	/*
+	 * sets pixel <x>,<y> to color number <col>
+	 * returns 0 on success, -1 on error
+	 */
+	OSD_GetPixel,	/* (x0,y0) */
+	/* returns color number of pixel <x>,<y>,  or -1 */
+	OSD_SetRow,	/* (x0,y0,x1,data) */
+	/*
+	 * fills pixels x0,y through  x1,y with the content of data[]
+	 * returns 0 on success, -1 on clipping all pixel (no pixel drawn)
+	 */
+	OSD_SetBlock,	/* (x0,y0,x1,y1,increment{color},data) */
+	/*
+	 * fills pixels x0,y0 through  x1,y1 with the content of data[]
+	 * inc contains the width of one line in the data block,
+	 * inc<=0 uses blockwidth as linewidth
+	 * returns 0 on success, -1 on clipping all pixel
+	 */
+	OSD_FillRow,	/* (x0,y0,x1,color) */
+	/*
+	 * fills pixels x0,y through  x1,y with the color <col>
+	 * returns 0 on success, -1 on clipping all pixel
+	 */
+	OSD_FillBlock,	/* (x0,y0,x1,y1,color) */
+	/*
+	 * fills pixels x0,y0 through  x1,y1 with the color <col>
+	 * returns 0 on success, -1 on clipping all pixel
+	 */
+	OSD_Line,	/* (x0,y0,x1,y1,color) */
+	/*
+	 * draw a line from x0,y0 to x1,y1 with the color <col>
+	 * returns 0 on success
+	 */
+	OSD_Query,	/* (x0,y0,x1,y1,xasp{color}}), yasp=11 */
+	/*
+	 * fills parameters with the picture dimensions and the pixel aspect ratio
+	 * returns 0 on success
+	 */
+	OSD_Test,       /* () */
+	/*
+	 * draws a test picture. for debugging purposes only
+	 * returns 0 on success
+	 * TODO: remove "test" in final version
+	 */
+	OSD_Text,	/* (x0,y0,size,color,text) */
+	OSD_SetWindow,	/* (x0) set window with number 0<x0<8 as current */
+	OSD_MoveWindow,	/* move current window to (x0, y0) */
+	OSD_OpenRaw,	/* Open other types of OSD windows */
+} OSD_Command;
+
+typedef struct osd_cmd_s {
+	OSD_Command cmd;
+	int x0;
+	int y0;
+	int x1;
+	int y1;
+	int color;
+	void __user *data;
+} osd_cmd_t;
+
+/* OSD_OpenRaw: set 'color' to desired window type */
+typedef enum {
+	OSD_BITMAP1,           /* 1 bit bitmap */
+	OSD_BITMAP2,           /* 2 bit bitmap */
+	OSD_BITMAP4,           /* 4 bit bitmap */
+	OSD_BITMAP8,           /* 8 bit bitmap */
+	OSD_BITMAP1HR,         /* 1 Bit bitmap half resolution */
+	OSD_BITMAP2HR,         /* 2 bit bitmap half resolution */
+	OSD_BITMAP4HR,         /* 4 bit bitmap half resolution */
+	OSD_BITMAP8HR,         /* 8 bit bitmap half resolution */
+	OSD_YCRCB422,          /* 4:2:2 YCRCB Graphic Display */
+	OSD_YCRCB444,          /* 4:4:4 YCRCB Graphic Display */
+	OSD_YCRCB444HR,        /* 4:4:4 YCRCB graphic half resolution */
+	OSD_VIDEOTSIZE,        /* True Size Normal MPEG Video Display */
+	OSD_VIDEOHSIZE,        /* MPEG Video Display Half Resolution */
+	OSD_VIDEOQSIZE,        /* MPEG Video Display Quarter Resolution */
+	OSD_VIDEODSIZE,        /* MPEG Video Display Double Resolution */
+	OSD_VIDEOTHSIZE,       /* True Size MPEG Video Display Half Resolution */
+	OSD_VIDEOTQSIZE,       /* True Size MPEG Video Display Quarter Resolution*/
+	OSD_VIDEOTDSIZE,       /* True Size MPEG Video Display Double Resolution */
+	OSD_VIDEONSIZE,        /* Full Size MPEG Video Display */
+	OSD_CURSOR             /* Cursor */
+} osd_raw_window_t;
+
+typedef struct osd_cap_s {
+	int  cmd;
+#define OSD_CAP_MEMSIZE         1  /* memory size */
+	long val;
+} osd_cap_t;
+
+#define OSD_SEND_CMD            _IOW('o', 160, osd_cmd_t)
+#define OSD_GET_CAPABILITY      _IOR('o', 161, osd_cap_t)
+
+/* AV7110 video */
+
+typedef enum {
+	VIDEO_FORMAT_4_3,     /* Select 4:3 format */
+	VIDEO_FORMAT_16_9,    /* Select 16:9 format. */
+	VIDEO_FORMAT_221_1    /* 2.21:1 */
+} video_format_t;
+
+
+typedef enum {
+	VIDEO_PAN_SCAN,       /* use pan and scan format */
+	VIDEO_LETTER_BOX,     /* use letterbox format */
+	VIDEO_CENTER_CUT_OUT  /* use center cut out format */
+} video_displayformat_t;
+
+typedef struct {
+	int w;
+	int h;
+	video_format_t aspect_ratio;
+} video_size_t;
+
+typedef enum {
+	VIDEO_SOURCE_DEMUX, /* Select the demux as the main source */
+	VIDEO_SOURCE_MEMORY /* If this source is selected, the stream
+			       comes from the user through the write
+			       system call */
+} video_stream_source_t;
+
+
+typedef enum {
+	VIDEO_STOPPED, /* Video is stopped */
+	VIDEO_PLAYING, /* Video is currently playing */
+	VIDEO_FREEZED  /* Video is freezed */
+} video_play_state_t;
+
+
+/* Decoder commands */
+#define VIDEO_CMD_PLAY        (0)
+#define VIDEO_CMD_STOP        (1)
+#define VIDEO_CMD_FREEZE      (2)
+#define VIDEO_CMD_CONTINUE    (3)
+
+/* Flags for VIDEO_CMD_FREEZE */
+#define VIDEO_CMD_FREEZE_TO_BLACK	(1 << 0)
+
+/* Flags for VIDEO_CMD_STOP */
+#define VIDEO_CMD_STOP_TO_BLACK		(1 << 0)
+#define VIDEO_CMD_STOP_IMMEDIATELY	(1 << 1)
+
+/* Play input formats: */
+/* The decoder has no special format requirements */
+#define VIDEO_PLAY_FMT_NONE         (0)
+/* The decoder requires full GOPs */
+#define VIDEO_PLAY_FMT_GOP          (1)
+
+/* The structure must be zeroed before use by the application
+   This ensures it can be extended safely in the future. */
+struct video_command {
+	__u32 cmd;
+	__u32 flags;
+	union {
+		struct {
+			__u64 pts;
+		} stop;
+
+		struct {
+			/* 0 or 1000 specifies normal speed,
+			   1 specifies forward single stepping,
+			   -1 specifies backward single stepping,
+			   >1: playback at speed/1000 of the normal speed,
+			   <-1: reverse playback at (-speed/1000) of the normal speed. */
+			__s32 speed;
+			__u32 format;
+		} play;
+
+		struct {
+			__u32 data[16];
+		} raw;
+	};
+};
+
+/* FIELD_UNKNOWN can be used if the hardware does not know whether
+   the Vsync is for an odd, even or progressive (i.e. non-interlaced)
+   field. */
+#define VIDEO_VSYNC_FIELD_UNKNOWN	(0)
+#define VIDEO_VSYNC_FIELD_ODD		(1)
+#define VIDEO_VSYNC_FIELD_EVEN		(2)
+#define VIDEO_VSYNC_FIELD_PROGRESSIVE	(3)
+
+struct video_event {
+	__s32 type;
+#define VIDEO_EVENT_SIZE_CHANGED	1
+#define VIDEO_EVENT_FRAME_RATE_CHANGED	2
+#define VIDEO_EVENT_DECODER_STOPPED	3
+#define VIDEO_EVENT_VSYNC		4
+	/* unused, make sure to use atomic time for y2038 if it ever gets used */
+	long timestamp;
+	union {
+		video_size_t size;
+		unsigned int frame_rate;	/* in frames per 1000sec */
+		unsigned char vsync_field;	/* unknown/odd/even/progressive */
+	} u;
+};
+
+
+struct video_status {
+	int                   video_blank;   /* blank video on freeze? */
+	video_play_state_t    play_state;    /* current state of playback */
+	video_stream_source_t stream_source; /* current source (demux/memory) */
+	video_format_t        video_format;  /* current aspect ratio of stream*/
+	video_displayformat_t display_format;/* selected cropping mode */
+};
+
+
+struct video_still_picture {
+	char __user *iFrame;        /* pointer to a single iframe in memory */
+	__s32 size;
+};
+
+
+typedef __u16 video_attributes_t;
+/*   bits: descr. */
+/*   15-14 Video compression mode (0=MPEG-1, 1=MPEG-2) */
+/*   13-12 TV system (0=525/60, 1=625/50) */
+/*   11-10 Aspect ratio (0=4:3, 3=16:9) */
+/*    9- 8 permitted display mode on 4:3 monitor (0=both, 1=only pan-sca */
+/*    7    line 21-1 data present in GOP (1=yes, 0=no) */
+/*    6    line 21-2 data present in GOP (1=yes, 0=no) */
+/*    5- 3 source resolution (0=720x480/576, 1=704x480/576, 2=352x480/57 */
+/*    2    source letterboxed (1=yes, 0=no) */
+/*    0    film/camera mode (0=
+ *camera, 1=film (625/50 only)) */
+
+
+/* bit definitions for capabilities: */
+/* can the hardware decode MPEG1 and/or MPEG2? */
+#define VIDEO_CAP_MPEG1   1
+#define VIDEO_CAP_MPEG2   2
+/* can you send a system and/or program stream to video device?
+   (you still have to open the video and the audio device but only
+    send the stream to the video device) */
+#define VIDEO_CAP_SYS     4
+#define VIDEO_CAP_PROG    8
+/* can the driver also handle SPU, NAVI and CSS encoded data?
+   (CSS API is not present yet) */
+#define VIDEO_CAP_SPU    16
+#define VIDEO_CAP_NAVI   32
+#define VIDEO_CAP_CSS    64
+
+
+#define VIDEO_STOP                 _IO('o', 21)
+#define VIDEO_PLAY                 _IO('o', 22)
+#define VIDEO_FREEZE               _IO('o', 23)
+#define VIDEO_CONTINUE             _IO('o', 24)
+#define VIDEO_SELECT_SOURCE        _IO('o', 25)
+#define VIDEO_SET_BLANK            _IO('o', 26)
+#define VIDEO_GET_STATUS           _IOR('o', 27, struct video_status)
+#define VIDEO_GET_EVENT            _IOR('o', 28, struct video_event)
+#define VIDEO_SET_DISPLAY_FORMAT   _IO('o', 29)
+#define VIDEO_STILLPICTURE         _IOW('o', 30, struct video_still_picture)
+#define VIDEO_FAST_FORWARD         _IO('o', 31)
+#define VIDEO_SLOWMOTION           _IO('o', 32)
+#define VIDEO_GET_CAPABILITIES     _IOR('o', 33, unsigned int)
+#define VIDEO_CLEAR_BUFFER         _IO('o',  34)
+#define VIDEO_SET_STREAMTYPE       _IO('o', 36)
+#define VIDEO_SET_FORMAT           _IO('o', 37)
+#define VIDEO_GET_SIZE             _IOR('o', 55, video_size_t)
+
+/**
+ * VIDEO_GET_PTS
+ *
+ * Read the 33 bit presentation time stamp as defined
+ * in ITU T-REC-H.222.0 / ISO/IEC 13818-1.
+ *
+ * The PTS should belong to the currently played
+ * frame if possible, but may also be a value close to it
+ * like the PTS of the last decoded frame or the last PTS
+ * extracted by the PES parser.
+ */
+#define VIDEO_GET_PTS              _IOR('o', 57, __u64)
+
+/* Read the number of displayed frames since the decoder was started */
+#define VIDEO_GET_FRAME_COUNT	   _IOR('o', 58, __u64)
+
+#define VIDEO_COMMAND		   _IOWR('o', 59, struct video_command)
+#define VIDEO_TRY_COMMAND	   _IOWR('o', 60, struct video_command)
+
+#endif /* _UAPI_AV7110_H_ */
+ 

Re: Future of the SAA7146 drivers

[Soeren Moch]

Hi Stefan, Hans,

On 02.02.23 00:12, Stefan Herdler wrote:
> Hi Hans, Sören,
>
> On 01/02/23, 10:15 Hans Verkuil wrote:
>
> [...]
>>
>> Once it is converted to vb2 the driver can stay.
>>
>> Note that the driver might need a bit more work: we use the
>> v4l2-compliance
>> utility to test V4L2 API compliance of a driver, and after the vb2
>> conversion the driver should pass this test. So the compliance test
>> might
>> find some other things that do not work as they should, and it would be
>> really good to clean that up as well. Usually the things it finds are
>> pretty
>> easy to fix.
>>
> For the records, as long I remember it:
> The "Buget Patch" driver is superfluous and can be removed.
> This driver is for an experimental hardware-mod which never really
> worked. No such hardware was ever produced.
> I was really surprised to see it.
I own such card, as I wrote earlier. The budget patch works great and is
necessary for such cards. Please keep it.

Regards,
Soeren
>>>
>>> There is a long lasting controversy about the deprecated 3
>>> DVB-API-files
>>> for the av7110 driver.
>>> Sören stated he is tired about that discussions and looking for
>>> permanent solution without having to rewrite the whole driver.
>>>
>>> In this case I'm just the messenger, but I would also prefer a
>>> permanent
>>> solution.
>>> That is why I made the suggestion with the driver specific UAPI file.
>>> The av7110 driver is only driver using this API-part.
>>> And the modification is fairly easy and the impact minimal.
>>>
>>> May that be a compromise all parties can live with?
>>
>> Moving it to a public av7110.h header makes sense to me.
>
> I've done this already.
> Primary for my self to see if and how it may work.
> I'll attach the patch, maybe it is helpful.
>
> Theoretically there shouldn't be a difference whether the headers are in
> 1 or 3 files.
> Unused symbols should be removed by the compiler while optimization the
> result should be identical.
> I was just curious and decided to try it.
>
> Unfortunately I couldn't test it yet. But hopefully next weekend.
> There seems to be an issue with new kernel and my Nvidia graphics-card.
> But the kernel builds and boots into text console.
>
>>
>> It's a nice-to-have in my view, and moving it to a driver-specific API
>> should avoid future discussions. The fact remains that as long as
>> people use this API we can't remove it, however much we would want to.
>>
>> I think the main problem has always been that we are surprised at how
>> many people still use these cards. It's very similar in that respect
>> to the bttv driver: very old, but still in use.
>
> I own one too.
> Such cards can still be handy for digitizing family videos and stuff.
>
>>
>> The difference appears to be that the use of saa7146 cards is confined
>> to a specific region (esp. Germany), whereas bttv is in use worldwide.
>
> Until recently I wasn't aware that there are no saa7146 cards for ATSC
> nor ISDB.
>
>>
>> Because of that we just miss that it is still in use.
>>
>> Having an active maintainer should help with that.
>>
>> Regards,
>>
>>     Hans
>
>
>
>
>
> On 01/02/23, 14:51 Hans Verkuil wrote:
>
> [...]
>>
>> It's the analog video streaming that uses vb2, so being able to test
>> that
>> is critical.
>>
> The DVB data always uses one specific of the 2 video ports. The other
> one is not able to handle DVB-data.
> It is always the path through BRS and FIFO3, if I remember correctly.
>
> The analog video data has to use the remaining video port and FIFO1 if a
> DVB-Tuner is present.
> Input data format is YUV and output RGB. At least at the FF cards.
>
> (I may have confused the Ports, but in general it should be correct.)
>
> I don't have a combined budget-card and don't know how the driver
> handles analog inputs. But because of this hardware limitation there
> shouldn't be much difference between the decoded video of the FF and the
> video-input of a combined DVB-budget.
> Maybe testing on a FF is sufficient?
>
>
>> So I decided to do this differently:
>>
>> 1) I'll revert the move of saa7146 to staging, it will go back to
>>     mainline. av7110 stays in staging for now (that might change, I
>>     just don't want to make more changes than strictly necessary).
>>
>> 2) I will do the vb2 conversion. I have the analog video hardware,
>>     so I can test this.
>>
>> I didn't want to spend time on that originally, but since these drivers
>> are still in use, it is probably best if I bite the bullet and just
>> do it.
>>
>> I'm now almost done with the vb2 conversion of cx18, and it was about
>> 2 days work, which isn't that bad. I'll try to get this saa7146 vb2
>> conversion done this month.
>>
>> The PR reverting this has just been posted:
>>
>> https://patchwork.linuxtv.org/project/linux-media/patch/5902a4f2-da31-816c-f3cf-020340dbaddf@xs4all.nl/
>>
>>
>
> Great news, thanks!
>
> Regards
>
> Stefan
>
>> Regards,
>>
>>     Hans

Re: Future of the SAA7146 drivers

[Stefan Herdler]

Hi Hans, Sören,

On 02/02/23 10:43, Soeren Moch wrote:
> Hi Stefan, Hans,
>
> On 02.02.23 00:12, Stefan Herdler wrote:
>> Hi Hans, Sören,
>>
>> On 01/02/23, 10:15 Hans Verkuil wrote:
>>
>> [...]
>>>
>>> Once it is converted to vb2 the driver can stay.
>>>
>>> Note that the driver might need a bit more work: we use the
>>> v4l2-compliance
>>> utility to test V4L2 API compliance of a driver, and after the vb2
>>> conversion the driver should pass this test. So the compliance test
>>> might
>>> find some other things that do not work as they should, and it would be
>>> really good to clean that up as well. Usually the things it finds are
>>> pretty
>>> easy to fix.
>>>
>> For the records, as long I remember it:
>> The "Buget Patch" driver is superfluous and can be removed.
>> This driver is for an experimental hardware-mod which never really
>> worked. No such hardware was ever produced.
>> I was really surprised to see it.
> I own such card, as I wrote earlier. The budget patch works great and is
> necessary for such cards. Please keep it.
>
I think you confused it with is successor "fullTSmod" which works great
indeed.

The support for the "fullTSmod" is implemented in the "dvb-ttpci" kernel
module.
The "Buget Patch" driver is an separate kernel module.

 From Kkonfig:
config DVB_BUDGET_PATCH
	[...]
	  Support for Budget Patch (full TS) modification on
	  SAA7146+AV7110 based cards (DVB-S cards). This
	  driver doesn't use onboard MPEG2 decoder. The
	  card is driven in Budget-only mode. Card is
	  required to have loaded firmware to tune properly.
	  Firmware can be loaded by insertion and removal of
	  standard AV7110 driver prior to loading this
	  driver.

I my self own and operate a card with "fullTSmod" too. An I did some
mods for others.
I never loaded the "Buget Patch" driver.
And the kernel module it isn't loaded on my VDR. I checked it right now
again.

I removed the "budget-patch.ko" and everything kept working like usual.
Ill keep an eye on it.

Regards,
Stefan




> Regards,
> Soeren
[...]

Re: Future of the SAA7146 drivers

[Stefan Herdler]

Hi Hans,

It's me again, sorry.

Sören wrote to me that he dislikes the idea of driver specific
headerfile and will refuse to maintain the driver if there is any change.

I can't tell more, I'm just the messenger, sorry.

Regards,
Stefan



On 02.02.23 22:26, Stefan Herdler wrote:> Hi Hans, Sören,
>
> On 02/02/23 10:43, Soeren Moch wrote:
>> Hi Stefan, Hans,
>>
>> On 02.02.23 00:12, Stefan Herdler wrote:
>>> Hi Hans, Sören,
>>>
>>> On 01/02/23, 10:15 Hans Verkuil wrote:
>>>
>>> [...]
>>>>
>>>> Once it is converted to vb2 the driver can stay.
>>>>
>>>> Note that the driver might need a bit more work: we use the
>>>> v4l2-compliance
>>>> utility to test V4L2 API compliance of a driver, and after the vb2
>>>> conversion the driver should pass this test. So the compliance test
>>>> might
>>>> find some other things that do not work as they should, and it would be
>>>> really good to clean that up as well. Usually the things it finds are
>>>> pretty
>>>> easy to fix.
>>>>
>>> For the records, as long I remember it:
>>> The "Buget Patch" driver is superfluous and can be removed.
>>> This driver is for an experimental hardware-mod which never really
>>> worked. No such hardware was ever produced.
>>> I was really surprised to see it.
>> I own such card, as I wrote earlier. The budget patch works great and is
>> necessary for such cards. Please keep it.
>>
> I think you confused it with is successor "fullTSmod" which works great
> indeed.
>
> The support for the "fullTSmod" is implemented in the "dvb-ttpci" kernel
> module.
> The "Buget Patch" driver is an separate kernel module.
>
>  From Kkonfig:
> config DVB_BUDGET_PATCH
>      [...]
>        Support for Budget Patch (full TS) modification on
>        SAA7146+AV7110 based cards (DVB-S cards). This
>        driver doesn't use onboard MPEG2 decoder. The
>        card is driven in Budget-only mode. Card is
>        required to have loaded firmware to tune properly.
>        Firmware can be loaded by insertion and removal of
>        standard AV7110 driver prior to loading this
>        driver.
>
> I my self own and operate a card with "fullTSmod" too. An I did some
> mods for others.
> I never loaded the "Buget Patch" driver.
> And the kernel module it isn't loaded on my VDR. I checked it right now
> again.
>
> I removed the "budget-patch.ko" and everything kept working like usual.
> Ill keep an eye on it.
>
> Regards,
> Stefan
>
>
>
>
>> Regards,
>> Soeren
> [...]

Re: Future of the SAA7146 drivers

[Hans Verkuil]

On 03/02/2023 01:58, Stefan Herdler wrote:
> Hi Hans,
> 
> It's me again, sorry.
> 
> Sören wrote to me that he dislikes the idea of driver specific
> headerfile and will refuse to maintain the driver if there is any change.
> 
> I can't tell more, I'm just the messenger, sorry.

No problem, I think we'll just leave it as-is.

The reality is that 1) there are very few developers with in-depth DVB
knowledge in the media subsystem, and 2) they don't have time.

Also, the DVB drivers that are in the kernel seem to be doing fine:
bug reports are rare. This videobuf issue is the first in years that
cropped up and this too is really only analog video as well, it's just
that it affects DVB boards as well since the same driver is used.

The av7110 has always been an unusual card and some API decisions were
made in the past that do not fit well into our current ideas how this
should work. But frankly, I personally have no interest in getting
involved in that 'fight'.

BTW, I looked at your av7110api.diff patch and that is a good first step.
I do thing that the existing video.h/audio.h/osd.h should be replaced
with versions that just include av7110.h, with a big fat notice that
these APIs are now av7110 specific (as they have almost always been in
practice).

Regards,

	Hans

> 
> Regards,
> Stefan
> 
> 
> 
> On 02.02.23 22:26, Stefan Herdler wrote:> Hi Hans, Sören,
>>
>> On 02/02/23 10:43, Soeren Moch wrote:
>>> Hi Stefan, Hans,
>>>
>>> On 02.02.23 00:12, Stefan Herdler wrote:
>>>> Hi Hans, Sören,
>>>>
>>>> On 01/02/23, 10:15 Hans Verkuil wrote:
>>>>
>>>> [...]
>>>>>
>>>>> Once it is converted to vb2 the driver can stay.
>>>>>
>>>>> Note that the driver might need a bit more work: we use the
>>>>> v4l2-compliance
>>>>> utility to test V4L2 API compliance of a driver, and after the vb2
>>>>> conversion the driver should pass this test. So the compliance test
>>>>> might
>>>>> find some other things that do not work as they should, and it would be
>>>>> really good to clean that up as well. Usually the things it finds are
>>>>> pretty
>>>>> easy to fix.
>>>>>
>>>> For the records, as long I remember it:
>>>> The "Buget Patch" driver is superfluous and can be removed.
>>>> This driver is for an experimental hardware-mod which never really
>>>> worked. No such hardware was ever produced.
>>>> I was really surprised to see it.
>>> I own such card, as I wrote earlier. The budget patch works great and is
>>> necessary for such cards. Please keep it.
>>>
>> I think you confused it with is successor "fullTSmod" which works great
>> indeed.
>>
>> The support for the "fullTSmod" is implemented in the "dvb-ttpci" kernel
>> module.
>> The "Buget Patch" driver is an separate kernel module.
>>
>>  From Kkonfig:
>> config DVB_BUDGET_PATCH
>>      [...]
>>        Support for Budget Patch (full TS) modification on
>>        SAA7146+AV7110 based cards (DVB-S cards). This
>>        driver doesn't use onboard MPEG2 decoder. The
>>        card is driven in Budget-only mode. Card is
>>        required to have loaded firmware to tune properly.
>>        Firmware can be loaded by insertion and removal of
>>        standard AV7110 driver prior to loading this
>>        driver.
>>
>> I my self own and operate a card with "fullTSmod" too. An I did some
>> mods for others.
>> I never loaded the "Buget Patch" driver.
>> And the kernel module it isn't loaded on my VDR. I checked it right now
>> again.
>>
>> I removed the "budget-patch.ko" and everything kept working like usual.
>> Ill keep an eye on it.
>>
>> Regards,
>> Stefan
>>
>>
>>
>>
>>> Regards,
>>> Soeren
>> [...]

Re: Future of the SAA7146 drivers

[Stefan Herdler]

Hi Hans,

On 03/02/23 09:50, Hans Verkuil wrote:
> On 03/02/2023 01:58, Stefan Herdler wrote:
>> Hi Hans,
>>
>> It's me again, sorry.
>>
>> Sören wrote to me that he dislikes the idea of driver specific
>> headerfile and will refuse to maintain the driver if there is any change.
>>
>> I can't tell more, I'm just the messenger, sorry.
>
> No problem, I think we'll just leave it as-is.
>
> The reality is that 1) there are very few developers with in-depth DVB
> knowledge in the media subsystem, and 2) they don't have time.

Sörens "no changes" means absolutely no changes.
That includes filenames, position, basically everything.

His main concern is that distributions may packages if build brakes.
I wasn't aware of that since Friday. (Poor communication, sorry.)

This concern is not completely unjustified.
Especially if it happens without notice and no update is available.

The download links of the vdr-plugin seems to be broken, which might be
fatal in this case.
It happened this summer when vdr switched from FTP to GIT. I suppose it
was inadvertently and can be fixed quickly.
I'll take care of it, a missing source isn't good anyway.

Until today I wasn't aware of that either.
I focused on the kernel and used a local copy so far.

>
> Also, the DVB drivers that are in the kernel seem to be doing fine:
> bug reports are rare. This videobuf issue is the first in years that
> cropped up and this too is really only analog video as well, it's just
> that it affects DVB boards as well since the same driver is used.
>
> The av7110 has always been an unusual card and some API decisions were
> made in the past that do not fit well into our current ideas how this
> should work. But frankly, I personally have no interest in getting
> involved in that 'fight'.

Me neither.
But it looks like I already managed to get between the lines :-(.
>
> BTW, I looked at your av7110api.diff patch and that is a good first step.
> I do thing that the existing video.h/audio.h/osd.h should be replaced
> with versions that just include av7110.h,

For clarification:
I mentioned the API-conversion under the impression the av7110 driver is
almost already gone and that it might be the only chance to save it.
I do not really want this conversion, I still prefer to avoid it.
But if the choice is between driver removal and API-conversion, I'll
take the latter.

Please inform us early, if Linux-Media decides the API-conversion is
necessary and has to be done.
I guess it takes at least 1/2 year to distribute the updates.
Unfortunately, Sören most likely won't be "in the boat" anymore, in this
case. But that is his own decision.



Anyhow, this is topic for later, as you wrote recently.
First thing to do is the videobuf conversion.

In the next weeks I'll be busy with other things and probably don't find
much time for this hobby.
But other modifications to the driver doesn't make much sense while
videobuf conversion is in progress anyway.

Please cc me if you're done with videobuf conversion. I might overlook
it otherwise.
I'll take a look at the compliance-tool then and try to fix as much I can.

> with a big fat notice that
> these APIs are now av7110 specific
Don't worry there are only the 2 fullfeatured-cards using this API and
just because of historical reasons. The driver of the "new"
HD-fullfeatured-card dates back to 2008 (*).
Meanwhile here have been written several specific output-device-plugins
for vdr using V4L-API, vaapi, vdpau, ...
There are no plans to use this part of the DVB-API ever again.

(* The driver is out-of-tree and doesn't count. It is just about the date.)
  (as they have almost always been in
> practice).
>
> Regards,
>
> 	Hans
>
>>

Regards,

Stefan

Re: Future of the SAA7146 drivers

[Mauro Carvalho Chehab]

Em Wed, 1 Feb 2023 17:37:12 +0100
Hans Verkuil <hverkuil-cisco@xs4all.nl> escreveu:

> On 01/02/2023 16:20, Soeren Moch wrote:
> > 
> > 
> > On 01.02.23 14:51, Hans Verkuil wrote:  
> >> Hi Sören,
> >>
> >> On 01/02/2023 12:35, Soeren Moch wrote:
> >>
> >> <snip>
> >>  
> >>>>>> Obviously, if someone wants to do the vb2 conversion, then that would be
> >>>>>> perfect. I was looking at removing analog video support, and that doesn't
> >>>>>> look as easy as I thought it would be.
> >>>>>>  
> >>> I only own full-featured (Nexus) cards, modified to also support a mode
> >>> of operation like budget cards. In full-featured cards there is a
> >>> possibility to re-read the decoded video output signal back, which could
> >>> be similar to how analog cards work. But I never had access to
> >>> analog/hybrid saa7146 cards, so I'm not sure I can test this mode. I
> >>> also don't know anybody with such card who could help testing.
> >>> I personally do not care much about analog card support in the driver,
> >>> but will at least check which part of analog functionality is used in
> >>> full-featured cards. Maybe the support for analog/hybrid cards and some
> >>> test coverage comes for free with full support for full-featured cards.  
> >> It's the analog video streaming that uses vb2, so being able to test that
> >> is critical.
> >>
> >> So I decided to do this differently:
> >>
> >> 1) I'll revert the move of saa7146 to staging, it will go back to
> >>     mainline. av7110 stays in staging for now (that might change, I
> >>     just don't want to make more changes than strictly necessary).  
> > Hm, you wrote earlier, all this staging is about vb2 conversion.
> > There is no videobuf in av7110. Why this part needs to stay in staging?
> > 
> > How can I help here?  
> 
> Right, there are two different issues here: av7110 in staging (and I wasn't
> aware that these boards have no analog support) and the removal of the old videobuf.
> 
> I have not really been involved in the move of av7110 to staging, but
> given the fact that it is still used, I think it would make sense to just
> make the 'problematic' part of the API an av7110 driver-specific API, and
> then it can be moved back.

Heh, if I'm not mistaken, you were the one who wrote the patc moving it
to staging ;-)

The av7110 is in staging for two reasons:
- It is the only in-kernel driver that (partially) uses the 
  full-featured DVB API;
- Several IOCTLs used there are deprecated. See, for instance,
  AUDIO_BILINGUAL_CHANNEL_SELECT documentation:

	" This ioctl is obsolete. Do not use in new drivers. It has been replaced
	  by the V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK`` control
	  for MPEG decoders controlled through V4L2. "

- the full-featured DVB API were never fully/properly documented. We did an
  effort to document what it was possible, but there are still documentation
  gaps.
- there are some parts of the full-featured API that aren't used on av7110,
  which makes hard to have them documented. I guess those bits are used only
  on some DVB settop boxes.
- there's a goal to use MC and V4L2 API for several of the features there.
  However, as this didn't actually happen, I guess we can consider such
  API as av7110-specific API when the time comes to move it from staging.

Now, before moving av7110 out of staging, the API should be clearly
documented (and/or the unused parts of the API should be removed).

So, for now, I'm ok to move saa7146 out of "deprecated" part, but
we should keep av7110 in staging (and all parts of saa7146 that
may depend on av7110) while we don't fix the API documentation.

Thanks,
Mauro

Re: Future of the SAA7146 drivers

[Mauro Carvalho Chehab]

Em Mon, 6 Feb 2023 01:06:47 +0100
Stefan Herdler <herdler@nurfuerspam.de> escreveu:

> Hi Hans,
> 
> On 03/02/23 09:50, Hans Verkuil wrote:
> > On 03/02/2023 01:58, Stefan Herdler wrote:  
> >> Hi Hans,
> >>
> >> It's me again, sorry.
> >>
> >> Sören wrote to me that he dislikes the idea of driver specific
> >> headerfile and will refuse to maintain the driver if there is any change.
> >>
> >> I can't tell more, I'm just the messenger, sorry.  
> >
> > No problem, I think we'll just leave it as-is.
> >
> > The reality is that 1) there are very few developers with in-depth DVB
> > knowledge in the media subsystem, and 2) they don't have time.  
> 
> Sörens "no changes" means absolutely no changes.
> That includes filenames, position, basically everything.

It won't make any sense to warrant that any Kernel files will be kept 
as-is forever. If one wants a fixed driver, just use a LTS distro.
 
> His main concern is that distributions may packages if build brakes.
> I wasn't aware of that since Friday. (Poor communication, sorry.)

Distributions can handle changes on Kernel files, provided that any
changes would also be applied at the userspace apps (if this is the
case).

> This concern is not completely unjustified.
> Especially if it happens without notice and no update is available.
> 
> The download links of the vdr-plugin seems to be broken, which might be
> fatal in this case.
> It happened this summer when vdr switched from FTP to GIT. I suppose it
> was inadvertently and can be fixed quickly.
> I'll take care of it, a missing source isn't good anyway.
> 
> Until today I wasn't aware of that either.
> I focused on the kernel and used a local copy so far.
> 
> >
> > Also, the DVB drivers that are in the kernel seem to be doing fine:
> > bug reports are rare. This videobuf issue is the first in years that
> > cropped up and this too is really only analog video as well, it's just
> > that it affects DVB boards as well since the same driver is used.
> >
> > The av7110 has always been an unusual card and some API decisions were
> > made in the past that do not fit well into our current ideas how this
> > should work. But frankly, I personally have no interest in getting
> > involved in that 'fight'.  
> 
> Me neither.
> But it looks like I already managed to get between the lines :-(.
> >
> > BTW, I looked at your av7110api.diff patch and that is a good first step.
> > I do thing that the existing video.h/audio.h/osd.h should be replaced
> > with versions that just include av7110.h,  
> 
> For clarification:
> I mentioned the API-conversion under the impression the av7110 driver is
> almost already gone and that it might be the only chance to save it.
> I do not really want this conversion, I still prefer to avoid it.
> But if the choice is between driver removal and API-conversion, I'll
> take the latter.
> 
> Please inform us early, if Linux-Media decides the API-conversion is
> necessary and has to be done.
> I guess it takes at least 1/2 year to distribute the updates.
> Unfortunately, Sören most likely won't be "in the boat" anymore, in this
> case. But that is his own decision.
> 
> Anyhow, this is topic for later, as you wrote recently.
> First thing to do is the videobuf conversion.
> 
> In the next weeks I'll be busy with other things and probably don't find
> much time for this hobby.
> But other modifications to the driver doesn't make much sense while
> videobuf conversion is in progress anyway.
> 
> Please cc me if you're done with videobuf conversion. I might overlook
> it otherwise.
> I'll take a look at the compliance-tool then and try to fix as much I can.
> 
> > with a big fat notice that
> > these APIs are now av7110 specific  
> Don't worry there are only the 2 fullfeatured-cards using this API and
> just because of historical reasons. The driver of the "new"
> HD-fullfeatured-card dates back to 2008 (*).
> Meanwhile here have been written several specific output-device-plugins
> for vdr using V4L-API, vaapi, vdpau, ...
> There are no plans to use this part of the DVB-API ever again.

Ok. If that's the case, maybe we can just keep the api without changes.

Yet, in order to move av7110 out of staging, we should finish documenting
the API (or drop the unused/undocumented parts of it).

> (* The driver is out-of-tree and doesn't count. It is just about the date.)
>   (as they have almost always been in
> > practice).

Thanks,
Mauro

Re: Future of the SAA7146 drivers

[Stefan Herdler]

On 08/02/23 10:08, Mauro Carvalho Chehab wrote:

[...]

>>> with a big fat notice that
>>> these APIs are now av7110 specific
>> Don't worry there are only the 2 fullfeatured-cards using this API and
>> just because of historical reasons. The driver of the "new"
>> HD-fullfeatured-card dates back to 2008 (*).
>> Meanwhile here have been written several specific output-device-plugins
>> for vdr using V4L-API, vaapi, vdpau, ...
>> There are no plans to use this part of the DVB-API ever again.
>
> Ok. If that's the case, maybe we can just keep the api without changes.
>
> Yet, in order to move av7110 out of staging, we should finish documenting
> the API (or drop the unused/undocumented parts of it).

Hi Mauro,
that sounds like a good plan to me.

Documentation is a solvable problem. At least for the parts used by the
full-featured-cards.
The VDR-plugin-API is pretty well documented (1) and the output-plugin
for the full-featured-cards push most commands right trough.

It is still a laborious task to crosscheck the documents, but most
information should be already there.
I think I'll get it done, but it my take a while depending on my other
duties.


Documenting the "unused" parts could be difficult.
There is no helpful documentation about the "enigma2" receivers. At
least I haven't found some.
This receivers are also not completely open source. The the drivers seem
to be binary only.
The only things I know for sure are: The OSD-part of the DVB-API isn't
used (2) and the audio- and video-part are used (3).
I manged to find the file where the headers are included (4), but there
is no documentation either.


I think I'll start with the used parts and see how far I come.
I'll mail again when I'm done, probably in 2 or 3 weeks.


Thanks and Regards

Stefan


>
>> (* The driver is out-of-tree and doesn't count. It is just about the date.)
>>    (as they have almost always been in
>>> practice).
>
> Thanks,
> Mauro

1.  http://git.tvdr.de/?p=vdr.git;a=blob;f=device.h

2.  https://en.wikipedia.org/wiki/Enigma_(DVB)#Technical_realization
     "direct access to framebuffer"

3.
https://github.com/OpenPLi/openpli-oe-core/blob/10e1dd6b0109ce787dbae204275659778119eafb/meta-openpli/recipes-kernel/linux-libc-headers/linux-libc-headers/audio_video_ioctl.patch

4.  https://github.com/openatv/enigma2/blob/master/lib/dvb/decoder.cpp

saa7146: please test the vb2 conversion!

[Hans Verkuil]

Hi all,

I finished the vb2 conversion and tested what I could test. I am missing
'full featured' hardware, so I could not test the analog video capture part
of that. It's not clear to me if VBI capture is also supported on those
cards, if so, then that needs to be tested as well.

Note that there is one userspace-facing change: the VBI output settings
are kept, even if the vbi device is closed by the application.

Before you had to open the vbi device, format the slice VBI output, and
write sliced VBI data to it. Closing the device would reset how VBI output
behaves. That is not in spec with the V4L2 API. The format is kept after
the device is closed.

Any application that uses VBI output and that wants to keep the same
behavior would have to call VIDIOC_S_FMT with a struct v4l2_sliced_vbi_format
with a service_set field set to 0 to indicate that you don't want to
output any VBI anymore.

If this is a problem, then I can make a module option that selects the old
behavior.

BTW, if anyone has a spare full-featured card (i.e. with analog video capture
as well), then I would love to take it off your hands so that I can test that
myself!

This series has been tested on the two Hexium boards, the mxb board, and two
av7710 boards (DVB-C and DVB-T).

Regards,

	Hans

Re: saa7146: please test the vb2 conversion!

[Hans Verkuil]

On 24/03/2023 11:37, Hans Verkuil wrote:
> Hi all,
> 
> I finished the vb2 conversion and tested what I could test. I am missing
> 'full featured' hardware, so I could not test the analog video capture part
> of that. It's not clear to me if VBI capture is also supported on those
> cards, if so, then that needs to be tested as well.
> 
> Note that there is one userspace-facing change: the VBI output settings
> are kept, even if the vbi device is closed by the application.
> 
> Before you had to open the vbi device, format the slice VBI output, and
> write sliced VBI data to it. Closing the device would reset how VBI output
> behaves. That is not in spec with the V4L2 API. The format is kept after
> the device is closed.
> 
> Any application that uses VBI output and that wants to keep the same
> behavior would have to call VIDIOC_S_FMT with a struct v4l2_sliced_vbi_format
> with a service_set field set to 0 to indicate that you don't want to
> output any VBI anymore.
> 
> If this is a problem, then I can make a module option that selects the old
> behavior.
> 
> BTW, if anyone has a spare full-featured card (i.e. with analog video capture
> as well), then I would love to take it off your hands so that I can test that
> myself!
> 
> This series has been tested on the two Hexium boards, the mxb board, and two
> av7710 boards (DVB-C and DVB-T).

It does help if I point to the patches :-)

The patch series is here:

https://patchwork.linuxtv.org/project/linux-media/list/?series=10140

It's also in my git tree:

https://git.linuxtv.org/hverkuil/media_tree.git/log/?h=saa7146-clean

Regards,

	Hans

Re: saa7146: please test the vb2 conversion!

[Stefan Herdler]

Hi Hans,

great to read, that it is finally done, thank you for your work!


On 24/03/23 11:40 Hans Verkuil wrote:
> On 24/03/2023 11:37, Hans Verkuil wrote:
>> Hi all,
>>
>> I finished the vb2 conversion and tested what I could test. I am missing
>> 'full featured' hardware, so I could not test the analog video capture part
There is some miss understanding.
At VDR 'full featured' refers to all DVB-cards with decoder and OSD.

I wasn't aware, that this definition doesn't seem to be common, sorry.
>> of that. It's not clear to me if VBI capture is also supported on those
>> cards, if so, then that needs to be tested as well.
>>
>> Note that there is one userspace-facing change: the VBI output settings
>> are kept, even if the vbi device is closed by the application.
>>
>> Before you had to open the vbi device, format the slice VBI output, and
>> write sliced VBI data to it. Closing the device would reset how VBI output
>> behaves. That is not in spec with the V4L2 API. The format is kept after
>> the device is closed.
>>
>> Any application that uses VBI output and that wants to keep the same
>> behavior would have to call VIDIOC_S_FMT with a struct v4l2_sliced_vbi_format
>> with a service_set field set to 0 to indicate that you don't want to
>> output any VBI anymore.
>>
>> If this is a problem, then I can make a module option that selects the old
>> behavior.
>>
>> BTW, if anyone has a spare full-featured card (i.e. with analog video capture
>> as well), then I would love to take it off your hands so that I can test that
>> myself!
There are only DVB-C boards with analog features.

I personally never had cable-TV nor own any DVB-C cards.
But I try to find such a card with an analog module on it.
>>
>> This series has been tested on the two Hexium boards, the mxb board, and two
>> av7710 boards (DVB-C and DVB-T).

I can test on the DVB-S hardware.

But let me finish the API-documentation fist, it is almost done.
There are only the complains from chackpatch left to fix, I hope it is done quickly.


Regards
Stefan


>
> It does help if I point to the patches :-)
>
> The patch series is here:
>
> https://patchwork.linuxtv.org/project/linux-media/list/?series=10140
>
> It's also in my git tree:
>
> https://git.linuxtv.org/hverkuil/media_tree.git/log/?h=saa7146-clean
>
> Regards,
>
> 	Hans

[PATCH] Legacy DVB API: completion of documentation

[Stefan Herdler]

Hi Mauro and Hans,

it took a little longer then anticipated, but I think I was able to fill the gaps in the documentation.
At least everything in the header-files is in the documentation now. I hope, I have done it sufficiently.

Some remarks:

I considered the existing documentation to be trustworthy.
Existing things like returntypes, errnos, ... haven't been touched by me.
There are only a few minor modifications to reflect the data formats actually used for playback.

The documentation has been merged into one file per header-file. Entries have been sorted equally.
For me it is much better arranged this way, the mass of different files where just to confusing and the
original files have already been removed anyway.
But I may revert that if necessary.

Title and chapter-styles has been changed to the suggested ones in "/doc-guide/sphinx.html#writing-documentation".

There are still some "Duplicate C++ declaration, ..." warnings. Renaming doesn't work either: 'unknown option: "name"'
I haven't found any useful hint how to get rid of them.
Should I switch to "code-block:: c" instead?
But there are a lot of this warnings from other files too. It seems I'm mot the only one with this problem.


Please point out, if something is missing, wrong or need to be improved. I will try to fix it.

Regards
Stefan

p.s. It is my first try to submit a patch this way. I hope my mail-client doesn't mess it up.



This patch is largely based on the already existing documentation and the header files.

Signed-off-by: Stefan Herdler <herdler@nurfuerspam.de>


diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst
index b97d56ee543c..ffe8325749e5 100644
--- a/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst
+++ b/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst
@@ -23,3 +23,4 @@ DVB-S2, DVB-T2, ISDB, etc.
     :maxdepth: 1

     frontend_legacy_dvbv3_api
+    legacy_dvb_decoder_api
diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst
new file mode 100644
index 000000000000..3197b29df2fa
--- /dev/null
+++ b/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst
@@ -0,0 +1,1242 @@
+.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+
+.. _dvb_audio:
+
+================
+DVB Audio Device
+================
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+The DVB audio device controls the MPEG2 audio decoder of the DVB
+hardware. It can be accessed through ``/dev/dvb/adapter?/audio?``. Data
+types and ioctl definitions can be accessed by including
+``linux/dvb/audio.h`` in your application.
+
+Please note that most DVB cards don’t have their own MPEG decoder, which
+results in the omission of the audio and video device.
+
+These ioctls were also used by V4L2 to control MPEG decoders implemented
+in V4L2. The use of these ioctls for that purpose has been made obsolete
+and proper V4L2 ioctls or controls have been created to replace that
+functionality. Use :ref:`V4L2 ioctls<video>` for new drivers!
+
+
+
+Audio Data Types
+================
+
+This section describes the structures, data types and defines used when
+talking to the audio device.
+
+
+
+audio_stream_source_t
+---------------------
+
+The audio stream source is set through the `AUDIO_SELECT_SOURCE`_ call
+and can take the following values, depending on whether we are replaying
+from an internal (demux) or external (user write) source.
+
+
+.. code-block:: c
+
+    typedef enum {
+	AUDIO_SOURCE_DEMUX,
+	AUDIO_SOURCE_MEMORY
+    } audio_stream_source_t;
+
+AUDIO_SOURCE_DEMUX selects the demultiplexer (fed either by the
+frontend or the DVR device) as the source of the video stream. If
+AUDIO_SOURCE_MEMORY is selected the stream comes from the application
+through the `write()`_ system call.
+
+
+audio_play_state_t
+------------------
+
+The following values can be returned by the `AUDIO_GET_STATUS`_ call
+representing the state of audio playback.
+
+
+.. code-block:: c
+
+    typedef enum {
+	AUDIO_STOPPED,
+	AUDIO_PLAYING,
+	AUDIO_PAUSED
+    } audio_play_state_t;
+
+
+audio_channel_select_t
+----------------------
+
+The audio channel selected via `AUDIO_CHANNEL_SELECT`_ is determined by
+the following values.
+
+
+.. code-block:: c
+
+    typedef enum {
+	AUDIO_STEREO,
+	AUDIO_MONO_LEFT,
+	AUDIO_MONO_RIGHT,
+	AUDIO_MONO,
+	AUDIO_STEREO_SWAPPED
+    } audio_channel_select_t;
+
+
+audio_mixer
+-----------
+
+The following structure is used by the `AUDIO_SET_MIXER`_ call to set the
+audio volume.
+
+
+.. code-block:: c
+
+    typedef struct audio_mixer {
+	unsigned int volume_left;
+	unsigned int volume_right;
+    } audio_mixer_t;
+
+
+audio_status
+------------
+
+The `AUDIO_GET_STATUS`_ call returns the following structure informing
+about various states of the playback operation.
+
+
+.. code-block:: c
+
+    typedef struct audio_status {
+	boolean AV_sync_state;
+	boolean mute_state;
+	audio_play_state_t play_state;
+	audio_stream_source_t stream_source;
+	audio_channel_select_t channel_select;
+	boolean bypass_mode;
+	audio_mixer_t mixer_state;
+    } audio_status_t;
+
+
+audio encodings
+---------------
+
+A call to `AUDIO_GET_CAPABILITIES`_ returns an unsigned integer with the
+following bits set according to the hardwares capabilities.
+
+
+.. code-block:: c
+
+     #define AUDIO_CAP_DTS    1
+     #define AUDIO_CAP_LPCM   2
+     #define AUDIO_CAP_MP1    4
+     #define AUDIO_CAP_MP2    8
+     #define AUDIO_CAP_MP3   16
+     #define AUDIO_CAP_AAC   32
+     #define AUDIO_CAP_OGG   64
+     #define AUDIO_CAP_SDDS 128
+     #define AUDIO_CAP_AC3  256
+
+
+Audio Function Calls
+====================
+
+
+AUDIO_STOP
+----------
+
+Synopsis
+~~~~~~~~
+
+.. cpp:function:: int ioctl(int fd, int request = AUDIO_STOP)
+   :name: LEGACY_DVB_AUDIO_STOP
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_STOP for this command.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to stop playing the current
+stream.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+AUDIO_PLAY
+----------
+
+Synopsis
+~~~~~~~~
+
+.. cpp:function:: int  ioctl(int fd, int request = AUDIO_PLAY)
+   :name: LEGACY_DVB_AUDIO_PLAY
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_PLAY for this command.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to start playing an audio stream
+from the selected source.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+AUDIO_PAUSE
+-----------
+
+Synopsis
+~~~~~~~~
+
+.. cpp:function:: int  ioctl(int fd, int request = AUDIO_PAUSE)
+   :name: LEGACY_DVB_AUDIO_PAUSE
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_PAUSE for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call suspends the audio stream being played. Decoding and
+playing are paused. It is then possible to restart again decoding and
+playing process of the audio stream using `AUDIO_CONTINUE`_ command.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+AUDIO_CONTINUE
+--------------
+
+Synopsis
+~~~~~~~~
+
+.. cpp:function:: int  ioctl(int fd, int request = AUDIO_CONTINUE)
+   :name: LEGACY_DVB_AUDIO_CONTINUE
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_CONTINUE for this command.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl restarts the decoding and playing process previously paused
+with `AUDIO_PAUSE`_ command.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+AUDIO_SELECT_SOURCE
+-------------------
+
+Synopsis
+~~~~~~~~
+
+.. cpp:function:: int ioctl(int fd, int request = AUDIO_SELECT_SOURCE, audio_stream_source_t source)
+   :name: LEGACY_DVB_AUDIO_SELECT_SOURCE
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_SELECT_SOURCE for this command.
+
+    -  .. row 3
+
+       -  `audio_stream_source_t`_ source
+
+       -  Indicates the source that shall be used for the Audio stream.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call informs the audio device which source shall be used for
+the input data. The possible sources are demux or memory. If
+AUDIO_SOURCE_MEMORY is selected, the data is fed to the Audio Device
+through the write command.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+AUDIO_SET_MUTE
+--------------
+
+Synopsis
+~~~~~~~~
+
+.. cpp:function:: int  ioctl(int fd, int request = AUDIO_SET_MUTE, boolean state)
+   :name: LEGACY_DVB_AUDIO_SET_MUTE
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_SET_MUTE for this command.
+
+    -  .. row 3
+
+       -  boolean state
+
+       -  Indicates if audio device shall mute or not.
+
+    -  .. row 4
+
+       -
+       -  TRUE Audio Mute
+
+    -  .. row 5
+
+       -
+       -  FALSE Audio Un-mute
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for DVB devices only. To control a V4L2 decoder use the
+V4L2 :ref:`VIDIOC_DECODER_CMD` with the
+``V4L2_DEC_CMD_START_MUTE_AUDIO`` flag instead.
+
+This ioctl call asks the audio device to mute the stream that is
+currently being played.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+AUDIO_SET_AV_SYNC
+-----------------
+
+Synopsis
+~~~~~~~~
+
+.. cpp:function:: int  ioctl(int fd, int request = AUDIO_SET_AV_SYNC, boolean state)
+   :name: LEGACY_DVB_AUDIO_SET_AV_SYNC
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_AV_SYNC for this command.
+
+    -  .. row 3
+
+       -  boolean state
+
+       -  Tells the DVB subsystem if A/V synchronization shall be ON or OFF.
+
+    -  .. row 4
+
+       -
+       -  TRUE AV-sync ON
+
+    -  .. row 5
+
+       -
+       -  FALSE AV-sync OFF
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to turn ON or OFF A/V
+synchronization.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+AUDIO_SET_BYPASS_MODE
+---------------------
+
+Synopsis
+~~~~~~~~
+
+.. cpp:function:: int ioctl(int fd, int request = AUDIO_SET_BYPASS_MODE, boolean mode)
+   :name: LEGACY_DVB_AUDIO_SET_BYPASS_MODE
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_SET_BYPASS_MODE for this command.
+
+    -  .. row 3
+
+       -  boolean mode
+
+       -  Enables or disables the decoding of the current Audio stream in
+	  the DVB subsystem.
+
+    -  .. row 4
+
+       -
+       -  TRUE Bypass is disabled
+
+    -  .. row 5
+
+       -
+       -  FALSE Bypass is enabled
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to bypass the Audio decoder and
+forward the stream without decoding. This mode shall be used if streams
+that can’t be handled by the DVB system shall be decoded. Dolby
+DigitalTM streams are automatically forwarded by the DVB subsystem if
+the hardware can handle it.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+AUDIO_CHANNEL_SELECT
+--------------------
+
+Synopsis
+~~~~~~~~
+
+.. cpp:function:: int ioctl(int fd, int request = AUDIO_CHANNEL_SELECT, audio_channel_select_t)
+   :name: LEGACY_DVB_AUDIO_CHANNEL_SELECT
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_CHANNEL_SELECT for this command.
+
+    -  .. row 3
+
+       -  `audio_channel_select_t`_ ch
+
+       -  Select the output format of the audio (mono left/right, stereo).
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for DVB devices only. To control a V4L2 decoder use the
+V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK`` control instead.
+
+This ioctl call asks the Audio Device to select the requested channel if
+possible.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+AUDIO_GET_STATUS
+----------------
+
+Synopsis
+~~~~~~~~
+
+.. cpp:function:: int ioctl(int fd, int request = AUDIO_GET_STATUS, struct audio_status *status)
+   :name: LEGACY_DVB_AUDIO_GET_STATUS
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_GET_STATUS for this command.
+
+    -  .. row 3
+
+       -  struct `audio_status`_ \*status
+
+       -  Returns the current state of Audio Device.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to return the current state of the
+Audio Device.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+AUDIO_GET_CAPABILITIES
+----------------------
+
+Synopsis
+~~~~~~~~
+
+.. cpp:function:: int ioctl(int fd, int request = AUDIO_GET_CAPABILITIES, unsigned int *cap)
+   :name: LEGACY_DVB_AUDIO_GET_CAPABILITIES
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_GET_CAPABILITIES for this command.
+
+    -  .. row 3
+
+       -  unsigned int \*cap
+
+       -  Returns a bit array of supported sound formats.
+          Bits are defined in `audio encodings`_.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to tell us about the decoding
+capabilities of the audio hardware.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+AUDIO_CLEAR_BUFFER
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. cpp:function:: int  ioctl(int fd, int request = AUDIO_CLEAR_BUFFER)
+   :name: LEGACY_DVB_AUDIO_CLEAR_BUFFER
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_CLEAR_BUFFER for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to clear all software and hardware
+buffers of the audio decoder device.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+AUDIO_SET_ID
+------------
+
+Synopsis
+~~~~~~~~
+
+.. cpp:function:: int  ioctl(int fd, int request = AUDIO_SET_ID, int id)
+   :name: LEGACY_DVB_AUDIO_SET_ID
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_SET_ID for this command.
+
+    -  .. row 3
+
+       -  int id
+
+       -  audio sub-stream id
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl selects which sub-stream is to be decoded if a program or
+system stream is sent to the video device. If no audio stream type is
+set the id has to be in [0xC0,0xDF] for MPEG sound, in [0x80,0x87] for
+AC3 and in [0xA0,0xA7] for LPCM. More specifications may follow for
+other stream types. If the stream type is set the id just specifies the
+substream id of the audio stream and only the first 5 bits are
+recognized.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+AUDIO_SET_MIXER
+---------------
+
+Synopsis
+~~~~~~~~
+
+.. cpp:function:: int ioctl(int fd, int request = AUDIO_SET_MIXER, audio_mixer_t *mix)
+   :name: LEGACY_DVB_AUDIO_SET_MIXER
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_SET_ID for this command.
+
+    -  .. row 3
+
+       -  audio_mixer_t \*mix
+
+       -  mixer settings.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl lets you adjust the mixer settings of the audio decoder.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+
+AUDIO_SET_STREAMTYPE
+--------------------
+
+Synopsis
+~~~~~~~~
+
+.. cpp:function:: int  ioctl(fd, int request = AUDIO_SET_STREAMTYPE, int type)
+   :name: LEGACY_DVB_AUDIO_SET_STREAMTYPE
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_SET_STREAMTYPE for this command.
+
+    -  .. row 3
+
+       -  int type
+
+       -  stream type
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl tells the driver which kind of audio stream to expect. This
+is useful if the stream offers several audio sub-streams like LPCM and
+AC3.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  ``EINVAL``
+
+       -  type is not a valid or supported stream type.
+
+
+
+AUDIO_BILINGUAL_CHANNEL_SELECT
+------------------------------
+
+Synopsis
+~~~~~~~~
+
+.. cpp:function:: int ioctl(int fd, int request = AUDIO_BILINGUAL_CHANNEL_SELECT, audio_channel_select_t)
+   :name: LEGACY_DVB_AUDIO_BILINGUAL_CHANNEL_SELECT
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_BILINGUAL_CHANNEL_SELECT for this command.
+
+    -  .. row 3
+
+       -  audio_channel_select_t ch
+
+       -  Select the output format of the audio (mono left/right, stereo).
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl has been replaced by the V4L2
+``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK`` control
+for MPEG decoders controlled through V4L2.
+
+This ioctl call asks the Audio Device to select the requested channel
+for bilingual streams if possible.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+
+open()
+------
+
+Synopsis
+~~~~~~~~
+
+.. cpp:function:: int  open(const char *deviceName, int flags)
+   :name: LEGACY_DVB_AUDIO_OPEN
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  const char \*deviceName
+
+       -  Name of specific audio device.
+
+    -  .. row 2
+
+       -  int flags
+
+       -  A bit-wise OR of the following flags:
+
+    -  .. row 3
+
+       -
+       -  O_RDONLY read-only access
+
+    -  .. row 4
+
+       -
+       -  O_RDWR read/write access
+
+    -  .. row 5
+
+       -
+       -  O_NONBLOCK open in non-blocking mode
+
+    -  .. row 6
+
+       -
+       -  (blocking mode is the default)
+
+
+Description
+~~~~~~~~~~~
+
+This system call opens a named audio device (e.g.
+/dev/dvb/adapter0/audio0) for subsequent use. When an open() call has
+succeeded, the device will be ready for use. The significance of
+blocking or non-blocking mode is described in the documentation for
+functions where there is a difference. It does not affect the semantics
+of the open() call itself. A device opened in blocking mode can later be
+put into non-blocking mode (and vice versa) using the F_SETFL command
+of the fcntl system call. This is a standard system call, documented in
+the Linux manual page for fcntl. Only one user can open the Audio Device
+in O_RDWR mode. All other attempts to open the device in this mode will
+fail, and an error code will be returned. If the Audio Device is opened
+in O_RDONLY mode, the only ioctl call that can be used is
+`AUDIO_GET_STATUS`_. All other call will return with an error code.
+
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  ``ENODEV``
+
+       -  Device driver not loaded/available.
+
+    -  .. row 2
+
+       -  ``EBUSY``
+
+       -  Device or resource busy.
+
+    -  .. row 3
+
+       -  ``EINVAL``
+
+       -  Invalid argument.
+
+
+close()
+-------
+
+Synopsis
+~~~~~~~~
+
+.. cpp:function:: int  close(int fd)
+   :name: LEGACY_DVB_AUDIO_CLOSE
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+
+Description
+~~~~~~~~~~~
+
+This system call closes a previously opened audio device.
+
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  ``EBADF``
+
+       -  fd is not a valid open file descriptor.
+
+
+
+write()
+-------
+
+Synopsis
+~~~~~~~~
+
+.. cpp:function:: size_t write(int fd, const void *buf, size_t count)
+   :name: LEGACY_DVB_AUDIO_WRITE
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  void \*buf
+
+       -  Pointer to the buffer containing the PES data.
+
+    -  .. row 3
+
+       -  size_t count
+
+       -  Size of buf.
+
+
+Description
+~~~~~~~~~~~
+
+This system call can only be used if AUDIO_SOURCE_MEMORY is selected
+in the ioctl call `AUDIO_SELECT_SOURCE`_. The data provided shall be in
+PES format. If O_NONBLOCK is not specified the function will block
+until buffer space is available. The amount of data to be transferred is
+implied by count.
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  ``EPERM``
+
+       -  Mode AUDIO_SOURCE_MEMORY not selected.
+
+    -  .. row 2
+
+       -  ``ENOMEM``
+
+       -  Attempted to write more data than the internal buffer can hold.
+
+    -  .. row 3
+
+       -  ``EBADF``
+
+       -  fd is not a valid open file descriptor.
diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst
new file mode 100644
index 000000000000..566aa7b8eee6
--- /dev/null
+++ b/Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst
@@ -0,0 +1,61 @@
+.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+
+.. _legacy_dvb_decoder_api:
+
+============================
+Legacy DVB MPEG Decoder APIs
+============================
+
+.. _legacy_dvb_decoder_notes:
+
+General Notes
+=============
+
+This API has originally been designed for DVB only and is therefore limited to
+the :ref:`legacy_dvb_decoder_formats` used in such digital TV-broadcastsystems.
+
+To circumvent this limitations the more versatile :ref:`V4L2 <v4l2spec>` API has
+been designed. Which replaces this part of the DVB API.
+
+Nevertheless there have been projects build around this API.
+To ensure compatibility this API is kept as it is.
+
+.. attention:: Do **not** use this API in new drivers!
+
+    For audio and video use the :ref:`V4L2 <v4l2spec>` and ALSA APIs.
+
+    Pipelines should be set up using the :ref:`Media Controller  API<media_controller>`.
+
+Practically the decoders seem to be treated differently. The application typically
+knows which decoder is in use or it is specially written for one decoder type.
+Querying capabilities are rarely used because they are already known.
+
+.. _legacy_dvb_decoder_formats:
+
+Data Formats
+============
+
+The API has been designed for DVB and compatible broadcastsystems.
+Because of that fact the only supported data formats are ISO/IEC 13818-1
+compatible MPEG streams. The supported payloads may vary depending on the
+used decoder.
+
+Timestamps are always MPEG PTS as defined in ITU T-REC-H.222.0 /
+ISO/IEC 13818-1, if not otherwise noted.
+
+For storing recordings typically TS streams are used, in lesser extent PES.
+Both variants are commonly accepted for playback, but it may be driver dependent.
+
+
+
+
+Table of Contents
+=================
+
+.. toctree::
+    :maxdepth: 2
+
+    legacy_dvb_video
+    legacy_dvb_audio
+    legacy_dvb_osd
+
diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst
new file mode 100644
index 000000000000..a067cc0b3f2f
--- /dev/null
+++ b/Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst
@@ -0,0 +1,436 @@
+.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+
+.. _dvb_osd:
+
+==============
+DVB OSD Device
+==============
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+The DVB OSD Device controls the OnScreenDisplay of the AV7110 based
+DVB-cards with hardware MPEG2 decoder. It can be accessed through ``/dev/dvb/adapter?/osd0``.
+Data types and ioctl definitions can be accessed by including
+``linux/dvb/osd.h`` in your application.
+
+The OSD is not a framebuffer like on many other cards.
+It is a kind of canvas one can draw on.
+The colordepth is limited depending on the memorysize installed. An appropriate palette
+of colors has to be set up.
+The installed memory size can be identified with the `OSD_GET_CAPABILITY`_ ioctl.
+
+OSD Data Types
+==============
+
+OSD_Command
+-----------
+
+The ``OSD_Command`` data type defined by
+
+.. code-block:: c
+
+    typedef enum {
+	/* All functions return -2 on "not open" */
+	OSD_Close = 1,	/* () */
+	/*
+	 * Disables OSD and releases the buffers
+	 * returns 0 on success
+	 */
+	OSD_Open,	/* (x0,y0,x1,y1,BitPerPixel[2/4/8](color&0x0F),mix[0..15](color&0xF0)) */
+	/*
+	 * Opens OSD with this size and bit depth
+	 * returns 0 on success, -1 on DRAM allocation error, -2 on "already open"
+	 */
+	OSD_Show,	/* () */
+	/*
+	 * enables OSD mode
+	 * returns 0 on success
+	 */
+	OSD_Hide,	/* () */
+	/*
+	 * disables OSD mode
+	 * returns 0 on success
+	 */
+	OSD_Clear,	/* () */
+	/*
+	 * Sets all pixel to color 0
+	 * returns 0 on success
+	 */
+	OSD_Fill,	/* (color) */
+	/*
+	 * Sets all pixel to color <col>
+	 * returns 0 on success
+	 */
+	OSD_SetColor,	/* (color,R{x0},G{y0},B{x1},opacity{y1}) */
+	/*
+	 * set palette entry <num> to <r,g,b>, <mix> and <trans> apply
+	 * R,G,B: 0..255
+	 * R=Red, G=Green, B=Blue
+	 * opacity=0:      pixel opacity 0% (only video pixel shows)
+	 * opacity=1..254: pixel opacity as specified in header
+	 * opacity=255:    pixel opacity 100% (only OSD pixel shows)
+	 * returns 0 on success, -1 on error
+	 */
+	OSD_SetPalette,	/* (firstcolor{color},lastcolor{x0},data) */
+	/*
+	 * Set a number of entries in the palette
+	 * sets the entries "firstcolor" through "lastcolor" from the array "data"
+	 * data has 4 byte for each color:
+	 * R,G,B, and a opacity value: 0->transparent, 1..254->mix, 255->pixel
+	 */
+	OSD_SetTrans,	/* (transparency{color}) */
+	/*
+	 * Sets transparency of mixed pixel (0..15)
+	 * returns 0 on success
+	 */
+	OSD_SetPixel,	/* (x0,y0,color) */
+	/*
+	 * sets pixel <x>,<y> to color number <col>
+	 * returns 0 on success, -1 on error
+	 */
+	OSD_GetPixel,	/* (x0,y0) */
+	/* returns color number of pixel <x>,<y>,  or -1 */
+	OSD_SetRow,	/* (x0,y0,x1,data) */
+	/*
+	 * fills pixels x0,y through  x1,y with the content of data[]
+	 * returns 0 on success, -1 on clipping all pixel (no pixel drawn)
+	 */
+	OSD_SetBlock,	/* (x0,y0,x1,y1,increment{color},data) */
+	/*
+	 * fills pixels x0,y0 through  x1,y1 with the content of data[]
+	 * inc contains the width of one line in the data block,
+	 * inc<=0 uses blockwidth as linewidth
+	 * returns 0 on success, -1 on clipping all pixel
+	 */
+	OSD_FillRow,	/* (x0,y0,x1,color) */
+	/*
+	 * fills pixels x0,y through  x1,y with the color <col>
+	 * returns 0 on success, -1 on clipping all pixel
+	 */
+	OSD_FillBlock,	/* (x0,y0,x1,y1,color) */
+	/*
+	 * fills pixels x0,y0 through  x1,y1 with the color <col>
+	 * returns 0 on success, -1 on clipping all pixel
+	 */
+	OSD_Line,	/* (x0,y0,x1,y1,color) */
+	/*
+	 * draw a line from x0,y0 to x1,y1 with the color <col>
+	 * returns 0 on success
+	 */
+	OSD_Query,	/* (x0,y0,x1,y1,xasp{color}}), yasp=11 */
+	/*
+	 * fills parameters with the picture dimensions and the pixel aspect ratio
+	 * returns 0 on success
+	 */
+	OSD_Test,       /* () */
+	/*
+	 * draws a test picture. for debugging purposes only
+	 * returns 0 on success
+	 * TODO: remove "test" in final version
+	 */
+	OSD_Text,	/* (x0,y0,size,color,text) */
+	OSD_SetWindow,	/* (x0) set window with number 0<x0<8 as current */
+	OSD_MoveWindow,	/* move current window to (x0, y0) */
+	OSD_OpenRaw,	/* Open other types of OSD windows */
+    } OSD_Command;
+
+is used with the `OSD_SEND_CMD`_ ioctl to tell the driver which OSD_Command to execute.
+
+osd_cmd_t
+---------
+
+The ``osd_cmd_t`` data type defined by
+
+.. code-block:: c
+
+    typedef struct osd_cmd_s {
+	OSD_Command cmd;
+	int x0;
+	int y0;
+	int x1;
+	int y1;
+	int color;
+	void __user *data;
+    } osd_cmd_t;
+
+is used with the `OSD_SEND_CMD`_ ioctl.
+It contains the data for the OSD_Command and the `OSD_Command`_ itself.
+
+
+osd_raw_window_t
+----------------
+
+The ``osd_raw_window_t`` data type defined by
+
+.. code-block:: c
+
+    /* OSD_OpenRaw: set 'color' to desired window type */
+    typedef enum {
+	OSD_BITMAP1,           /* 1 bit bitmap */
+	OSD_BITMAP2,           /* 2 bit bitmap */
+	OSD_BITMAP4,           /* 4 bit bitmap */
+	OSD_BITMAP8,           /* 8 bit bitmap */
+	OSD_BITMAP1HR,         /* 1 Bit bitmap half resolution */
+	OSD_BITMAP2HR,         /* 2 bit bitmap half resolution */
+	OSD_BITMAP4HR,         /* 4 bit bitmap half resolution */
+	OSD_BITMAP8HR,         /* 8 bit bitmap half resolution */
+	OSD_YCRCB422,          /* 4:2:2 YCRCB Graphic Display */
+	OSD_YCRCB444,          /* 4:4:4 YCRCB Graphic Display */
+	OSD_YCRCB444HR,        /* 4:4:4 YCRCB graphic half resolution */
+	OSD_VIDEOTSIZE,        /* True Size Normal MPEG Video Display */
+	OSD_VIDEOHSIZE,        /* MPEG Video Display Half Resolution */
+	OSD_VIDEOQSIZE,        /* MPEG Video Display Quarter Resolution */
+	OSD_VIDEODSIZE,        /* MPEG Video Display Double Resolution */
+	OSD_VIDEOTHSIZE,       /* True Size MPEG Video Display Half Resolution */
+	OSD_VIDEOTQSIZE,       /* True Size MPEG Video Display Quarter Resolution*/
+	OSD_VIDEOTDSIZE,       /* True Size MPEG Video Display Double Resolution */
+	OSD_VIDEONSIZE,        /* Full Size MPEG Video Display */
+	OSD_CURSOR             /* Cursor */
+    } osd_raw_window_t;
+
+is used to tell the `OSD_Command`_ OSD_OpenRaw which type of OSD to open.
+
+osd_cap_t
+---------
+
+The following is the structure of data returned by the `OSD_GET_CAPABILITY`_ call.
+
+The ``osd_cap_t`` data type defined by
+
+.. code-block:: c
+
+    typedef struct osd_cap_s {
+	int  cmd;
+    #define OSD_CAP_MEMSIZE         1  /* memory size */
+	long val;
+    } osd_cap_t;
+
+OSD Function Calls
+==================
+
+OSD_SEND_CMD
+------------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int ioctl(int fd, int request = OSD_SEND_CMD, enum osd_cmd_t *cmd)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals `osd_cmd_t`_ for this command.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl sends the `OSD_Command`_ to the card.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+OSD_GET_CAPABILITY
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int ioctl(int fd, int request = OSD_GET_CAPABILITY, struct osd_cap_t *cap)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals OSD_GET_CAPABILITY for this command.
+
+    -  .. row 3
+
+       -  unsigned int \*cap
+
+       -  Pointer to a location where to store the capability information.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is used to get the capabilities of the OSD of the AV7110 based DVB-decoder-card in use.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+open()
+------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int open(const char *deviceName, int flags)
+   :name: LEGACY_DVB_OSD_OPEN
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  const char \*deviceName
+
+       -  Name of specific OSD device.
+
+    -  .. row 2
+
+       -  int flags
+
+       -  A bit-wise OR of the following flags:
+
+    -  .. row 3
+
+       -
+       -  O_RDONLY read-only access
+
+    -  .. row 4
+
+       -
+       -  O_RDWR read/write access
+
+    -  .. row 5
+
+       -
+       -  O_NONBLOCK open in non-blocking mode
+
+
+Description
+~~~~~~~~~~~
+
+This system call opens a named OSD device (e.g.
+/dev/dvb/adapter?/osd0) for subsequent use.
+
+
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  ``ENODEV``
+
+       -  Device driver not loaded/available.
+
+    -  .. row 2
+
+       -  ``EINTERNAL``
+
+       -  Internal error.
+
+    -  .. row 3
+
+       -  ``EBUSY``
+
+       -  Device or resource busy.
+
+    -  .. row 4
+
+       -  ``EINVAL``
+
+       -  Invalid argument.
+
+close()
+-------
+
+Synopsis
+~~~~~~~~
+
+.. cpp:function:: int close(int fd)
+   :name: LEGACY_DVB_OSD_CLOSE
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_ .
+
+
+Description
+~~~~~~~~~~~
+
+This system call closes a previously opened OSD device.
+
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  ``EBADF``
+
+       -  fd is not a valid open file descriptor.
+
diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst
new file mode 100644
index 000000000000..92ab2122ba23
--- /dev/null
+++ b/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst
@@ -0,0 +1,1720 @@
+.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+
+.. _dvb_video:
+
+================
+DVB Video Device
+================
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+The DVB video device controls the MPEG2 video decoder of the DVB
+hardware. It can be accessed through ``/dev/dvb/adapter0/video0``. Data
+types and ioctl definitions can be accessed by including
+``linux/dvb/video.h`` in your application.
+
+Note that the DVB video device only controls decoding of the MPEG video
+stream, not its presentation on the TV or computer screen. On PCs this
+is typically handled by an associated video4linux device, e.g.
+``/dev/video``, which allows scaling and defining output windows.
+
+Most DVB cards don’t have their own MPEG decoder, which results in the
+omission of the audio and video device as well as the video4linux
+device.
+
+These ioctls were also used by V4L2 to control MPEG decoders implemented
+in V4L2. The use of these ioctls for that purpose has been made obsolete
+and proper V4L2 ioctls or controls have been created to replace that
+functionality. Use :ref:`V4L2 ioctls<video>` for new drivers!
+
+
+Video Data Types
+================
+
+
+video_format_t
+--------------
+
+The ``video_format_t`` data type defined by
+
+
+.. code-block:: c
+
+    typedef enum {
+	VIDEO_FORMAT_4_3,     /* Select 4:3 format */
+	VIDEO_FORMAT_16_9,    /* Select 16:9 format. */
+	VIDEO_FORMAT_221_1    /* 2.21:1 */
+    } video_format_t;
+
+is used in the `VIDEO_SET_FORMAT`_ function to tell the driver which
+aspect ratio the output hardware (e.g. TV) has. It is also used in the
+data structures `video_status`_ returned by `VIDEO_GET_STATUS`_
+and `video_event`_ returned by `VIDEO_GET_EVENT`_ which report
+about the display format of the current video stream.
+
+
+video_displayformat_t
+---------------------
+
+In case the display format of the video stream and of the display
+hardware differ the application has to specify how to handle the
+cropping of the picture. This can be done using the
+`VIDEO_SET_DISPLAY_FORMAT`_ call which accepts
+
+
+.. code-block:: c
+
+    typedef enum {
+	VIDEO_PAN_SCAN,       /* use pan and scan format */
+	VIDEO_LETTER_BOX,     /* use letterbox format */
+	VIDEO_CENTER_CUT_OUT  /* use center cut out format */
+    } video_displayformat_t;
+
+as argument.
+
+
+video_size_t
+------------
+
+Used in the struct `video_event`_. It stores the resolution and
+aspect ratio of the video.
+
+.. code-block:: c
+
+    typedef struct {
+	int w;
+	int h;
+	video_format_t aspect_ratio;
+    } video_size_t;
+
+
+video_stream_source_t
+---------------------
+
+The video stream source is set through the `VIDEO_SELECT_SOURCE`_ call
+and can take the following values, depending on whether we are replaying
+from an internal (demuxer) or external (user write) source.
+
+
+.. code-block:: c
+
+    typedef enum {
+	VIDEO_SOURCE_DEMUX, /* Select the demux as the main source */
+	VIDEO_SOURCE_MEMORY /* If this source is selected, the stream
+		       comes from the user through the write
+		       system call */
+    } video_stream_source_t;
+
+VIDEO_SOURCE_DEMUX selects the demultiplexer (fed either by the
+frontend or the DVR device) as the source of the video stream. If
+VIDEO_SOURCE_MEMORY is selected the stream comes from the application
+through the `write()`_ system call.
+
+
+video_play_state_t
+------------------
+
+The following values can be returned by the `VIDEO_GET_STATUS`_ call
+representing the state of video playback.
+
+
+.. code-block:: c
+
+    typedef enum {
+	VIDEO_STOPPED, /* Video is stopped */
+	VIDEO_PLAYING, /* Video is currently playing */
+	VIDEO_FREEZED  /* Video is freezed */
+    } video_play_state_t;
+
+
+struct video_command
+--------------------
+
+The structure must be zeroed before use by the application. This ensures
+it can be extended safely in the future.
+
+
+.. code-block:: c
+
+    struct video_command {
+	__u32 cmd;
+	__u32 flags;
+	union {
+	    struct {
+		__u64 pts;
+	    } stop;
+
+	    struct {
+		/* 0 or 1000 specifies normal speed,
+		   1 specifies forward single stepping,
+		   -1 specifies backward single stepping,
+		   >>1: playback at speed/1000 of the normal speed,
+		   <-1: reverse playback at (-speed/1000) of the normal speed. */
+		__s32 speed;
+		__u32 format;
+	    } play;
+
+	    struct {
+		__u32 data[16];
+	    } raw;
+	};
+    };
+
+
+Predefined decoder commands and flags:
+
+.. code-block:: c
+
+    /* Decoder commands */
+    #define VIDEO_CMD_PLAY        (0)
+    #define VIDEO_CMD_STOP        (1)
+    #define VIDEO_CMD_FREEZE      (2)
+    #define VIDEO_CMD_CONTINUE    (3)
+
+    /* Flags for VIDEO_CMD_FREEZE */
+    #define VIDEO_CMD_FREEZE_TO_BLACK	(1 << 0)
+
+    /* Flags for VIDEO_CMD_STOP */
+    #define VIDEO_CMD_STOP_TO_BLACK	(1 << 0)
+    #define VIDEO_CMD_STOP_IMMEDIATELY	(1 << 1)
+
+    /* Play input formats: */
+    /* The decoder has no special format requirements */
+    #define VIDEO_PLAY_FMT_NONE         (0)
+    /* The decoder requires full GOPs */
+    #define VIDEO_PLAY_FMT_GOP          (1)
+
+    /* FIELD_UNKNOWN can be used if the hardware does not know whether
+    the Vsync is for an odd, even or progressive (i.e. non-interlaced)
+    field. */
+    #define VIDEO_VSYNC_FIELD_UNKNOWN		(0)
+    #define VIDEO_VSYNC_FIELD_ODD		(1)
+    #define VIDEO_VSYNC_FIELD_EVEN		(2)
+    #define VIDEO_VSYNC_FIELD_PROGRESSIVE	(3)
+
+
+
+video_event
+-----------
+
+The following is the structure of a video event as it is returned by the
+`VIDEO_GET_EVENT`_ call.
+
+
+.. code-block:: c
+
+    struct video_event {
+	__s32 type;
+    #define VIDEO_EVENT_SIZE_CHANGED        1
+    #define VIDEO_EVENT_FRAME_RATE_CHANGED  2
+    #define VIDEO_EVENT_DECODER_STOPPED     3
+    #define VIDEO_EVENT_VSYNC               4
+	long timestamp;                 /* MPEG PTS */
+	union {
+	    video_size_t size;
+	    unsigned int frame_rate;    /* in frames per 1000sec */
+	    unsigned char vsync_field;  /* unknown/odd/even/progressive */
+	} u;
+    };
+
+
+video_status
+------------
+
+The `VIDEO_GET_STATUS`_ call returns the following structure informing
+about various states of the playback operation.
+
+
+.. code-block:: c
+
+    struct video_status {
+	int                   video_blank;   /* blank video on freeze? */
+	video_play_state_t    play_state;    /* current state of playback */
+	video_stream_source_t stream_source; /* current source (demux/memory) */
+	video_format_t        video_format;  /* current aspect ratio of stream */
+	video_displayformat_t display_format;/* applied cropping mode */
+    };
+
+If video_blank is set video will be blanked out if the channel is
+changed or if playback is stopped. Otherwise, the last picture will be
+displayed. play_state indicates if the video is currently frozen,
+stopped, or being played back. The stream_source corresponds to the
+selected source for the video stream. It can come either from the
+demultiplexer or from memory. The video_format indicates the aspect
+ratio (one of 4:3 or 16:9) of the currently played video stream.
+Finally, display_format corresponds to the applied cropping mode in
+case the source video format is not the same as the format of the output
+device.
+
+
+video_still_picture
+-------------------
+
+An I-frame displayed via the `VIDEO_STILLPICTURE`_ call is passed on
+within the following structure.
+
+
+.. code-block:: c
+
+    /* pointer to and size of a single iframe in memory */
+    struct video_still_picture {
+    char *iFrame;        /* pointer to a single iframe in memory */
+    int32_t size;
+    };
+
+
+video capabilities
+------------------
+
+A call to `VIDEO_GET_CAPABILITIES`_ returns an unsigned integer with the
+following bits set according to the hardwares capabilities.
+
+
+.. code-block:: c
+
+    /* bit definitions for capabilities: */
+    /* can the hardware decode MPEG1 and/or MPEG2? */
+    #define VIDEO_CAP_MPEG1   1
+    #define VIDEO_CAP_MPEG2   2
+    /* does the video device accept system and/or program stream?
+    (you still have to open the video and the audio device
+    but only send the stream to the video device) */
+    #define VIDEO_CAP_SYS     4
+    #define VIDEO_CAP_PROG    8
+
+
+Video Function Calls
+====================
+
+
+VIDEO_STOP
+----------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int ioctl(fd, VIDEO_STOP, boolean mode)
+   :name: LEGACY_DVB_VIDEO_STOP
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_STOP for this command.
+
+    -  .. row 3
+
+       -  Boolean mode
+
+       -  Indicates how the screen shall be handled.
+
+    -  .. row 4
+
+       -
+       -  TRUE: Blank screen when stop.
+
+    -  .. row 5
+
+       -
+       -  FALSE: Show last decoded frame.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for Digital TV devices only. To control a V4L2 decoder use the
+V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
+
+This ioctl call asks the Video Device to stop playing the current
+stream. Depending on the input parameter, the screen can be blanked out
+or displaying the last decoded frame.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_PLAY
+----------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int ioctl(fd, VIDEO_PLAY)
+   :name: LEGACY_DVB_VIDEO_PLAY
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_PLAY for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for Digital TV devices only. To control a V4L2 decoder use the
+V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
+
+This ioctl call asks the Video Device to start playing a video stream
+from the selected source.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_FREEZE
+------------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int ioctl(fd, VIDEO_FREEZE)
+   :name: LEGACY_DVB_VIDEO_FREEZE
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_FREEZE for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for Digital TV devices only. To control a V4L2 decoder use the
+V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
+
+This ioctl call suspends the live video stream being played. Decoding
+and playing are frozen. It is then possible to restart the decoding and
+playing process of the video stream using the `VIDEO_CONTINUE`_ command.
+If VIDEO_SOURCE_MEMORY is selected in the ioctl call
+`VIDEO_SELECT_SOURCE`_, the Digital TV subsystem will not decode any more data
+until the ioctl call `VIDEO_CONTINUE`_ or `VIDEO_PLAY`_ is performed.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_CONTINUE
+--------------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int ioctl(fd, VIDEO_CONTINUE)
+   :name: LEGACY_DVB_VIDEO_CONTINUE
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_CONTINUE for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for Digital TV devices only. To control a V4L2 decoder use the
+V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
+
+This ioctl call restarts decoding and playing processes of the video
+stream which was played before a call to `VIDEO_FREEZE`_ was made.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_SELECT_SOURCE
+-------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int ioctl(fd, VIDEO_SELECT_SOURCE, video_stream_source_t source)
+   :name: LEGACY_DVB_VIDEO_SELECT_SOURCE
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_SELECT_SOURCE for this command.
+
+    -  .. row 3
+
+       -  `video_stream_source_t`_ source
+
+       -  Indicates which source shall be used for the Video stream.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for Digital TV devices only. This ioctl was also supported by the
+V4L2 ivtv driver, but that has been replaced by the ivtv-specific
+``IVTV_IOC_PASSTHROUGH_MODE`` ioctl.
+
+This ioctl call informs the video device which source shall be used for
+the input data. The possible sources are demux or memory. If memory is
+selected, the data is fed to the video device through the write command
+using the struct `video_stream_source_t`_.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_SET_BLANK
+---------------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int ioctl(fd, VIDEO_SET_BLANK, boolean mode)
+   :name: LEGACY_DVB_VIDEO_SET_BLANK
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_SET_BLANK for this command.
+
+    -  .. row 3
+
+       -  boolean mode
+
+       -  TRUE: Blank screen when stop.
+
+    -  .. row 4
+
+       -
+       -  FALSE: Show last decoded frame.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Video Device to blank out the picture.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_GET_STATUS
+----------------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int ioctl(fd, int request = VIDEO_GET_STATUS, struct video_status *status)
+   :name: LEGACY_DVB_VIDEO_GET_STATUS
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_GET_STATUS for this command.
+
+    -  .. row 3
+
+       -  struct `video_status`_ \*status
+
+       -  Returns the current status of the Video Device.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Video Device to return the current status of
+the device.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_GET_EVENT
+---------------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int ioctl(fd, int request = VIDEO_GET_EVENT, struct video_event *ev)
+   :name: LEGACY_DVB_VIDEO_GET_EVENT
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_GET_EVENT for this command.
+
+    -  .. row 3
+
+       -  struct `video_event`_ \*ev
+
+       -  Points to the location where the event, if any, is to be stored.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for DVB devices only. To get events from a V4L2 decoder
+use the V4L2 :ref:`VIDIOC_DQEVENT` ioctl instead.
+
+This ioctl call returns an event of type `video_event`_ if available. If
+an event is not available, the behavior depends on whether the device is
+in blocking or non-blocking mode. In the latter case, the call fails
+immediately with errno set to ``EWOULDBLOCK``. In the former case, the call
+blocks until an event becomes available. The standard Linux poll()
+and/or select() system calls can be used with the device file descriptor
+to watch for new events. For select(), the file descriptor should be
+included in the exceptfds argument, and for poll(), POLLPRI should be
+specified as the wake-up condition. Read-only permissions are sufficient
+for this ioctl call.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  ``EWOULDBLOCK``
+
+       -  There is no event pending, and the device is in non-blocking mode.
+
+    -  .. row 2
+
+       -  ``EOVERFLOW``
+
+       -  Overflow in event queue - one or more events were lost.
+
+
+VIDEO_SET_DISPLAY_FORMAT
+------------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int ioctl(fd, int request = VIDEO_SET_DISPLAY_FORMAT, video_display_format_t format)
+   :name: LEGACY_DVB_VIDEO_DISPLAY_FORMAT
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_SET_DISPLAY_FORMAT for this command.
+
+    -  .. row 3
+
+       -  `video_displayformat_t`_ format
+
+       -  Selects the video format to be used.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Video Device to select the video format to be
+applied by the MPEG chip on the video.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_STILLPICTURE
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int ioctl(fd, int request = VIDEO_STILLPICTURE, struct video_still_picture *sp)
+   :name: LEGACY_DVB_VIDEO_STILLPICTURE
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_STILLPICTURE for this command.
+
+    -  .. row 3
+
+       -  struct `video_still_picture`_ \*sp
+
+       -  Pointer to a location where an I-frame and size is stored.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Video Device to display a still picture
+(I-frame). The input data shall contain an I-frame. If the pointer is
+NULL, then the current displayed still picture is blanked.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_FAST_FORWARD
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int ioctl(fd, int request = VIDEO_FAST_FORWARD, int nFrames)
+   :name: LEGACY_DVB_VIDEO_SLOWMOTION
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_FAST_FORWARD for this command.
+
+    -  .. row 3
+
+       -  int nFrames
+
+       -  The number of frames to skip.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Video Device to skip decoding of N number of
+I-frames. This call can only be used if VIDEO_SOURCE_MEMORY is
+selected.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  ``EPERM``
+
+       -  Mode VIDEO_SOURCE_MEMORY not selected.
+
+
+VIDEO_SLOWMOTION
+----------------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int ioctl(fd, int request = VIDEO_SLOWMOTION, int nFrames)
+   :name: LEGACY_DVB_VIDEO_SLOWMOTION
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_SLOWMOTION for this command.
+
+    -  .. row 3
+
+       -  int nFrames
+
+       -  The number of times to repeat each frame.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the video device to repeat decoding frames N number
+of times. This call can only be used if VIDEO_SOURCE_MEMORY is
+selected.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  ``EPERM``
+
+       -  Mode VIDEO_SOURCE_MEMORY not selected.
+
+
+VIDEO_GET_CAPABILITIES
+----------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int ioctl(fd, int request = VIDEO_GET_CAPABILITIES, unsigned int *cap)
+   :name: LEGACY_DVB_VIDEO_GET_CAPABILITIES
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_GET_CAPABILITIES for this command.
+
+    -  .. row 3
+
+       -  unsigned int \*cap
+
+       -  Pointer to a location where to store the capability information.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the video device about its decoding capabilities.
+On success it returns and integer which has bits set according to the
+defines in section ??.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_CLEAR_BUFFER
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int ioctl(fd, int request = VIDEO_CLEAR_BUFFER)
+   :name: LEGACY_DVB_VIDEO_CLEAR_BUFFER
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_CLEAR_BUFFER for this command.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call clears all video buffers in the driver and in the
+decoder hardware.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_SET_STREAMTYPE
+--------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int ioctl(fd, int request = VIDEO_SET_STREAMTYPE, int type)
+   :name: LEGACY_DVB_VIDEO_SET_STREAMTYPE
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_SET_STREAMTYPE for this command.
+
+    -  .. row 3
+
+       -  int type
+
+       -  stream type
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl tells the driver which kind of stream to expect being written
+to it. If this call is not used the default of video PES is used. Some
+drivers might not support this call and always expect PES.
+Intelligent decoder might also not support or ignore this call and
+determine the streamtype themselves.
+
+.. note:: See: :ref:`DVB Data Formats <legacy_dvb_decoder_formats>`
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_SET_FORMAT
+----------------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int ioctl(fd, int request = VIDEO_SET_FORMAT, video_format_t format)
+   :name: LEGACY_DVB_VIDEO_SET_FORMAT
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_SET_FORMAT for this command.
+
+    -  .. row 3
+
+       -  `video_format_t`_ format
+
+       -  video format of TV as defined in section ??.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl sets the screen format (aspect ratio) of the connected output
+device (TV) so that the output of the decoder can be adjusted
+accordingly.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_GET_SIZE
+--------------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int ioctl(int fd, int request = VIDEO_GET_SIZE, video_size_t *size)
+   :name: LEGACY_DVB_VIDEO_GET_SIZE
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_GET_SIZE for this command.
+
+    -  .. row 3
+
+       -  `video_size_t`_ \*size
+
+       -  Returns the size and aspect ratio.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl returns the size and aspect ratio.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_GET_PTS
+-------------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int ioctl(int fd, int request = VIDEO_GET_PTS, __u64 *pts)
+   :name: LEGACY_DVB_VIDEO_GET_PTS
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_GET_PTS for this command.
+
+    -  .. row 3
+
+       -  __u64 \*pts
+
+       -  Returns the 33-bit timestamp as defined in ITU T-REC-H.222.0 /
+	  ISO/IEC 13818-1.
+
+	  The PTS should belong to the currently played frame if possible,
+	  but may also be a value close to it like the PTS of the last
+	  decoded frame or the last PTS extracted by the PES parser.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+For V4L2 decoders this ioctl has been replaced by the
+``V4L2_CID_MPEG_VIDEO_DEC_PTS`` control.
+
+This ioctl call asks the Video Device to return the current PTS
+timestamp.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_GET_FRAME_RATE
+--------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int ioctl(int fd, int request = VIDEO_GET_FRAME_RATE, unsigned int *rate)
+   :name: LEGACY_DVB_VIDEO_GET_FRAME_RATE
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_GET_FRAME_RATE for this command.
+
+    -  .. row 3
+
+       -  unsigned int \*rate
+
+       -  Returns the framerate in number of frames per 1000 seconds.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Video Device to return the current framerate.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_COMMAND
+-------------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int ioctl(int fd, int request = VIDEO_COMMAND, struct video_command *cmd)
+   :name: LEGACY_DVB_VIDEO_COMMAND
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_COMMAND for this command.
+
+    -  .. row 3
+
+       -  `struct video_command`_ \*cmd
+
+       -  Commands the decoder.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+For V4L2 decoders this ioctl has been replaced by the
+:ref:`VIDIOC_DECODER_CMD` ioctl.
+
+This ioctl commands the decoder. The `struct video_command`_ is a
+subset of the ``v4l2_decoder_cmd`` struct, so refer to the
+:ref:`VIDIOC_DECODER_CMD` documentation for
+more information.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_TRY_COMMAND
+-----------------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int ioctl(int fd, int request = VIDEO_TRY_COMMAND, struct video_command *cmd)
+   :name: LEGACY_DVB_VIDEO_TRY_COMMAND
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_TRY_COMMAND for this command.
+
+    -  .. row 3
+
+       -  `struct video_command`_ \*cmd
+
+       -  Try a decoder command.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+For V4L2 decoders this ioctl has been replaced by the
+:ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` ioctl.
+
+This ioctl tries a decoder command. The `struct video_command`_ is a
+subset of the ``v4l2_decoder_cmd`` struct, so refer to the
+:ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` documentation
+for more information.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+open()
+------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int open(const char *deviceName, int flags)
+   :name: LEGACY_DVB_VIDEO_OPEN
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  const char \*deviceName
+
+       -  Name of specific video device.
+
+    -  .. row 2
+
+       -  int flags
+
+       -  A bit-wise OR of the following flags:
+
+    -  .. row 3
+
+       -
+       -  O_RDONLY read-only access
+
+    -  .. row 4
+
+       -
+       -  O_RDWR read/write access
+
+    -  .. row 5
+
+       -
+       -  O_NONBLOCK open in non-blocking mode
+
+    -  .. row 6
+
+       -
+       -  (blocking mode is the default)
+
+
+Description
+~~~~~~~~~~~
+
+This system call opens a named video device (e.g.
+/dev/dvb/adapter?/video?) for subsequent use.
+
+When an open() call has succeeded, the device will be ready for use. The
+significance of blocking or non-blocking mode is described in the
+documentation for functions where there is a difference. It does not
+affect the semantics of the open() call itself. A device opened in
+blocking mode can later be put into non-blocking mode (and vice versa)
+using the F_SETFL command of the fcntl system call. This is a standard
+system call, documented in the Linux manual page for fcntl. Only one
+user can open the Video Device in O_RDWR mode. All other attempts to
+open the device in this mode will fail, and an error-code will be
+returned. If the Video Device is opened in O_RDONLY mode, the only
+ioctl call that can be used is `VIDEO_GET_STATUS`_. All other call will
+return an error code.
+
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  ``ENODEV``
+
+       -  Device driver not loaded/available.
+
+    -  .. row 2
+
+       -  ``EINTERNAL``
+
+       -  Internal error.
+
+    -  .. row 3
+
+       -  ``EBUSY``
+
+       -  Device or resource busy.
+
+    -  .. row 4
+
+       -  ``EINVAL``
+
+       -  Invalid argument.
+
+
+close()
+-------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int close(int fd)
+   :name: LEGACY_DVB_VIDEO_CLOSE
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+
+Description
+~~~~~~~~~~~
+
+This system call closes a previously opened video device.
+
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  ``EBADF``
+
+       -  fd is not a valid open file descriptor.
+
+
+write()
+-------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: size_t write(int fd, const void *buf, size_t count)
+   :name: LEGACY_DVB_VIDEO_WRITE
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  void \*buf
+
+       -  Pointer to the buffer containing the PES data.
+
+    -  .. row 3
+
+       -  size_t count
+
+       -  Size of buf.
+
+
+Description
+~~~~~~~~~~~
+
+This system call can only be used if VIDEO_SOURCE_MEMORY is selected
+in the ioctl call `VIDEO_SELECT_SOURCE`_. The data provided shall be in
+PES format, unless the capability allows other formats. TS is the
+most common format for storing DVB-data, it is usually supported too.
+If O_NONBLOCK is not specified the function will block until buffer space
+is available. The amount of data to be transferred is implied by count.
+
+.. note:: See: :ref:`DVB Data Formats <legacy_dvb_decoder_formats>`
+
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  ``EPERM``
+
+       -  Mode VIDEO_SOURCE_MEMORY not selected.
+
+    -  .. row 2
+
+       -  ``ENOMEM``
+
+       -  Attempted to write more data than the internal buffer can hold.
+
+    -  .. row 3
+
+       -  ``EBADF``
+
+       -  fd is not a valid open file descriptor.

Re: [PATCH] Legacy DVB API: completion of documentation

[kernel test robot]

Hi Stefan,

Thank you for the patch! Perhaps something to improve:

[auto build test WARNING on media-tree/master]
[also build test WARNING on linus/master v6.3-rc3 next-20230324]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]

url:    https://github.com/intel-lab-lkp/linux/commits/Stefan-Herdler/Legacy-DVB-API-completion-of-documentation/20230325-094623
base:   git://linuxtv.org/media_tree.git master
patch link:    https://lore.kernel.org/r/50f69514-abbb-2dfb-6060-889aa2c6e02c%40nurfuerspam.de
patch subject: [PATCH] Legacy DVB API: completion of documentation
reproduce:
        # https://github.com/intel-lab-lkp/linux/commit/1dee8a08e2a818066aa1453a7370685deb3a5786
        git remote add linux-review https://github.com/intel-lab-lkp/linux
        git fetch --no-tags linux-review Stefan-Herdler/Legacy-DVB-API-completion-of-documentation/20230325-094623
        git checkout 1dee8a08e2a818066aa1453a7370685deb3a5786
        make menuconfig
        # enable CONFIG_COMPILE_TEST, CONFIG_WARN_MISSING_DOCUMENTS, CONFIG_WARN_ABI_ERRORS
        make htmldocs

If you fix the issue, kindly add following tag where applicable
| Reported-by: kernel test robot <lkp@intel.com>
| Link: https://lore.kernel.org/oe-kbuild-all/202303251637.x35nzuXi-lkp@intel.com/

All warnings (new ones prefixed by >>):

>> Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst:155: WARNING: Error in "cpp:function" directive:
>> Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst:399: WARNING: Error in "cpp:function" directive:

vim +155 Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst

   154	
 > 155	.. cpp:function:: int ioctl(int fd, int request = AUDIO_STOP)
   156	   :name: LEGACY_DVB_AUDIO_STOP
   157	

-- 
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests

[PATCH v2] Legacy DVB API: completion of documentation

[Stefan Herdler]

On 25/03/23 02:44, Stefan Herdler wrote:
> Hi Mauro and Hans,
>
> it took a little longer then anticipated, but I think I was able to fill the gaps in the documentation.
> At least everything in the header-files is in the documentation now. I hope, I have done it sufficiently.
>
> Some remarks:
>
> I considered the existing documentation to be trustworthy.
> Existing things like returntypes, errnos, ... haven't been touched by me.
> There are only a few minor modifications to reflect the data formats actually used for playback.
>
> The documentation has been merged into one file per header-file. Entries have been sorted equally.
> For me it is much better arranged this way, the mass of different files where just to confusing and the
> original files have already been removed anyway.
> But I may revert that if necessary.
>
> Title and chapter-styles has been changed to the suggested ones in "/doc-guide/sphinx.html#writing-documentation".
>
> There are still some "Duplicate C++ declaration, ..." warnings. Renaming doesn't work either: 'unknown option: "name"'
> I haven't found any useful hint how to get rid of them.
> Should I switch to "code-block:: c" instead?
> But there are a lot of this warnings from other files too. It seems I'm mot the only one with this problem.
I switched to "code-block".
Now there are no warnings anymore.

This functions shouldn't be referenced from outside this document anyway.


Lets hope, the robot likes it better this way :-).

Regards
Stefan

>
>
> Please point out, if something is missing, wrong or need to be improved. I will try to fix it.
>
> Regards
> Stefan
>
> p.s. It is my first try to submit a patch this way. I hope my mail-client doesn't mess it up.
>


This patch is largely based on the already existing documentation and the header files


| Reported-by: kernel test robot <lkp@intel.com>
| Link: https://lore.kernel.org/oe-kbuild-all/202303251637.x35nzuXi-lkp@intel.com/


Signed-off-by: Stefan Herdler <herdler@nurfuerspam.de>

diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst
index b97d56ee543c..ffe8325749e5 100644
--- a/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst
+++ b/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst
@@ -23,3 +23,4 @@ DVB-S2, DVB-T2, ISDB, etc.
     :maxdepth: 1

     frontend_legacy_dvbv3_api
+    legacy_dvb_decoder_api
diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst
new file mode 100644
index 000000000000..b4f75643c21f
--- /dev/null
+++ b/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst
@@ -0,0 +1,1280 @@
+.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+
+.. _dvb_audio:
+
+================
+DVB Audio Device
+================
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+The DVB audio device controls the MPEG2 audio decoder of the DVB
+hardware. It can be accessed through ``/dev/dvb/adapter?/audio?``. Data
+types and ioctl definitions can be accessed by including
+``linux/dvb/audio.h`` in your application.
+
+Please note that most DVB cards don’t have their own MPEG decoder, which
+results in the omission of the audio and video device.
+
+These ioctls were also used by V4L2 to control MPEG decoders implemented
+in V4L2. The use of these ioctls for that purpose has been made obsolete
+and proper V4L2 ioctls or controls have been created to replace that
+functionality. Use :ref:`V4L2 ioctls<video>` for new drivers!
+
+
+
+Audio Data Types
+================
+
+This section describes the structures, data types and defines used when
+talking to the audio device.
+
+
+
+audio_stream_source_t
+---------------------
+
+The audio stream source is set through the `AUDIO_SELECT_SOURCE`_ call
+and can take the following values, depending on whether we are replaying
+from an internal (demux) or external (user write) source.
+
+
+.. code-block:: c
+
+    typedef enum {
+	AUDIO_SOURCE_DEMUX,
+	AUDIO_SOURCE_MEMORY
+    } audio_stream_source_t;
+
+AUDIO_SOURCE_DEMUX selects the demultiplexer (fed either by the
+frontend or the DVR device) as the source of the video stream. If
+AUDIO_SOURCE_MEMORY is selected the stream comes from the application
+through the `write()`_ system call.
+
+
+audio_play_state_t
+------------------
+
+The following values can be returned by the `AUDIO_GET_STATUS`_ call
+representing the state of audio playback.
+
+
+.. code-block:: c
+
+    typedef enum {
+	AUDIO_STOPPED,
+	AUDIO_PLAYING,
+	AUDIO_PAUSED
+    } audio_play_state_t;
+
+
+audio_channel_select_t
+----------------------
+
+The audio channel selected via `AUDIO_CHANNEL_SELECT`_ is determined by
+the following values.
+
+
+.. code-block:: c
+
+    typedef enum {
+	AUDIO_STEREO,
+	AUDIO_MONO_LEFT,
+	AUDIO_MONO_RIGHT,
+	AUDIO_MONO,
+	AUDIO_STEREO_SWAPPED
+    } audio_channel_select_t;
+
+
+audio_mixer
+-----------
+
+The following structure is used by the `AUDIO_SET_MIXER`_ call to set the
+audio volume.
+
+
+.. code-block:: c
+
+    typedef struct audio_mixer {
+	unsigned int volume_left;
+	unsigned int volume_right;
+    } audio_mixer_t;
+
+
+audio_status
+------------
+
+The `AUDIO_GET_STATUS`_ call returns the following structure informing
+about various states of the playback operation.
+
+
+.. code-block:: c
+
+    typedef struct audio_status {
+	boolean AV_sync_state;
+	boolean mute_state;
+	audio_play_state_t play_state;
+	audio_stream_source_t stream_source;
+	audio_channel_select_t channel_select;
+	boolean bypass_mode;
+	audio_mixer_t mixer_state;
+    } audio_status_t;
+
+
+audio encodings
+---------------
+
+A call to `AUDIO_GET_CAPABILITIES`_ returns an unsigned integer with the
+following bits set according to the hardwares capabilities.
+
+
+.. code-block:: c
+
+     #define AUDIO_CAP_DTS    1
+     #define AUDIO_CAP_LPCM   2
+     #define AUDIO_CAP_MP1    4
+     #define AUDIO_CAP_MP2    8
+     #define AUDIO_CAP_MP3   16
+     #define AUDIO_CAP_AAC   32
+     #define AUDIO_CAP_OGG   64
+     #define AUDIO_CAP_SDDS 128
+     #define AUDIO_CAP_AC3  256
+
+
+Audio Function Calls
+====================
+
+
+AUDIO_STOP
+----------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	 int ioctl(int fd, int request = AUDIO_STOP)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_STOP for this command.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to stop playing the current
+stream.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+AUDIO_PLAY
+----------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	 int  ioctl(int fd, int request = AUDIO_PLAY)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_PLAY for this command.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to start playing an audio stream
+from the selected source.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+AUDIO_PAUSE
+-----------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	 int  ioctl(int fd, int request = AUDIO_PAUSE)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_PAUSE for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call suspends the audio stream being played. Decoding and
+playing are paused. It is then possible to restart again decoding and
+playing process of the audio stream using `AUDIO_CONTINUE`_ command.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+AUDIO_CONTINUE
+--------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	 int  ioctl(int fd, int request = AUDIO_CONTINUE)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_CONTINUE for this command.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl restarts the decoding and playing process previously paused
+with `AUDIO_PAUSE`_ command.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+AUDIO_SELECT_SOURCE
+-------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	 int ioctl(int fd, int request = AUDIO_SELECT_SOURCE, audio_stream_source_t source)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_SELECT_SOURCE for this command.
+
+    -  .. row 3
+
+       -  `audio_stream_source_t`_ source
+
+       -  Indicates the source that shall be used for the Audio stream.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call informs the audio device which source shall be used for
+the input data. The possible sources are demux or memory. If
+AUDIO_SOURCE_MEMORY is selected, the data is fed to the Audio Device
+through the write command.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+AUDIO_SET_MUTE
+--------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	 int  ioctl(int fd, int request = AUDIO_SET_MUTE, boolean state)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_SET_MUTE for this command.
+
+    -  .. row 3
+
+       -  boolean state
+
+       -  Indicates if audio device shall mute or not.
+
+    -  .. row 4
+
+       -
+       -  TRUE Audio Mute
+
+    -  .. row 5
+
+       -
+       -  FALSE Audio Un-mute
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for DVB devices only. To control a V4L2 decoder use the
+V4L2 :ref:`VIDIOC_DECODER_CMD` with the
+``V4L2_DEC_CMD_START_MUTE_AUDIO`` flag instead.
+
+This ioctl call asks the audio device to mute the stream that is
+currently being played.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+AUDIO_SET_AV_SYNC
+-----------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	 int  ioctl(int fd, int request = AUDIO_SET_AV_SYNC, boolean state)
+
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_AV_SYNC for this command.
+
+    -  .. row 3
+
+       -  boolean state
+
+       -  Tells the DVB subsystem if A/V synchronization shall be ON or OFF.
+
+    -  .. row 4
+
+       -
+       -  TRUE AV-sync ON
+
+    -  .. row 5
+
+       -
+       -  FALSE AV-sync OFF
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to turn ON or OFF A/V
+synchronization.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+AUDIO_SET_BYPASS_MODE
+---------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	 int ioctl(int fd, int request = AUDIO_SET_BYPASS_MODE, boolean mode)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_SET_BYPASS_MODE for this command.
+
+    -  .. row 3
+
+       -  boolean mode
+
+       -  Enables or disables the decoding of the current Audio stream in
+	  the DVB subsystem.
+
+    -  .. row 4
+
+       -
+       -  TRUE Bypass is disabled
+
+    -  .. row 5
+
+       -
+       -  FALSE Bypass is enabled
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to bypass the Audio decoder and
+forward the stream without decoding. This mode shall be used if streams
+that can’t be handled by the DVB system shall be decoded. Dolby
+DigitalTM streams are automatically forwarded by the DVB subsystem if
+the hardware can handle it.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+AUDIO_CHANNEL_SELECT
+--------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	 int ioctl(int fd, int request = AUDIO_CHANNEL_SELECT, audio_channel_select_t)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_CHANNEL_SELECT for this command.
+
+    -  .. row 3
+
+       -  `audio_channel_select_t`_ ch
+
+       -  Select the output format of the audio (mono left/right, stereo).
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for DVB devices only. To control a V4L2 decoder use the
+V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK`` control instead.
+
+This ioctl call asks the Audio Device to select the requested channel if
+possible.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+AUDIO_GET_STATUS
+----------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	 int ioctl(int fd, int request = AUDIO_GET_STATUS, struct audio_status *status)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_GET_STATUS for this command.
+
+    -  .. row 3
+
+       -  struct `audio_status`_ \*status
+
+       -  Returns the current state of Audio Device.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to return the current state of the
+Audio Device.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+AUDIO_GET_CAPABILITIES
+----------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	 int ioctl(int fd, int request = AUDIO_GET_CAPABILITIES, unsigned int *cap)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_GET_CAPABILITIES for this command.
+
+    -  .. row 3
+
+       -  unsigned int \*cap
+
+       -  Returns a bit array of supported sound formats.
+          Bits are defined in `audio encodings`_.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to tell us about the decoding
+capabilities of the audio hardware.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+AUDIO_CLEAR_BUFFER
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	 int  ioctl(int fd, int request = AUDIO_CLEAR_BUFFER)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_CLEAR_BUFFER for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to clear all software and hardware
+buffers of the audio decoder device.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+AUDIO_SET_ID
+------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	 int  ioctl(int fd, int request = AUDIO_SET_ID, int id)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_SET_ID for this command.
+
+    -  .. row 3
+
+       -  int id
+
+       -  audio sub-stream id
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl selects which sub-stream is to be decoded if a program or
+system stream is sent to the video device. If no audio stream type is
+set the id has to be in [0xC0,0xDF] for MPEG sound, in [0x80,0x87] for
+AC3 and in [0xA0,0xA7] for LPCM. More specifications may follow for
+other stream types. If the stream type is set the id just specifies the
+substream id of the audio stream and only the first 5 bits are
+recognized.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+AUDIO_SET_MIXER
+---------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	 int ioctl(int fd, int request = AUDIO_SET_MIXER, audio_mixer_t *mix)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_SET_ID for this command.
+
+    -  .. row 3
+
+       -  audio_mixer_t \*mix
+
+       -  mixer settings.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl lets you adjust the mixer settings of the audio decoder.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+
+AUDIO_SET_STREAMTYPE
+--------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	 int  ioctl(fd, int request = AUDIO_SET_STREAMTYPE, int type)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_SET_STREAMTYPE for this command.
+
+    -  .. row 3
+
+       -  int type
+
+       -  stream type
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl tells the driver which kind of audio stream to expect. This
+is useful if the stream offers several audio sub-streams like LPCM and
+AC3.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  ``EINVAL``
+
+       -  type is not a valid or supported stream type.
+
+
+
+AUDIO_BILINGUAL_CHANNEL_SELECT
+------------------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	 int ioctl(int fd, int request = AUDIO_BILINGUAL_CHANNEL_SELECT, audio_channel_select_t)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals AUDIO_BILINGUAL_CHANNEL_SELECT for this command.
+
+    -  .. row 3
+
+       -  audio_channel_select_t ch
+
+       -  Select the output format of the audio (mono left/right, stereo).
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl has been replaced by the V4L2
+``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK`` control
+for MPEG decoders controlled through V4L2.
+
+This ioctl call asks the Audio Device to select the requested channel
+for bilingual streams if possible.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+
+open()
+------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	 int  open(const char *deviceName, int flags)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  const char \*deviceName
+
+       -  Name of specific audio device.
+
+    -  .. row 2
+
+       -  int flags
+
+       -  A bit-wise OR of the following flags:
+
+    -  .. row 3
+
+       -
+       -  O_RDONLY read-only access
+
+    -  .. row 4
+
+       -
+       -  O_RDWR read/write access
+
+    -  .. row 5
+
+       -
+       -  O_NONBLOCK open in non-blocking mode
+
+    -  .. row 6
+
+       -
+       -  (blocking mode is the default)
+
+
+Description
+~~~~~~~~~~~
+
+This system call opens a named audio device (e.g.
+/dev/dvb/adapter0/audio0) for subsequent use. When an open() call has
+succeeded, the device will be ready for use. The significance of
+blocking or non-blocking mode is described in the documentation for
+functions where there is a difference. It does not affect the semantics
+of the open() call itself. A device opened in blocking mode can later be
+put into non-blocking mode (and vice versa) using the F_SETFL command
+of the fcntl system call. This is a standard system call, documented in
+the Linux manual page for fcntl. Only one user can open the Audio Device
+in O_RDWR mode. All other attempts to open the device in this mode will
+fail, and an error code will be returned. If the Audio Device is opened
+in O_RDONLY mode, the only ioctl call that can be used is
+`AUDIO_GET_STATUS`_. All other call will return with an error code.
+
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  ``ENODEV``
+
+       -  Device driver not loaded/available.
+
+    -  .. row 2
+
+       -  ``EBUSY``
+
+       -  Device or resource busy.
+
+    -  .. row 3
+
+       -  ``EINVAL``
+
+       -  Invalid argument.
+
+
+close()
+-------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	 int  close(int fd)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+
+Description
+~~~~~~~~~~~
+
+This system call closes a previously opened audio device.
+
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  ``EBADF``
+
+       -  fd is not a valid open file descriptor.
+
+
+
+write()
+-------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	 size_t write(int fd, const void *buf, size_t count)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  void \*buf
+
+       -  Pointer to the buffer containing the PES data.
+
+    -  .. row 3
+
+       -  size_t count
+
+       -  Size of buf.
+
+
+Description
+~~~~~~~~~~~
+
+This system call can only be used if AUDIO_SOURCE_MEMORY is selected
+in the ioctl call `AUDIO_SELECT_SOURCE`_. The data provided shall be in
+PES format. If O_NONBLOCK is not specified the function will block
+until buffer space is available. The amount of data to be transferred is
+implied by count.
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  ``EPERM``
+
+       -  Mode AUDIO_SOURCE_MEMORY not selected.
+
+    -  .. row 2
+
+       -  ``ENOMEM``
+
+       -  Attempted to write more data than the internal buffer can hold.
+
+    -  .. row 3
+
+       -  ``EBADF``
+
+       -  fd is not a valid open file descriptor.
diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst
new file mode 100644
index 000000000000..566aa7b8eee6
--- /dev/null
+++ b/Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst
@@ -0,0 +1,61 @@
+.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+
+.. _legacy_dvb_decoder_api:
+
+============================
+Legacy DVB MPEG Decoder APIs
+============================
+
+.. _legacy_dvb_decoder_notes:
+
+General Notes
+=============
+
+This API has originally been designed for DVB only and is therefore limited to
+the :ref:`legacy_dvb_decoder_formats` used in such digital TV-broadcastsystems.
+
+To circumvent this limitations the more versatile :ref:`V4L2 <v4l2spec>` API has
+been designed. Which replaces this part of the DVB API.
+
+Nevertheless there have been projects build around this API.
+To ensure compatibility this API is kept as it is.
+
+.. attention:: Do **not** use this API in new drivers!
+
+    For audio and video use the :ref:`V4L2 <v4l2spec>` and ALSA APIs.
+
+    Pipelines should be set up using the :ref:`Media Controller  API<media_controller>`.
+
+Practically the decoders seem to be treated differently. The application typically
+knows which decoder is in use or it is specially written for one decoder type.
+Querying capabilities are rarely used because they are already known.
+
+.. _legacy_dvb_decoder_formats:
+
+Data Formats
+============
+
+The API has been designed for DVB and compatible broadcastsystems.
+Because of that fact the only supported data formats are ISO/IEC 13818-1
+compatible MPEG streams. The supported payloads may vary depending on the
+used decoder.
+
+Timestamps are always MPEG PTS as defined in ITU T-REC-H.222.0 /
+ISO/IEC 13818-1, if not otherwise noted.
+
+For storing recordings typically TS streams are used, in lesser extent PES.
+Both variants are commonly accepted for playback, but it may be driver dependent.
+
+
+
+
+Table of Contents
+=================
+
+.. toctree::
+    :maxdepth: 2
+
+    legacy_dvb_video
+    legacy_dvb_audio
+    legacy_dvb_osd
+
diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst
new file mode 100644
index 000000000000..2174440e77c5
--- /dev/null
+++ b/Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst
@@ -0,0 +1,444 @@
+.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+
+.. _dvb_osd:
+
+==============
+DVB OSD Device
+==============
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+The DVB OSD Device controls the OnScreenDisplay of the AV7110 based
+DVB-cards with hardware MPEG2 decoder. It can be accessed through ``/dev/dvb/adapter?/osd0``.
+Data types and ioctl definitions can be accessed by including
+``linux/dvb/osd.h`` in your application.
+
+The OSD is not a framebuffer like on many other cards.
+It is a kind of canvas one can draw on.
+The colordepth is limited depending on the memorysize installed. An appropriate palette
+of colors has to be set up.
+The installed memory size can be identified with the `OSD_GET_CAPABILITY`_ ioctl.
+
+OSD Data Types
+==============
+
+OSD_Command
+-----------
+
+The ``OSD_Command`` data type defined by
+
+.. code-block:: c
+
+    typedef enum {
+	/* All functions return -2 on "not open" */
+	OSD_Close = 1,	/* () */
+	/*
+	 * Disables OSD and releases the buffers
+	 * returns 0 on success
+	 */
+	OSD_Open,	/* (x0,y0,x1,y1,BitPerPixel[2/4/8](color&0x0F),mix[0..15](color&0xF0)) */
+	/*
+	 * Opens OSD with this size and bit depth
+	 * returns 0 on success, -1 on DRAM allocation error, -2 on "already open"
+	 */
+	OSD_Show,	/* () */
+	/*
+	 * enables OSD mode
+	 * returns 0 on success
+	 */
+	OSD_Hide,	/* () */
+	/*
+	 * disables OSD mode
+	 * returns 0 on success
+	 */
+	OSD_Clear,	/* () */
+	/*
+	 * Sets all pixel to color 0
+	 * returns 0 on success
+	 */
+	OSD_Fill,	/* (color) */
+	/*
+	 * Sets all pixel to color <col>
+	 * returns 0 on success
+	 */
+	OSD_SetColor,	/* (color,R{x0},G{y0},B{x1},opacity{y1}) */
+	/*
+	 * set palette entry <num> to <r,g,b>, <mix> and <trans> apply
+	 * R,G,B: 0..255
+	 * R=Red, G=Green, B=Blue
+	 * opacity=0:      pixel opacity 0% (only video pixel shows)
+	 * opacity=1..254: pixel opacity as specified in header
+	 * opacity=255:    pixel opacity 100% (only OSD pixel shows)
+	 * returns 0 on success, -1 on error
+	 */
+	OSD_SetPalette,	/* (firstcolor{color},lastcolor{x0},data) */
+	/*
+	 * Set a number of entries in the palette
+	 * sets the entries "firstcolor" through "lastcolor" from the array "data"
+	 * data has 4 byte for each color:
+	 * R,G,B, and a opacity value: 0->transparent, 1..254->mix, 255->pixel
+	 */
+	OSD_SetTrans,	/* (transparency{color}) */
+	/*
+	 * Sets transparency of mixed pixel (0..15)
+	 * returns 0 on success
+	 */
+	OSD_SetPixel,	/* (x0,y0,color) */
+	/*
+	 * sets pixel <x>,<y> to color number <col>
+	 * returns 0 on success, -1 on error
+	 */
+	OSD_GetPixel,	/* (x0,y0) */
+	/* returns color number of pixel <x>,<y>,  or -1 */
+	OSD_SetRow,	/* (x0,y0,x1,data) */
+	/*
+	 * fills pixels x0,y through  x1,y with the content of data[]
+	 * returns 0 on success, -1 on clipping all pixel (no pixel drawn)
+	 */
+	OSD_SetBlock,	/* (x0,y0,x1,y1,increment{color},data) */
+	/*
+	 * fills pixels x0,y0 through  x1,y1 with the content of data[]
+	 * inc contains the width of one line in the data block,
+	 * inc<=0 uses blockwidth as linewidth
+	 * returns 0 on success, -1 on clipping all pixel
+	 */
+	OSD_FillRow,	/* (x0,y0,x1,color) */
+	/*
+	 * fills pixels x0,y through  x1,y with the color <col>
+	 * returns 0 on success, -1 on clipping all pixel
+	 */
+	OSD_FillBlock,	/* (x0,y0,x1,y1,color) */
+	/*
+	 * fills pixels x0,y0 through  x1,y1 with the color <col>
+	 * returns 0 on success, -1 on clipping all pixel
+	 */
+	OSD_Line,	/* (x0,y0,x1,y1,color) */
+	/*
+	 * draw a line from x0,y0 to x1,y1 with the color <col>
+	 * returns 0 on success
+	 */
+	OSD_Query,	/* (x0,y0,x1,y1,xasp{color}}), yasp=11 */
+	/*
+	 * fills parameters with the picture dimensions and the pixel aspect ratio
+	 * returns 0 on success
+	 */
+	OSD_Test,       /* () */
+	/*
+	 * draws a test picture. for debugging purposes only
+	 * returns 0 on success
+	 * TODO: remove "test" in final version
+	 */
+	OSD_Text,	/* (x0,y0,size,color,text) */
+	OSD_SetWindow,	/* (x0) set window with number 0<x0<8 as current */
+	OSD_MoveWindow,	/* move current window to (x0, y0) */
+	OSD_OpenRaw,	/* Open other types of OSD windows */
+    } OSD_Command;
+
+is used with the `OSD_SEND_CMD`_ ioctl to tell the driver which OSD_Command to execute.
+
+osd_cmd_t
+---------
+
+The ``osd_cmd_t`` data type defined by
+
+.. code-block:: c
+
+    typedef struct osd_cmd_s {
+	OSD_Command cmd;
+	int x0;
+	int y0;
+	int x1;
+	int y1;
+	int color;
+	void __user *data;
+    } osd_cmd_t;
+
+is used with the `OSD_SEND_CMD`_ ioctl.
+It contains the data for the OSD_Command and the `OSD_Command`_ itself.
+
+
+osd_raw_window_t
+----------------
+
+The ``osd_raw_window_t`` data type defined by
+
+.. code-block:: c
+
+    /* OSD_OpenRaw: set 'color' to desired window type */
+    typedef enum {
+	OSD_BITMAP1,           /* 1 bit bitmap */
+	OSD_BITMAP2,           /* 2 bit bitmap */
+	OSD_BITMAP4,           /* 4 bit bitmap */
+	OSD_BITMAP8,           /* 8 bit bitmap */
+	OSD_BITMAP1HR,         /* 1 Bit bitmap half resolution */
+	OSD_BITMAP2HR,         /* 2 bit bitmap half resolution */
+	OSD_BITMAP4HR,         /* 4 bit bitmap half resolution */
+	OSD_BITMAP8HR,         /* 8 bit bitmap half resolution */
+	OSD_YCRCB422,          /* 4:2:2 YCRCB Graphic Display */
+	OSD_YCRCB444,          /* 4:4:4 YCRCB Graphic Display */
+	OSD_YCRCB444HR,        /* 4:4:4 YCRCB graphic half resolution */
+	OSD_VIDEOTSIZE,        /* True Size Normal MPEG Video Display */
+	OSD_VIDEOHSIZE,        /* MPEG Video Display Half Resolution */
+	OSD_VIDEOQSIZE,        /* MPEG Video Display Quarter Resolution */
+	OSD_VIDEODSIZE,        /* MPEG Video Display Double Resolution */
+	OSD_VIDEOTHSIZE,       /* True Size MPEG Video Display Half Resolution */
+	OSD_VIDEOTQSIZE,       /* True Size MPEG Video Display Quarter Resolution*/
+	OSD_VIDEOTDSIZE,       /* True Size MPEG Video Display Double Resolution */
+	OSD_VIDEONSIZE,        /* Full Size MPEG Video Display */
+	OSD_CURSOR             /* Cursor */
+    } osd_raw_window_t;
+
+is used to tell the `OSD_Command`_ OSD_OpenRaw which type of OSD to open.
+
+osd_cap_t
+---------
+
+The following is the structure of data returned by the `OSD_GET_CAPABILITY`_ call.
+
+The ``osd_cap_t`` data type defined by
+
+.. code-block:: c
+
+    typedef struct osd_cap_s {
+	int  cmd;
+    #define OSD_CAP_MEMSIZE         1  /* memory size */
+	long val;
+    } osd_cap_t;
+
+OSD Function Calls
+==================
+
+OSD_SEND_CMD
+------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    int ioctl(int fd, int request = OSD_SEND_CMD, enum osd_cmd_t *cmd)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals `osd_cmd_t`_ for this command.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl sends the `OSD_Command`_ to the card.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+OSD_GET_CAPABILITY
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    int ioctl(int fd, int request = OSD_GET_CAPABILITY, struct osd_cap_t *cap)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals OSD_GET_CAPABILITY for this command.
+
+    -  .. row 3
+
+       -  unsigned int \*cap
+
+       -  Pointer to a location where to store the capability information.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is used to get the capabilities of the OSD of the AV7110 based DVB-decoder-card in use.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+open()
+------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    int open(const char *deviceName, int flags)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  const char \*deviceName
+
+       -  Name of specific OSD device.
+
+    -  .. row 2
+
+       -  int flags
+
+       -  A bit-wise OR of the following flags:
+
+    -  .. row 3
+
+       -
+       -  O_RDONLY read-only access
+
+    -  .. row 4
+
+       -
+       -  O_RDWR read/write access
+
+    -  .. row 5
+
+       -
+       -  O_NONBLOCK open in non-blocking mode
+
+
+Description
+~~~~~~~~~~~
+
+This system call opens a named OSD device (e.g.
+/dev/dvb/adapter?/osd0) for subsequent use.
+
+
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  ``ENODEV``
+
+       -  Device driver not loaded/available.
+
+    -  .. row 2
+
+       -  ``EINTERNAL``
+
+       -  Internal error.
+
+    -  .. row 3
+
+       -  ``EBUSY``
+
+       -  Device or resource busy.
+
+    -  .. row 4
+
+       -  ``EINVAL``
+
+       -  Invalid argument.
+
+close()
+-------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    int close(int fd)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_ .
+
+
+Description
+~~~~~~~~~~~
+
+This system call closes a previously opened OSD device.
+
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  ``EBADF``
+
+       -  fd is not a valid open file descriptor.
+
diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst
new file mode 100644
index 000000000000..ae0c1e8a54b8
--- /dev/null
+++ b/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst
@@ -0,0 +1,1768 @@
+.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+
+.. _dvb_video:
+
+================
+DVB Video Device
+================
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+The DVB video device controls the MPEG2 video decoder of the DVB
+hardware. It can be accessed through ``/dev/dvb/adapter0/video0``. Data
+types and ioctl definitions can be accessed by including
+``linux/dvb/video.h`` in your application.
+
+Note that the DVB video device only controls decoding of the MPEG video
+stream, not its presentation on the TV or computer screen. On PCs this
+is typically handled by an associated video4linux device, e.g.
+``/dev/video``, which allows scaling and defining output windows.
+
+Most DVB cards don’t have their own MPEG decoder, which results in the
+omission of the audio and video device as well as the video4linux
+device.
+
+These ioctls were also used by V4L2 to control MPEG decoders implemented
+in V4L2. The use of these ioctls for that purpose has been made obsolete
+and proper V4L2 ioctls or controls have been created to replace that
+functionality. Use :ref:`V4L2 ioctls<video>` for new drivers!
+
+
+Video Data Types
+================
+
+
+video_format_t
+--------------
+
+The ``video_format_t`` data type defined by
+
+
+.. code-block:: c
+
+    typedef enum {
+	VIDEO_FORMAT_4_3,     /* Select 4:3 format */
+	VIDEO_FORMAT_16_9,    /* Select 16:9 format. */
+	VIDEO_FORMAT_221_1    /* 2.21:1 */
+    } video_format_t;
+
+is used in the `VIDEO_SET_FORMAT`_ function to tell the driver which
+aspect ratio the output hardware (e.g. TV) has. It is also used in the
+data structures `video_status`_ returned by `VIDEO_GET_STATUS`_
+and `video_event`_ returned by `VIDEO_GET_EVENT`_ which report
+about the display format of the current video stream.
+
+
+video_displayformat_t
+---------------------
+
+In case the display format of the video stream and of the display
+hardware differ the application has to specify how to handle the
+cropping of the picture. This can be done using the
+`VIDEO_SET_DISPLAY_FORMAT`_ call which accepts
+
+
+.. code-block:: c
+
+    typedef enum {
+	VIDEO_PAN_SCAN,       /* use pan and scan format */
+	VIDEO_LETTER_BOX,     /* use letterbox format */
+	VIDEO_CENTER_CUT_OUT  /* use center cut out format */
+    } video_displayformat_t;
+
+as argument.
+
+
+video_size_t
+------------
+
+Used in the struct `video_event`_. It stores the resolution and
+aspect ratio of the video.
+
+.. code-block:: c
+
+    typedef struct {
+	int w;
+	int h;
+	video_format_t aspect_ratio;
+    } video_size_t;
+
+
+video_stream_source_t
+---------------------
+
+The video stream source is set through the `VIDEO_SELECT_SOURCE`_ call
+and can take the following values, depending on whether we are replaying
+from an internal (demuxer) or external (user write) source.
+
+
+.. code-block:: c
+
+    typedef enum {
+	VIDEO_SOURCE_DEMUX, /* Select the demux as the main source */
+	VIDEO_SOURCE_MEMORY /* If this source is selected, the stream
+		       comes from the user through the write
+		       system call */
+    } video_stream_source_t;
+
+VIDEO_SOURCE_DEMUX selects the demultiplexer (fed either by the
+frontend or the DVR device) as the source of the video stream. If
+VIDEO_SOURCE_MEMORY is selected the stream comes from the application
+through the `write()`_ system call.
+
+
+video_play_state_t
+------------------
+
+The following values can be returned by the `VIDEO_GET_STATUS`_ call
+representing the state of video playback.
+
+
+.. code-block:: c
+
+    typedef enum {
+	VIDEO_STOPPED, /* Video is stopped */
+	VIDEO_PLAYING, /* Video is currently playing */
+	VIDEO_FREEZED  /* Video is freezed */
+    } video_play_state_t;
+
+
+struct video_command
+--------------------
+
+The structure must be zeroed before use by the application. This ensures
+it can be extended safely in the future.
+
+
+.. code-block:: c
+
+    struct video_command {
+	__u32 cmd;
+	__u32 flags;
+	union {
+	    struct {
+		__u64 pts;
+	    } stop;
+
+	    struct {
+		/* 0 or 1000 specifies normal speed,
+		   1 specifies forward single stepping,
+		   -1 specifies backward single stepping,
+		   >>1: playback at speed/1000 of the normal speed,
+		   <-1: reverse playback at (-speed/1000) of the normal speed. */
+		__s32 speed;
+		__u32 format;
+	    } play;
+
+	    struct {
+		__u32 data[16];
+	    } raw;
+	};
+    };
+
+
+Predefined decoder commands and flags:
+
+.. code-block:: c
+
+    /* Decoder commands */
+    #define VIDEO_CMD_PLAY        (0)
+    #define VIDEO_CMD_STOP        (1)
+    #define VIDEO_CMD_FREEZE      (2)
+    #define VIDEO_CMD_CONTINUE    (3)
+
+    /* Flags for VIDEO_CMD_FREEZE */
+    #define VIDEO_CMD_FREEZE_TO_BLACK	(1 << 0)
+
+    /* Flags for VIDEO_CMD_STOP */
+    #define VIDEO_CMD_STOP_TO_BLACK	(1 << 0)
+    #define VIDEO_CMD_STOP_IMMEDIATELY	(1 << 1)
+
+    /* Play input formats: */
+    /* The decoder has no special format requirements */
+    #define VIDEO_PLAY_FMT_NONE         (0)
+    /* The decoder requires full GOPs */
+    #define VIDEO_PLAY_FMT_GOP          (1)
+
+    /* FIELD_UNKNOWN can be used if the hardware does not know whether
+    the Vsync is for an odd, even or progressive (i.e. non-interlaced)
+    field. */
+    #define VIDEO_VSYNC_FIELD_UNKNOWN		(0)
+    #define VIDEO_VSYNC_FIELD_ODD		(1)
+    #define VIDEO_VSYNC_FIELD_EVEN		(2)
+    #define VIDEO_VSYNC_FIELD_PROGRESSIVE	(3)
+
+
+
+video_event
+-----------
+
+The following is the structure of a video event as it is returned by the
+`VIDEO_GET_EVENT`_ call.
+
+
+.. code-block:: c
+
+    struct video_event {
+	__s32 type;
+    #define VIDEO_EVENT_SIZE_CHANGED        1
+    #define VIDEO_EVENT_FRAME_RATE_CHANGED  2
+    #define VIDEO_EVENT_DECODER_STOPPED     3
+    #define VIDEO_EVENT_VSYNC               4
+	long timestamp;                 /* MPEG PTS */
+	union {
+	    video_size_t size;
+	    unsigned int frame_rate;    /* in frames per 1000sec */
+	    unsigned char vsync_field;  /* unknown/odd/even/progressive */
+	} u;
+    };
+
+
+video_status
+------------
+
+The `VIDEO_GET_STATUS`_ call returns the following structure informing
+about various states of the playback operation.
+
+
+.. code-block:: c
+
+    struct video_status {
+	int                   video_blank;   /* blank video on freeze? */
+	video_play_state_t    play_state;    /* current state of playback */
+	video_stream_source_t stream_source; /* current source (demux/memory) */
+	video_format_t        video_format;  /* current aspect ratio of stream */
+	video_displayformat_t display_format;/* applied cropping mode */
+    };
+
+If video_blank is set video will be blanked out if the channel is
+changed or if playback is stopped. Otherwise, the last picture will be
+displayed. play_state indicates if the video is currently frozen,
+stopped, or being played back. The stream_source corresponds to the
+selected source for the video stream. It can come either from the
+demultiplexer or from memory. The video_format indicates the aspect
+ratio (one of 4:3 or 16:9) of the currently played video stream.
+Finally, display_format corresponds to the applied cropping mode in
+case the source video format is not the same as the format of the output
+device.
+
+
+video_still_picture
+-------------------
+
+An I-frame displayed via the `VIDEO_STILLPICTURE`_ call is passed on
+within the following structure.
+
+
+.. code-block:: c
+
+    /* pointer to and size of a single iframe in memory */
+    struct video_still_picture {
+    char *iFrame;        /* pointer to a single iframe in memory */
+    int32_t size;
+    };
+
+
+video capabilities
+------------------
+
+A call to `VIDEO_GET_CAPABILITIES`_ returns an unsigned integer with the
+following bits set according to the hardwares capabilities.
+
+
+.. code-block:: c
+
+    /* bit definitions for capabilities: */
+    /* can the hardware decode MPEG1 and/or MPEG2? */
+    #define VIDEO_CAP_MPEG1   1
+    #define VIDEO_CAP_MPEG2   2
+    /* does the video device accept system and/or program stream?
+    (you still have to open the video and the audio device
+    but only send the stream to the video device) */
+    #define VIDEO_CAP_SYS     4
+    #define VIDEO_CAP_PROG    8
+
+
+Video Function Calls
+====================
+
+
+VIDEO_STOP
+----------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	int ioctl(fd, VIDEO_STOP, boolean mode)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_STOP for this command.
+
+    -  .. row 3
+
+       -  Boolean mode
+
+       -  Indicates how the screen shall be handled.
+
+    -  .. row 4
+
+       -
+       -  TRUE: Blank screen when stop.
+
+    -  .. row 5
+
+       -
+       -  FALSE: Show last decoded frame.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for Digital TV devices only. To control a V4L2 decoder use the
+V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
+
+This ioctl call asks the Video Device to stop playing the current
+stream. Depending on the input parameter, the screen can be blanked out
+or displaying the last decoded frame.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_PLAY
+----------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	int ioctl(fd, VIDEO_PLAY)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_PLAY for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for Digital TV devices only. To control a V4L2 decoder use the
+V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
+
+This ioctl call asks the Video Device to start playing a video stream
+from the selected source.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_FREEZE
+------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	int ioctl(fd, VIDEO_FREEZE)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_FREEZE for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for Digital TV devices only. To control a V4L2 decoder use the
+V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
+
+This ioctl call suspends the live video stream being played. Decoding
+and playing are frozen. It is then possible to restart the decoding and
+playing process of the video stream using the `VIDEO_CONTINUE`_ command.
+If VIDEO_SOURCE_MEMORY is selected in the ioctl call
+`VIDEO_SELECT_SOURCE`_, the Digital TV subsystem will not decode any more data
+until the ioctl call `VIDEO_CONTINUE`_ or `VIDEO_PLAY`_ is performed.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_CONTINUE
+--------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	int ioctl(fd, VIDEO_CONTINUE)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_CONTINUE for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for Digital TV devices only. To control a V4L2 decoder use the
+V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
+
+This ioctl call restarts decoding and playing processes of the video
+stream which was played before a call to `VIDEO_FREEZE`_ was made.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_SELECT_SOURCE
+-------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	int ioctl(fd, VIDEO_SELECT_SOURCE, video_stream_source_t source)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_SELECT_SOURCE for this command.
+
+    -  .. row 3
+
+       -  `video_stream_source_t`_ source
+
+       -  Indicates which source shall be used for the Video stream.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for Digital TV devices only. This ioctl was also supported by the
+V4L2 ivtv driver, but that has been replaced by the ivtv-specific
+``IVTV_IOC_PASSTHROUGH_MODE`` ioctl.
+
+This ioctl call informs the video device which source shall be used for
+the input data. The possible sources are demux or memory. If memory is
+selected, the data is fed to the video device through the write command
+using the struct `video_stream_source_t`_.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_SET_BLANK
+---------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	int ioctl(fd, VIDEO_SET_BLANK, boolean mode)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_SET_BLANK for this command.
+
+    -  .. row 3
+
+       -  boolean mode
+
+       -  TRUE: Blank screen when stop.
+
+    -  .. row 4
+
+       -
+       -  FALSE: Show last decoded frame.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Video Device to blank out the picture.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_GET_STATUS
+----------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_GET_STATUS, struct video_status *status)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_GET_STATUS for this command.
+
+    -  .. row 3
+
+       -  struct `video_status`_ \*status
+
+       -  Returns the current status of the Video Device.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Video Device to return the current status of
+the device.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_GET_EVENT
+---------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_GET_EVENT, struct video_event *ev)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_GET_EVENT for this command.
+
+    -  .. row 3
+
+       -  struct `video_event`_ \*ev
+
+       -  Points to the location where the event, if any, is to be stored.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for DVB devices only. To get events from a V4L2 decoder
+use the V4L2 :ref:`VIDIOC_DQEVENT` ioctl instead.
+
+This ioctl call returns an event of type `video_event`_ if available. If
+an event is not available, the behavior depends on whether the device is
+in blocking or non-blocking mode. In the latter case, the call fails
+immediately with errno set to ``EWOULDBLOCK``. In the former case, the call
+blocks until an event becomes available. The standard Linux poll()
+and/or select() system calls can be used with the device file descriptor
+to watch for new events. For select(), the file descriptor should be
+included in the exceptfds argument, and for poll(), POLLPRI should be
+specified as the wake-up condition. Read-only permissions are sufficient
+for this ioctl call.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  ``EWOULDBLOCK``
+
+       -  There is no event pending, and the device is in non-blocking mode.
+
+    -  .. row 2
+
+       -  ``EOVERFLOW``
+
+       -  Overflow in event queue - one or more events were lost.
+
+
+VIDEO_SET_DISPLAY_FORMAT
+------------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_SET_DISPLAY_FORMAT, video_display_format_t format)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_SET_DISPLAY_FORMAT for this command.
+
+    -  .. row 3
+
+       -  `video_displayformat_t`_ format
+
+       -  Selects the video format to be used.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Video Device to select the video format to be
+applied by the MPEG chip on the video.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_STILLPICTURE
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_STILLPICTURE, struct video_still_picture *sp)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_STILLPICTURE for this command.
+
+    -  .. row 3
+
+       -  struct `video_still_picture`_ \*sp
+
+       -  Pointer to a location where an I-frame and size is stored.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Video Device to display a still picture
+(I-frame). The input data shall contain an I-frame. If the pointer is
+NULL, then the current displayed still picture is blanked.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_FAST_FORWARD
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_FAST_FORWARD, int nFrames)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_FAST_FORWARD for this command.
+
+    -  .. row 3
+
+       -  int nFrames
+
+       -  The number of frames to skip.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Video Device to skip decoding of N number of
+I-frames. This call can only be used if VIDEO_SOURCE_MEMORY is
+selected.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  ``EPERM``
+
+       -  Mode VIDEO_SOURCE_MEMORY not selected.
+
+
+VIDEO_SLOWMOTION
+----------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_SLOWMOTION, int nFrames)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_SLOWMOTION for this command.
+
+    -  .. row 3
+
+       -  int nFrames
+
+       -  The number of times to repeat each frame.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the video device to repeat decoding frames N number
+of times. This call can only be used if VIDEO_SOURCE_MEMORY is
+selected.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  ``EPERM``
+
+       -  Mode VIDEO_SOURCE_MEMORY not selected.
+
+
+VIDEO_GET_CAPABILITIES
+----------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_GET_CAPABILITIES, unsigned int *cap)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_GET_CAPABILITIES for this command.
+
+    -  .. row 3
+
+       -  unsigned int \*cap
+
+       -  Pointer to a location where to store the capability information.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the video device about its decoding capabilities.
+On success it returns and integer which has bits set according to the
+defines in section ??.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_CLEAR_BUFFER
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_CLEAR_BUFFER)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_CLEAR_BUFFER for this command.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call clears all video buffers in the driver and in the
+decoder hardware.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_SET_STREAMTYPE
+--------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_SET_STREAMTYPE, int type)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_SET_STREAMTYPE for this command.
+
+    -  .. row 3
+
+       -  int type
+
+       -  stream type
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl tells the driver which kind of stream to expect being written
+to it. If this call is not used the default of video PES is used. Some
+drivers might not support this call and always expect PES.
+Intelligent decoder might also not support or ignore this call and
+determine the streamtype themselves.
+
+.. note:: See: :ref:`DVB Data Formats <legacy_dvb_decoder_formats>`
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_SET_FORMAT
+----------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_SET_FORMAT, video_format_t format)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_SET_FORMAT for this command.
+
+    -  .. row 3
+
+       -  `video_format_t`_ format
+
+       -  video format of TV as defined in section ??.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl sets the screen format (aspect ratio) of the connected output
+device (TV) so that the output of the decoder can be adjusted
+accordingly.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_GET_SIZE
+--------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	int ioctl(int fd, int request = VIDEO_GET_SIZE, video_size_t *size)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_GET_SIZE for this command.
+
+    -  .. row 3
+
+       -  `video_size_t`_ \*size
+
+       -  Returns the size and aspect ratio.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl returns the size and aspect ratio.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_GET_PTS
+-------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	int ioctl(int fd, int request = VIDEO_GET_PTS, __u64 *pts)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_GET_PTS for this command.
+
+    -  .. row 3
+
+       -  __u64 \*pts
+
+       -  Returns the 33-bit timestamp as defined in ITU T-REC-H.222.0 /
+	  ISO/IEC 13818-1.
+
+	  The PTS should belong to the currently played frame if possible,
+	  but may also be a value close to it like the PTS of the last
+	  decoded frame or the last PTS extracted by the PES parser.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+For V4L2 decoders this ioctl has been replaced by the
+``V4L2_CID_MPEG_VIDEO_DEC_PTS`` control.
+
+This ioctl call asks the Video Device to return the current PTS
+timestamp.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_GET_FRAME_RATE
+--------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	int ioctl(int fd, int request = VIDEO_GET_FRAME_RATE, unsigned int *rate)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_GET_FRAME_RATE for this command.
+
+    -  .. row 3
+
+       -  unsigned int \*rate
+
+       -  Returns the framerate in number of frames per 1000 seconds.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Video Device to return the current framerate.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_COMMAND
+-------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	int ioctl(int fd, int request = VIDEO_COMMAND, struct video_command *cmd)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_COMMAND for this command.
+
+    -  .. row 3
+
+       -  `struct video_command`_ \*cmd
+
+       -  Commands the decoder.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+For V4L2 decoders this ioctl has been replaced by the
+:ref:`VIDIOC_DECODER_CMD` ioctl.
+
+This ioctl commands the decoder. The `struct video_command`_ is a
+subset of the ``v4l2_decoder_cmd`` struct, so refer to the
+:ref:`VIDIOC_DECODER_CMD` documentation for
+more information.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+VIDEO_TRY_COMMAND
+-----------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	int ioctl(int fd, int request = VIDEO_TRY_COMMAND, struct video_command *cmd)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  int request
+
+       -  Equals VIDEO_TRY_COMMAND for this command.
+
+    -  .. row 3
+
+       -  `struct video_command`_ \*cmd
+
+       -  Try a decoder command.
+
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+For V4L2 decoders this ioctl has been replaced by the
+:ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` ioctl.
+
+This ioctl tries a decoder command. The `struct video_command`_ is a
+subset of the ``v4l2_decoder_cmd`` struct, so refer to the
+:ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` documentation
+for more information.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+open()
+------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	int open(const char *deviceName, int flags)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  const char \*deviceName
+
+       -  Name of specific video device.
+
+    -  .. row 2
+
+       -  int flags
+
+       -  A bit-wise OR of the following flags:
+
+    -  .. row 3
+
+       -
+       -  O_RDONLY read-only access
+
+    -  .. row 4
+
+       -
+       -  O_RDWR read/write access
+
+    -  .. row 5
+
+       -
+       -  O_NONBLOCK open in non-blocking mode
+
+    -  .. row 6
+
+       -
+       -  (blocking mode is the default)
+
+
+Description
+~~~~~~~~~~~
+
+This system call opens a named video device (e.g.
+/dev/dvb/adapter?/video?) for subsequent use.
+
+When an open() call has succeeded, the device will be ready for use. The
+significance of blocking or non-blocking mode is described in the
+documentation for functions where there is a difference. It does not
+affect the semantics of the open() call itself. A device opened in
+blocking mode can later be put into non-blocking mode (and vice versa)
+using the F_SETFL command of the fcntl system call. This is a standard
+system call, documented in the Linux manual page for fcntl. Only one
+user can open the Video Device in O_RDWR mode. All other attempts to
+open the device in this mode will fail, and an error-code will be
+returned. If the Video Device is opened in O_RDONLY mode, the only
+ioctl call that can be used is `VIDEO_GET_STATUS`_. All other call will
+return an error code.
+
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  ``ENODEV``
+
+       -  Device driver not loaded/available.
+
+    -  .. row 2
+
+       -  ``EINTERNAL``
+
+       -  Internal error.
+
+    -  .. row 3
+
+       -  ``EBUSY``
+
+       -  Device or resource busy.
+
+    -  .. row 4
+
+       -  ``EINVAL``
+
+       -  Invalid argument.
+
+
+close()
+-------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	int close(int fd)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+
+Description
+~~~~~~~~~~~
+
+This system call closes a previously opened video device.
+
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  ``EBADF``
+
+       -  fd is not a valid open file descriptor.
+
+
+write()
+-------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	size_t write(int fd, const void *buf, size_t count)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  int fd
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  .. row 2
+
+       -  void \*buf
+
+       -  Pointer to the buffer containing the PES data.
+
+    -  .. row 3
+
+       -  size_t count
+
+       -  Size of buf.
+
+
+Description
+~~~~~~~~~~~
+
+This system call can only be used if VIDEO_SOURCE_MEMORY is selected
+in the ioctl call `VIDEO_SELECT_SOURCE`_. The data provided shall be in
+PES format, unless the capability allows other formats. TS is the
+most common format for storing DVB-data, it is usually supported too.
+If O_NONBLOCK is not specified the function will block until buffer space
+is available. The amount of data to be transferred is implied by count.
+
+.. note:: See: :ref:`DVB Data Formats <legacy_dvb_decoder_formats>`
+
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  .. row 1
+
+       -  ``EPERM``
+
+       -  Mode VIDEO_SOURCE_MEMORY not selected.
+
+    -  .. row 2
+
+       -  ``ENOMEM``
+
+       -  Attempted to write more data than the internal buffer can hold.
+
+    -  .. row 3
+
+       -  ``EBADF``
+
+       -  fd is not a valid open file descriptor.

Re: saa7146: please test the vb2 conversion!

[Tomasz Maciej Nowak]

W dniu 24.03.2023 o 22:21, Stefan Herdler pisze:

[...]

> There are only DVB-C boards with analog features.
> 
> I personally never had cable-TV nor own any DVB-C cards.
> But I try to find such a card with an analog module on it.

I'm not 100% sure, but there seems to be one offered on "ebay-kleinanzeigen".
Search for "DVB Board Siemens PCI". I won't post link, since that'll be
outdated once the offer expires. Unfortunately it's rather on the expensive
side, for the features it provides today.

[...]

Regards

-- 
TMN

Re: [PATCH v2] Legacy DVB API: completion of documentation

[Mauro Carvalho Chehab]

Em Sun, 26 Mar 2023 23:34:16 +0200
Stefan Herdler <herdler@nurfuerspam.de> escreveu:

> On 25/03/23 02:44, Stefan Herdler wrote:
> > Hi Mauro and Hans,
> >
> > it took a little longer then anticipated, but I think I was able to fill the gaps in the documentation.

Hmm.. your e-mailer seems to have mangled it:

	patch -p1 -i /tmp/dvb-doc.patch 
	patching file Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst
	patching file '='
	patch: **** malformed patch at line 198: , which

Better to submit it via "git send-email".

> > At least everything in the header-files is in the documentation now. I hope, I have done it sufficiently.

Good! It took me quite a while to read everything... At the end, as was
a little tired, so I probably missed things.

Next time, please split this on a patch series, in order to make
easier for the poor reviewers to look into it ;-)

> >
> > Some remarks:
> >
> > I considered the existing documentation to be trustworthy.

Please don't do that. The existing ones came from an old DVB API 
documentation, plus some reverse engineering we did to try to
understand missing bits.

There are existing gaps there that we were not able to address
(including some ioctls that has only a doc stub, if I'm not 
mistaken - I guess we removed some of those, but maybe there are
some stubs remaining somewhere).

> > Existing things like returntypes, errnos, ... haven't been touched by me.

Well, errnos are probably not too outdated.

> > There are only a few minor modifications to reflect the data formats actually used for playback.

Ok.

> >
> > The documentation has been merged into one file per header-file. Entries have been sorted equally.
> > For me it is much better arranged this way, the mass of different files where just to confusing and the
> > original files have already been removed anyway.
> > But I may revert that if necessary.

No need to revert.

> >
> > Title and chapter-styles has been changed to the suggested ones in "/doc-guide/sphinx.html#writing-documentation".
> >
> > There are still some "Duplicate C++ declaration, ..." warnings. Renaming doesn't work either: 'unknown option: "name"'

Don't care about that. There's a known bug on Sphinx related to it since
version 3.x (present at least until at least version 5). Basically, if
a struct has the same name of a function, for instance, it will generate
warnings.

> > I haven't found any useful hint how to get rid of them.
> > Should I switch to "code-block:: c" instead?
> > But there are a lot of this warnings from other files too. It seems I'm mot the only one with this problem.  
> I switched to "code-block".
> Now there are no warnings anymore.

For things like ioctl, code-blocks are preferred. For other things,
better to keep the warnings and not use code-block where not needed. The
warnings are part of the Sphinx cross-reference system, which tries to
create references to the C domain functions and data types.

Unfortunately, Sphinx has a known bug that it is hit when the same symbol
name is used with different meanings e.g., on C declarations like those:

	struct foo;
	enum foo;
	typedef foo;
	foo() {}

Each one has a different type. So, `foo` cross-references depend on
the context. Right now, Sphinx will just consider them to be attempts
to re-define an existing name. There's already patches fixing it
Sphinx upstream, but (last time I checked) not applied yet as those
would cause regressions on intersphinx.

> This functions shouldn't be referenced from outside this document anyway.

No, we link the header files with the documentation, exactly to
generate cross-references and detect gaps at the docs.

> Lets hope, the robot likes it better this way :-).
> 
> Regards
> Stefan
> 
> >
> >
> > Please point out, if something is missing, wrong or need to be improved. I will try to fix it.
> >
> > Regards
> > Stefan
> >
> > p.s. It is my first try to submit a patch this way. I hope my mail-client doesn't mess it up.
> >  
> 
> 
> This patch is largely based on the already existing documentation and the header files
> 
> 
> | Reported-by: kernel test robot <lkp@intel.com>
> | Link: https://lore.kernel.org/oe-kbuild-all/202303251637.x35nzuXi-lkp@intel.com/
> 
> 
> Signed-off-by: Stefan Herdler <herdler@nurfuerspam.de>
> 
> diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst
> index b97d56ee543c..ffe8325749e5 100644
> --- a/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst
> +++ b/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst
> @@ -23,3 +23,4 @@ DVB-S2, DVB-T2, ISDB, etc.
>      :maxdepth: 1
> 
>      frontend_legacy_dvbv3_api
> +    legacy_dvb_decoder_api
> diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst
> new file mode 100644
> index 000000000000..b4f75643c21f
> --- /dev/null
> +++ b/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst
> @@ -0,0 +1,1280 @@
> +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

Please place it dual licensed with GFDL and GPL 2.0.

> +
> +.. _dvb_audio:
> +
> +================
> +DVB Audio Device
> +================
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +The DVB audio device controls the MPEG2 audio decoder of the DVB
> +hardware. It can be accessed through ``/dev/dvb/adapter?/audio?``. Data
> +types and ioctl definitions can be accessed by including
> +``linux/dvb/audio.h`` in your application.
> +
> +Please note that most DVB cards don’t have their own MPEG decoder, which
> +results in the omission of the audio and video device.
> +
> +These ioctls were also used by V4L2 to control MPEG decoders implemented
> +in V4L2. The use of these ioctls for that purpose has been made obsolete
> +and proper V4L2 ioctls or controls have been created to replace that
> +functionality. Use :ref:`V4L2 ioctls<video>` for new drivers!
> +
> +
> +
> +Audio Data Types
> +================
> +
> +This section describes the structures, data types and defines used when
> +talking to the audio device.
> +
> +
> +
> +audio_stream_source_t
> +---------------------
> +
> +The audio stream source is set through the `AUDIO_SELECT_SOURCE`_ call
> +and can take the following values, depending on whether we are replaying
> +from an internal (demux) or external (user write) source.
> +
> +
> +.. code-block:: c
> +
> +    typedef enum {
> +	AUDIO_SOURCE_DEMUX,
> +	AUDIO_SOURCE_MEMORY
> +    } audio_stream_source_t;
> +
> +AUDIO_SOURCE_DEMUX selects the demultiplexer (fed either by the
> +frontend or the DVR device) as the source of the video stream. If
> +AUDIO_SOURCE_MEMORY is selected the stream comes from the application
> +through the `write()`_ system call.
> +
> +
> +audio_play_state_t
> +------------------
> +
> +The following values can be returned by the `AUDIO_GET_STATUS`_ call
> +representing the state of audio playback.
> +
> +
> +.. code-block:: c
> +
> +    typedef enum {
> +	AUDIO_STOPPED,
> +	AUDIO_PLAYING,
> +	AUDIO_PAUSED
> +    } audio_play_state_t;

Those are kind of obvious, but still the best would be to have documentation
for all enums/typedefs. 

> +
> +
> +audio_channel_select_t
> +----------------------
> +
> +The audio channel selected via `AUDIO_CHANNEL_SELECT`_ is determined by
> +the following values.
> +
> +
> +.. code-block:: c
> +
> +    typedef enum {
> +	AUDIO_STEREO,
> +	AUDIO_MONO_LEFT,
> +	AUDIO_MONO_RIGHT,
> +	AUDIO_MONO,
> +	AUDIO_STEREO_SWAPPED
> +    } audio_channel_select_t;

Here too. 

> +
> +
> +audio_mixer
> +-----------
> +
> +The following structure is used by the `AUDIO_SET_MIXER`_ call to set the
> +audio volume.
> +
> +
> +.. code-block:: c
> +
> +    typedef struct audio_mixer {
> +	unsigned int volume_left;
> +	unsigned int volume_right;
> +    } audio_mixer_t;

And here. In special, what are the maximum values for the volume?

> +
> +
> +audio_status
> +------------
> +
> +The `AUDIO_GET_STATUS`_ call returns the following structure informing
> +about various states of the playback operation.
> +
> +
> +.. code-block:: c
> +
> +    typedef struct audio_status {
> +	boolean AV_sync_state;
> +	boolean mute_state;
> +	audio_play_state_t play_state;
> +	audio_stream_source_t stream_source;
> +	audio_channel_select_t channel_select;
> +	boolean bypass_mode;
> +	audio_mixer_t mixer_state;
> +    } audio_status_t;

Each field should be described.

> +
> +
> +audio encodings
> +---------------
> +
> +A call to `AUDIO_GET_CAPABILITIES`_ returns an unsigned integer with the
> +following bits set according to the hardwares capabilities.
> +
> +
> +.. code-block:: c
> +
> +     #define AUDIO_CAP_DTS    1
> +     #define AUDIO_CAP_LPCM   2
> +     #define AUDIO_CAP_MP1    4
> +     #define AUDIO_CAP_MP2    8
> +     #define AUDIO_CAP_MP3   16
> +     #define AUDIO_CAP_AAC   32
> +     #define AUDIO_CAP_OGG   64
> +     #define AUDIO_CAP_SDDS 128
> +     #define AUDIO_CAP_AC3  256

Same here. This is probably not too hard, as they seems to belong
to some old DVB spec (there are more audio standards added on
newer versions of ETSI specs).

> +CEC_ADAP_G_CONNECTOR_INFO

Huh? Cut and paste issue?


> +
> +Audio Function Calls
> +====================
> +
> +
> +AUDIO_STOP
> +----------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	 int ioctl(int fd, int request = AUDIO_STOP)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals AUDIO_STOP for this command.
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl call asks the Audio Device to stop playing the current
> +stream.
> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +AUDIO_PLAY
> +----------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	 int  ioctl(int fd, int request = AUDIO_PLAY)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals AUDIO_PLAY for this command.
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl call asks the Audio Device to start playing an audio stream
> +from the selected source.
> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +AUDIO_PAUSE
> +-----------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	 int  ioctl(int fd, int request = AUDIO_PAUSE)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.

Cross references to syscalls are hard, as each filesystem has its
own definition. On DVB, each subset of the API also has it ;-)

We need to place them inside a namespace in order for the cross
references to point to the right ones.

See, for instance c:namespace:: DTV.ca and other similar definitions.

Without that, you'll be generating duplicated symbols and broken
cross references.

> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals AUDIO_PAUSE for this command.
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl call suspends the audio stream being played. Decoding and
> +playing are paused. It is then possible to restart again decoding and
> +playing process of the audio stream using `AUDIO_CONTINUE`_ command.
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +AUDIO_CONTINUE
> +--------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	 int  ioctl(int fd, int request = AUDIO_CONTINUE)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals AUDIO_CONTINUE for this command.
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl restarts the decoding and playing process previously paused
> +with `AUDIO_PAUSE`_ command.
> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +AUDIO_SELECT_SOURCE
> +-------------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	 int ioctl(int fd, int request = AUDIO_SELECT_SOURCE, audio_stream_source_t source)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals AUDIO_SELECT_SOURCE for this command.
> +
> +    -  .. row 3
> +
> +       -  `audio_stream_source_t`_ source
> +
> +       -  Indicates the source that shall be used for the Audio stream.
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl call informs the audio device which source shall be used for
> +the input data. The possible sources are demux or memory. If
> +AUDIO_SOURCE_MEMORY is selected, the data is fed to the Audio Device
> +through the write command.

Please also describe AUDIO_SOURCE_DEMUX.

FYI, this is one of the problems with this API, there are just two
possibilities there: AUDIO_SOURCE_DEMUX or AUDIO_SOURCE_MEMORY. This
doesn't work on devices that have multiple demuxes and multiple
tuners.

See, this API is interesting for embedded hardware which are the
ones that may actually have audio and video decoders those days.
However, they all offer multiple possibilities to setup audio and
video pipelines.

> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +AUDIO_SET_MUTE
> +--------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	 int  ioctl(int fd, int request = AUDIO_SET_MUTE, boolean state)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals AUDIO_SET_MUTE for this command.
> +
> +    -  .. row 3
> +
> +       -  boolean state
> +
> +       -  Indicates if audio device shall mute or not.

Please be clearer what 0 indicates and what other values
indicate (Kernel receives an integer for ioctl arguments, and not a
boolean, so internally is not really a boolean). From av7110:

	case AUDIO_SET_MUTE:
        {
                ret = audcom(av7110, arg ? AUDIO_CMD_MUTE : AUDIO_CMD_UNMUTE);
                if (!ret)
                        av7110->audiostate.mute_state = (int) arg;
                break;
        }

0 means unmuted. Any other value means muted.

> +
> +    -  .. row 4
> +
> +       -
> +       -  TRUE Audio Mute
> +
> +    -  .. row 5
> +
> +       -
> +       -  FALSE Audio Un-mute

There are just 3 arguments, and not 5 ones ;-)

> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl is for DVB devices only. To control a V4L2 decoder use the
> +V4L2 :ref:`VIDIOC_DECODER_CMD` with the
> +``V4L2_DEC_CMD_START_MUTE_AUDIO`` flag instead.
> +
> +This ioctl call asks the audio device to mute the stream that is
> +currently being played.
> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +AUDIO_SET_AV_SYNC
> +-----------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	 int  ioctl(int fd, int request = AUDIO_SET_AV_SYNC, boolean state)
> +
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals AUDIO_AV_SYNC for this command.
> +
> +    -  .. row 3
> +
> +       -  boolean state
> +
> +       -  Tells the DVB subsystem if A/V synchronization shall be ON or OFF.
> +
> +    -  .. row 4
> +
> +       -
> +       -  TRUE AV-sync ON
> +
> +    -  .. row 5
> +
> +       -
> +       -  FALSE AV-sync OFF

Same here (and on other booleans): use 3 rows, and at the "boolean"
explains what zero means and what non-zero means.

> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl call asks the Audio Device to turn ON or OFF A/V
> +synchronization.
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +AUDIO_SET_BYPASS_MODE
> +---------------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	 int ioctl(int fd, int request = AUDIO_SET_BYPASS_MODE, boolean mode)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals AUDIO_SET_BYPASS_MODE for this command.
> +
> +    -  .. row 3
> +
> +       -  boolean mode
> +
> +       -  Enables or disables the decoding of the current Audio stream in
> +	  the DVB subsystem.
> +
> +    -  .. row 4
> +
> +       -
> +       -  TRUE Bypass is disabled
> +
> +    -  .. row 5
> +
> +       -
> +       -  FALSE Bypass is enabled
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl call asks the Audio Device to bypass the Audio decoder and
> +forward the stream without decoding. This mode shall be used if streams
> +that can’t be handled by the DVB system shall be decoded. Dolby
> +DigitalTM streams are automatically forwarded by the DVB subsystem if
> +the hardware can handle it.
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +AUDIO_CHANNEL_SELECT
> +--------------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	 int ioctl(int fd, int request = AUDIO_CHANNEL_SELECT, audio_channel_select_t)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals AUDIO_CHANNEL_SELECT for this command.
> +
> +    -  .. row 3
> +
> +       -  `audio_channel_select_t`_ ch
> +
> +       -  Select the output format of the audio (mono left/right, stereo).
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl is for DVB devices only. To control a V4L2 decoder use the
> +V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK`` control instead.
> +
> +This ioctl call asks the Audio Device to select the requested channel if
> +possible.
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +AUDIO_GET_STATUS
> +----------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	 int ioctl(int fd, int request = AUDIO_GET_STATUS, struct audio_status *status)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals AUDIO_GET_STATUS for this command.
> +
> +    -  .. row 3
> +
> +       -  struct `audio_status`_ \*status
> +
> +       -  Returns the current state of Audio Device.
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl call asks the Audio Device to return the current state of the
> +Audio Device.
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +AUDIO_GET_CAPABILITIES
> +----------------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	 int ioctl(int fd, int request = AUDIO_GET_CAPABILITIES, unsigned int *cap)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals AUDIO_GET_CAPABILITIES for this command.
> +
> +    -  .. row 3
> +
> +       -  unsigned int \*cap
> +
> +       -  Returns a bit array of supported sound formats.
> +          Bits are defined in `audio encodings`_.
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl call asks the Audio Device to tell us about the decoding
> +capabilities of the audio hardware.
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +AUDIO_CLEAR_BUFFER
> +------------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	 int  ioctl(int fd, int request = AUDIO_CLEAR_BUFFER)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals AUDIO_CLEAR_BUFFER for this command.
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl call asks the Audio Device to clear all software and hardware
> +buffers of the audio decoder device.
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +AUDIO_SET_ID
> +------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	 int  ioctl(int fd, int request = AUDIO_SET_ID, int id)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals AUDIO_SET_ID for this command.
> +
> +    -  .. row 3
> +
> +       -  int id
> +
> +       -  audio sub-stream id
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl selects which sub-stream is to be decoded if a program or
> +system stream is sent to the video device. If no audio stream type is
> +set the id has to be in [0xC0,0xDF] for MPEG sound, in [0x80,0x87] for
> +AC3 and in [0xA0,0xA7] for LPCM. More specifications may follow for
> +other stream types. If the stream type is set the id just specifies the
> +substream id of the audio stream and only the first 5 bits are
> +recognized.

Hmm... "More specifications may follow for other stream types". What do
you mean?

As this API is legacy, and supports only a limited set of standards,
I would place here the valid values for the av7110 driver.

"First 5 bits" is vage. Are the 5 LSB bytes? the 5 MSB bytes?

Also, is it big endian, little endian or cpu's endian?

Btw, this doesn't seem to be used on av7110. Now, I don't mind having it
documented there if used by some other OOT driver, provided that it 
defines a clear API - e. g. what is the bit order and valid values
(it could be a pointer to ETSI docs in case you don't want to define
everything).

> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +AUDIO_SET_MIXER
> +---------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	 int ioctl(int fd, int request = AUDIO_SET_MIXER, audio_mixer_t *mix)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals AUDIO_SET_ID for this command.

Huh? I guess you meant AUDIO_SET_MIXER.

> +
> +    -  .. row 3
> +
> +       -  audio_mixer_t \*mix
> +
> +       -  mixer settings.
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl lets you adjust the mixer settings of the audio decoder.
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +
> +AUDIO_SET_STREAMTYPE
> +--------------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	 int  ioctl(fd, int request = AUDIO_SET_STREAMTYPE, int type)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals AUDIO_SET_STREAMTYPE for this command.
> +
> +    -  .. row 3
> +
> +       -  int type
> +
> +       -  stream type

What's the meaning of type?

Btw, av7110 doesn't seem to be using it.

> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl tells the driver which kind of audio stream to expect. This
> +is useful if the stream offers several audio sub-streams like LPCM and
> +AC3.
> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  ``EINVAL``
> +
> +       -  type is not a valid or supported stream type.
> +
> +
> +
> +AUDIO_BILINGUAL_CHANNEL_SELECT
> +------------------------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	 int ioctl(int fd, int request = AUDIO_BILINGUAL_CHANNEL_SELECT, audio_channel_select_t)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals AUDIO_BILINGUAL_CHANNEL_SELECT for this command.
> +
> +    -  .. row 3
> +
> +       -  audio_channel_select_t ch
> +
> +       -  Select the output format of the audio (mono left/right, stereo).

IMO, this is also another problematic API. Its name seems to be related
to language selection. However, multi-language usually uses different
PIDs. Maybe in the past they used to place two languages at the same
PID, one at the left channel and the other at the right one?

> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl has been replaced by the V4L2
> +``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK`` control
> +for MPEG decoders controlled through V4L2.
> +
> +This ioctl call asks the Audio Device to select the requested channel
> +for bilingual streams if possible.
> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +
> +open()
> +------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	 int  open(const char *deviceName, int flags)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  const char \*deviceName
> +
> +       -  Name of specific audio device.
> +
> +    -  .. row 2
> +
> +       -  int flags
> +
> +       -  A bit-wise OR of the following flags:
> +
> +    -  .. row 3
> +
> +       -
> +       -  O_RDONLY read-only access
> +
> +    -  .. row 4
> +
> +       -
> +       -  O_RDWR read/write access
> +
> +    -  .. row 5
> +
> +       -
> +       -  O_NONBLOCK open in non-blocking mode
> +
> +    -  .. row 6
> +
> +       -
> +       -  (blocking mode is the default)
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +This system call opens a named audio device (e.g.
> +/dev/dvb/adapter0/audio0) for subsequent use. When an open() call has
> +succeeded, the device will be ready for use. The significance of
> +blocking or non-blocking mode is described in the documentation for
> +functions where there is a difference. It does not affect the semantics
> +of the open() call itself. A device opened in blocking mode can later be
> +put into non-blocking mode (and vice versa) using the F_SETFL command
> +of the fcntl system call. This is a standard system call, documented in
> +the Linux manual page for fcntl. Only one user can open the Audio Device
> +in O_RDWR mode. All other attempts to open the device in this mode will
> +fail, and an error code will be returned. If the Audio Device is opened
> +in O_RDONLY mode, the only ioctl call that can be used is
> +`AUDIO_GET_STATUS`_. All other call will return with an error code.
> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  ``ENODEV``
> +
> +       -  Device driver not loaded/available.
> +
> +    -  .. row 2
> +
> +       -  ``EBUSY``
> +
> +       -  Device or resource busy.
> +
> +    -  .. row 3
> +
> +       -  ``EINVAL``
> +
> +       -  Invalid argument.
> +
> +
> +close()
> +-------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	 int  close(int fd)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +This system call closes a previously opened audio device.
> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  ``EBADF``
> +
> +       -  fd is not a valid open file descriptor.
> +
> +
> +
> +write()
> +-------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	 size_t write(int fd, const void *buf, size_t count)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  void \*buf
> +
> +       -  Pointer to the buffer containing the PES data.
> +
> +    -  .. row 3
> +
> +       -  size_t count
> +
> +       -  Size of buf.
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +This system call can only be used if AUDIO_SOURCE_MEMORY is selected
> +in the ioctl call `AUDIO_SELECT_SOURCE`_. The data provided shall be in
> +PES format. If O_NONBLOCK is not specified the function will block
> +until buffer space is available. The amount of data to be transferred is
> +implied by count.
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  ``EPERM``
> +
> +       -  Mode AUDIO_SOURCE_MEMORY not selected.
> +
> +    -  .. row 2
> +
> +       -  ``ENOMEM``
> +
> +       -  Attempted to write more data than the internal buffer can hold.
> +
> +    -  .. row 3
> +
> +       -  ``EBADF``
> +
> +       -  fd is not a valid open file descriptor.



> diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst
> new file mode 100644
> index 000000000000..566aa7b8eee6
> --- /dev/null
> +++ b/Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst

Better to send a patch series, with one patch per API. Makes easier
to review.

> @@ -0,0 +1,61 @@
> +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
> +
> +.. _legacy_dvb_decoder_api:
> +
> +============================
> +Legacy DVB MPEG Decoder APIs
> +============================
> +
> +.. _legacy_dvb_decoder_notes:
> +
> +General Notes
> +=============
> +
> +This API has originally been designed for DVB only and is therefore limited to
> +the :ref:`legacy_dvb_decoder_formats` used in such digital TV-broadcastsystems.
> +
> +To circumvent this limitations the more versatile :ref:`V4L2 <v4l2spec>` API has
> +been designed. Which replaces this part of the DVB API.
> +
> +Nevertheless there have been projects build around this API.
> +To ensure compatibility this API is kept as it is.
> +
> +.. attention:: Do **not** use this API in new drivers!
> +
> +    For audio and video use the :ref:`V4L2 <v4l2spec>` and ALSA APIs.
> +
> +    Pipelines should be set up using the :ref:`Media Controller  API<media_controller>`.
> +
> +Practically the decoders seem to be treated differently. The application typically
> +knows which decoder is in use or it is specially written for one decoder type.
> +Querying capabilities are rarely used because they are already known.
> +
> +.. _legacy_dvb_decoder_formats:
> +
> +Data Formats
> +============
> +
> +The API has been designed for DVB and compatible broadcastsystems.
> +Because of that fact the only supported data formats are ISO/IEC 13818-1
> +compatible MPEG streams. The supported payloads may vary depending on the
> +used decoder.
> +
> +Timestamps are always MPEG PTS as defined in ITU T-REC-H.222.0 /
> +ISO/IEC 13818-1, if not otherwise noted.
> +
> +For storing recordings typically TS streams are used, in lesser extent PES.
> +Both variants are commonly accepted for playback, but it may be driver dependent.
> +
> +
> +
> +
> +Table of Contents
> +=================
> +
> +.. toctree::
> +    :maxdepth: 2
> +
> +    legacy_dvb_video
> +    legacy_dvb_audio
> +    legacy_dvb_osd
> +
> diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst
> new file mode 100644
> index 000000000000..2174440e77c5
> --- /dev/null
> +++ b/Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst
> @@ -0,0 +1,444 @@
> +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
> +
> +.. _dvb_osd:
> +
> +==============
> +DVB OSD Device
> +==============
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +The DVB OSD Device controls the OnScreenDisplay of the AV7110 based
> +DVB-cards with hardware MPEG2 decoder. It can be accessed through ``/dev/dvb/adapter?/osd0``.
> +Data types and ioctl definitions can be accessed by including
> +``linux/dvb/osd.h`` in your application.
> +
> +The OSD is not a framebuffer like on many other cards.
> +It is a kind of canvas one can draw on.
> +The colordepth is limited depending on the memorysize installed. An appropriate palette
> +of colors has to be set up.
> +The installed memory size can be identified with the `OSD_GET_CAPABILITY`_ ioctl.
> +
> +OSD Data Types
> +==============
> +
> +OSD_Command
> +-----------
> +
> +The ``OSD_Command`` data type defined by
> +
> +.. code-block:: c
> +
> +    typedef enum {
> +	/* All functions return -2 on "not open" */
> +	OSD_Close = 1,	/* () */
> +	/*
> +	 * Disables OSD and releases the buffers
> +	 * returns 0 on success
> +	 */
> +	OSD_Open,	/* (x0,y0,x1,y1,BitPerPixel[2/4/8](color&0x0F),mix[0..15](color&0xF0)) */
> +	/*
> +	 * Opens OSD with this size and bit depth
> +	 * returns 0 on success, -1 on DRAM allocation error, -2 on "already open"
> +	 */
> +	OSD_Show,	/* () */
> +	/*
> +	 * enables OSD mode
> +	 * returns 0 on success
> +	 */
> +	OSD_Hide,	/* () */
> +	/*
> +	 * disables OSD mode
> +	 * returns 0 on success
> +	 */
> +	OSD_Clear,	/* () */
> +	/*
> +	 * Sets all pixel to color 0
> +	 * returns 0 on success
> +	 */
> +	OSD_Fill,	/* (color) */
> +	/*
> +	 * Sets all pixel to color <col>
> +	 * returns 0 on success
> +	 */
> +	OSD_SetColor,	/* (color,R{x0},G{y0},B{x1},opacity{y1}) */
> +	/*
> +	 * set palette entry <num> to <r,g,b>, <mix> and <trans> apply
> +	 * R,G,B: 0..255
> +	 * R=Red, G=Green, B=Blue
> +	 * opacity=0:      pixel opacity 0% (only video pixel shows)
> +	 * opacity=1..254: pixel opacity as specified in header
> +	 * opacity=255:    pixel opacity 100% (only OSD pixel shows)
> +	 * returns 0 on success, -1 on error
> +	 */
> +	OSD_SetPalette,	/* (firstcolor{color},lastcolor{x0},data) */
> +	/*
> +	 * Set a number of entries in the palette
> +	 * sets the entries "firstcolor" through "lastcolor" from the array "data"
> +	 * data has 4 byte for each color:
> +	 * R,G,B, and a opacity value: 0->transparent, 1..254->mix, 255->pixel
> +	 */
> +	OSD_SetTrans,	/* (transparency{color}) */
> +	/*
> +	 * Sets transparency of mixed pixel (0..15)
> +	 * returns 0 on success
> +	 */
> +	OSD_SetPixel,	/* (x0,y0,color) */
> +	/*
> +	 * sets pixel <x>,<y> to color number <col>
> +	 * returns 0 on success, -1 on error
> +	 */
> +	OSD_GetPixel,	/* (x0,y0) */
> +	/* returns color number of pixel <x>,<y>,  or -1 */
> +	OSD_SetRow,	/* (x0,y0,x1,data) */
> +	/*
> +	 * fills pixels x0,y through  x1,y with the content of data[]
> +	 * returns 0 on success, -1 on clipping all pixel (no pixel drawn)
> +	 */
> +	OSD_SetBlock,	/* (x0,y0,x1,y1,increment{color},data) */
> +	/*
> +	 * fills pixels x0,y0 through  x1,y1 with the content of data[]
> +	 * inc contains the width of one line in the data block,
> +	 * inc<=0 uses blockwidth as linewidth
> +	 * returns 0 on success, -1 on clipping all pixel
> +	 */
> +	OSD_FillRow,	/* (x0,y0,x1,color) */
> +	/*
> +	 * fills pixels x0,y through  x1,y with the color <col>
> +	 * returns 0 on success, -1 on clipping all pixel
> +	 */
> +	OSD_FillBlock,	/* (x0,y0,x1,y1,color) */
> +	/*
> +	 * fills pixels x0,y0 through  x1,y1 with the color <col>
> +	 * returns 0 on success, -1 on clipping all pixel
> +	 */
> +	OSD_Line,	/* (x0,y0,x1,y1,color) */
> +	/*
> +	 * draw a line from x0,y0 to x1,y1 with the color <col>
> +	 * returns 0 on success
> +	 */
> +	OSD_Query,	/* (x0,y0,x1,y1,xasp{color}}), yasp=11 */
> +	/*
> +	 * fills parameters with the picture dimensions and the pixel aspect ratio
> +	 * returns 0 on success
> +	 */
> +	OSD_Test,       /* () */
> +	/*
> +	 * draws a test picture. for debugging purposes only
> +	 * returns 0 on success
> +	 * TODO: remove "test" in final version
> +	 */
> +	OSD_Text,	/* (x0,y0,size,color,text) */
> +	OSD_SetWindow,	/* (x0) set window with number 0<x0<8 as current */
> +	OSD_MoveWindow,	/* move current window to (x0, y0) */
> +	OSD_OpenRaw,	/* Open other types of OSD windows */
> +    } OSD_Command;
> +
> +is used with the `OSD_SEND_CMD`_ ioctl to tell the driver which OSD_Command to execute.
> +
> +osd_cmd_t
> +---------
> +
> +The ``osd_cmd_t`` data type defined by
> +
> +.. code-block:: c
> +
> +    typedef struct osd_cmd_s {
> +	OSD_Command cmd;
> +	int x0;
> +	int y0;
> +	int x1;
> +	int y1;
> +	int color;
> +	void __user *data;
> +    } osd_cmd_t;
> +
> +is used with the `OSD_SEND_CMD`_ ioctl.
> +It contains the data for the OSD_Command and the `OSD_Command`_ itself.
> +
> +
> +osd_raw_window_t
> +----------------
> +
> +The ``osd_raw_window_t`` data type defined by
> +
> +.. code-block:: c
> +
> +    /* OSD_OpenRaw: set 'color' to desired window type */
> +    typedef enum {
> +	OSD_BITMAP1,           /* 1 bit bitmap */
> +	OSD_BITMAP2,           /* 2 bit bitmap */
> +	OSD_BITMAP4,           /* 4 bit bitmap */
> +	OSD_BITMAP8,           /* 8 bit bitmap */
> +	OSD_BITMAP1HR,         /* 1 Bit bitmap half resolution */
> +	OSD_BITMAP2HR,         /* 2 bit bitmap half resolution */
> +	OSD_BITMAP4HR,         /* 4 bit bitmap half resolution */
> +	OSD_BITMAP8HR,         /* 8 bit bitmap half resolution */
> +	OSD_YCRCB422,          /* 4:2:2 YCRCB Graphic Display */
> +	OSD_YCRCB444,          /* 4:4:4 YCRCB Graphic Display */
> +	OSD_YCRCB444HR,        /* 4:4:4 YCRCB graphic half resolution */
> +	OSD_VIDEOTSIZE,        /* True Size Normal MPEG Video Display */
> +	OSD_VIDEOHSIZE,        /* MPEG Video Display Half Resolution */
> +	OSD_VIDEOQSIZE,        /* MPEG Video Display Quarter Resolution */
> +	OSD_VIDEODSIZE,        /* MPEG Video Display Double Resolution */
> +	OSD_VIDEOTHSIZE,       /* True Size MPEG Video Display Half Resolution */
> +	OSD_VIDEOTQSIZE,       /* True Size MPEG Video Display Quarter Resolution*/
> +	OSD_VIDEOTDSIZE,       /* True Size MPEG Video Display Double Resolution */
> +	OSD_VIDEONSIZE,        /* Full Size MPEG Video Display */
> +	OSD_CURSOR             /* Cursor */
> +    } osd_raw_window_t;
> +
> +is used to tell the `OSD_Command`_ OSD_OpenRaw which type of OSD to open.
> +
> +osd_cap_t
> +---------
> +
> +The following is the structure of data returned by the `OSD_GET_CAPABILITY`_ call.
> +
> +The ``osd_cap_t`` data type defined by
> +
> +.. code-block:: c
> +
> +    typedef struct osd_cap_s {
> +	int  cmd;
> +    #define OSD_CAP_MEMSIZE         1  /* memory size */
> +	long val;
> +    } osd_cap_t;
> +
> +OSD Function Calls
> +==================
> +
> +OSD_SEND_CMD
> +------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +    int ioctl(int fd, int request = OSD_SEND_CMD, enum osd_cmd_t *cmd)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals `osd_cmd_t`_ for this command.
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl sends the `OSD_Command`_ to the card.
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.

It is probably a good idea to mention the error code when command
is out of range.

> +
> +OSD_GET_CAPABILITY
> +------------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +    int ioctl(int fd, int request = OSD_GET_CAPABILITY, struct osd_cap_t *cap)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals OSD_GET_CAPABILITY for this command.
> +
> +    -  .. row 3
> +
> +       -  unsigned int \*cap
> +
> +       -  Pointer to a location where to store the capability information.

Huh? Isn't struct osd_cap_t a structure with cmd, value?

Also, from the implementation, cap->cmd needs to be filled by userspace.
You'll need to describe it, and what are the acceptable values and
value ranges. The av7110 supports just one cmd:

        switch (cap->cmd) {
        case OSD_CAP_MEMSIZE:
                if (FW_4M_SDRAM(av7110->arm_app))
                        cap->val = 1000000;
                else
                        cap->val = 92000;
                return 0;
        default:
                return -EINVAL;
        }

You should probably tell that -EINVAL means that the capability is
not supported.

> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl is used to get the capabilities of the OSD of the AV7110 based DVB-decoder-card in use.
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +open()
> +------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +    int open(const char *deviceName, int flags)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  const char \*deviceName
> +
> +       -  Name of specific OSD device.
> +
> +    -  .. row 2
> +
> +       -  int flags
> +
> +       -  A bit-wise OR of the following flags:
> +
> +    -  .. row 3
> +
> +       -
> +       -  O_RDONLY read-only access
> +
> +    -  .. row 4
> +
> +       -
> +       -  O_RDWR read/write access
> +
> +    -  .. row 5
> +
> +       -
> +       -  O_NONBLOCK open in non-blocking mode
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +This system call opens a named OSD device (e.g.
> +/dev/dvb/adapter?/osd0) for subsequent use.
> +
> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  ``ENODEV``
> +
> +       -  Device driver not loaded/available.
> +
> +    -  .. row 2
> +
> +       -  ``EINTERNAL``
> +
> +       -  Internal error.
> +
> +    -  .. row 3
> +
> +       -  ``EBUSY``
> +
> +       -  Device or resource busy.
> +
> +    -  .. row 4
> +
> +       -  ``EINVAL``
> +
> +       -  Invalid argument.
> +
> +close()
> +-------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +    int close(int fd)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_ .
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +This system call closes a previously opened OSD device.
> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  ``EBADF``
> +
> +       -  fd is not a valid open file descriptor.
> +
> diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst
> new file mode 100644
> index 000000000000..ae0c1e8a54b8
> --- /dev/null
> +++ b/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst
> @@ -0,0 +1,1768 @@
> +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
> +
> +.. _dvb_video:
> +
> +================
> +DVB Video Device
> +================
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +The DVB video device controls the MPEG2 video decoder of the DVB
> +hardware. It can be accessed through ``/dev/dvb/adapter0/video0``. Data
> +types and ioctl definitions can be accessed by including
> +``linux/dvb/video.h`` in your application.
> +
> +Note that the DVB video device only controls decoding of the MPEG video
> +stream, not its presentation on the TV or computer screen. On PCs this
> +is typically handled by an associated video4linux device, e.g.
> +``/dev/video``, which allows scaling and defining output windows.
> +
> +Most DVB cards don’t have their own MPEG decoder, which results in the
> +omission of the audio and video device as well as the video4linux
> +device.
> +
> +These ioctls were also used by V4L2 to control MPEG decoders implemented
> +in V4L2. The use of these ioctls for that purpose has been made obsolete
> +and proper V4L2 ioctls or controls have been created to replace that
> +functionality. Use :ref:`V4L2 ioctls<video>` for new drivers!
> +
> +
> +Video Data Types
> +================
> +
> +
> +video_format_t
> +--------------
> +
> +The ``video_format_t`` data type defined by
> +
> +
> +.. code-block:: c
> +
> +    typedef enum {
> +	VIDEO_FORMAT_4_3,     /* Select 4:3 format */
> +	VIDEO_FORMAT_16_9,    /* Select 16:9 format. */
> +	VIDEO_FORMAT_221_1    /* 2.21:1 */
> +    } video_format_t;
> +
> +is used in the `VIDEO_SET_FORMAT`_ function to tell the driver which
> +aspect ratio the output hardware (e.g. TV) has. It is also used in the
> +data structures `video_status`_ returned by `VIDEO_GET_STATUS`_
> +and `video_event`_ returned by `VIDEO_GET_EVENT`_ which report
> +about the display format of the current video stream.
> +
> +
> +video_displayformat_t
> +---------------------
> +
> +In case the display format of the video stream and of the display
> +hardware differ the application has to specify how to handle the
> +cropping of the picture. This can be done using the
> +`VIDEO_SET_DISPLAY_FORMAT`_ call which accepts
> +
> +
> +.. code-block:: c
> +
> +    typedef enum {
> +	VIDEO_PAN_SCAN,       /* use pan and scan format */
> +	VIDEO_LETTER_BOX,     /* use letterbox format */
> +	VIDEO_CENTER_CUT_OUT  /* use center cut out format */
> +    } video_displayformat_t;
> +
> +as argument.
> +
> +
> +video_size_t
> +------------
> +
> +Used in the struct `video_event`_. It stores the resolution and
> +aspect ratio of the video.
> +
> +.. code-block:: c
> +
> +    typedef struct {
> +	int w;
> +	int h;
> +	video_format_t aspect_ratio;
> +    } video_size_t;
> +
> +
> +video_stream_source_t
> +---------------------
> +
> +The video stream source is set through the `VIDEO_SELECT_SOURCE`_ call
> +and can take the following values, depending on whether we are replaying
> +from an internal (demuxer) or external (user write) source.
> +
> +
> +.. code-block:: c
> +
> +    typedef enum {
> +	VIDEO_SOURCE_DEMUX, /* Select the demux as the main source */
> +	VIDEO_SOURCE_MEMORY /* If this source is selected, the stream
> +		       comes from the user through the write
> +		       system call */
> +    } video_stream_source_t;

FYI, this carries the same problem as the audio one: this API is problematic
for modern hardware that has multiple tuners and demuxers. Setting up 
pipelines for audio and video decoding on modern hardware require a lot 
more than just demux/memory.

> +
> +VIDEO_SOURCE_DEMUX selects the demultiplexer (fed either by the
> +frontend or the DVR device) as the source of the video stream. If
> +VIDEO_SOURCE_MEMORY is selected the stream comes from the application
> +through the `write()`_ system call.
> +
> +
> +video_play_state_t
> +------------------
> +
> +The following values can be returned by the `VIDEO_GET_STATUS`_ call
> +representing the state of video playback.
> +
> +
> +.. code-block:: c
> +
> +    typedef enum {
> +	VIDEO_STOPPED, /* Video is stopped */
> +	VIDEO_PLAYING, /* Video is currently playing */
> +	VIDEO_FREEZED  /* Video is freezed */
> +    } video_play_state_t;
> +
> +
> +struct video_command
> +--------------------
> +
> +The structure must be zeroed before use by the application. This ensures
> +it can be extended safely in the future.
> +
> +
> +.. code-block:: c
> +
> +    struct video_command {
> +	__u32 cmd;
> +	__u32 flags;
> +	union {
> +	    struct {
> +		__u64 pts;
> +	    } stop;
> +
> +	    struct {
> +		/* 0 or 1000 specifies normal speed,
> +		   1 specifies forward single stepping,
> +		   -1 specifies backward single stepping,
> +		   >>1: playback at speed/1000 of the normal speed,

I guess you meant > 1, right?

> +		   <-1: reverse playback at (-speed/1000) of the normal speed. */
> +		__s32 speed;
> +		__u32 format;
> +	    } play;
> +
> +	    struct {
> +		__u32 data[16];
> +	    } raw;
> +	};
> +    };
> +
> +
> +Predefined decoder commands and flags:
> +
> +.. code-block:: c
> +
> +    /* Decoder commands */
> +    #define VIDEO_CMD_PLAY        (0)
> +    #define VIDEO_CMD_STOP        (1)
> +    #define VIDEO_CMD_FREEZE      (2)
> +    #define VIDEO_CMD_CONTINUE    (3)
> +
> +    /* Flags for VIDEO_CMD_FREEZE */
> +    #define VIDEO_CMD_FREEZE_TO_BLACK	(1 << 0)
> +
> +    /* Flags for VIDEO_CMD_STOP */
> +    #define VIDEO_CMD_STOP_TO_BLACK	(1 << 0)
> +    #define VIDEO_CMD_STOP_IMMEDIATELY	(1 << 1)
> +
> +    /* Play input formats: */
> +    /* The decoder has no special format requirements */
> +    #define VIDEO_PLAY_FMT_NONE         (0)
> +    /* The decoder requires full GOPs */
> +    #define VIDEO_PLAY_FMT_GOP          (1)
> +
> +    /* FIELD_UNKNOWN can be used if the hardware does not know whether
> +    the Vsync is for an odd, even or progressive (i.e. non-interlaced)
> +    field. */
> +    #define VIDEO_VSYNC_FIELD_UNKNOWN		(0)
> +    #define VIDEO_VSYNC_FIELD_ODD		(1)
> +    #define VIDEO_VSYNC_FIELD_EVEN		(2)
> +    #define VIDEO_VSYNC_FIELD_PROGRESSIVE	(3)

Please explain the meaning for each of them. Ok, most are obvious, but
some aren't.

> +
> +
> +
> +video_event
> +-----------
> +
> +The following is the structure of a video event as it is returned by the
> +`VIDEO_GET_EVENT`_ call.
> +
> +
> +.. code-block:: c
> +
> +    struct video_event {
> +	__s32 type;
> +    #define VIDEO_EVENT_SIZE_CHANGED        1
> +    #define VIDEO_EVENT_FRAME_RATE_CHANGED  2
> +    #define VIDEO_EVENT_DECODER_STOPPED     3
> +    #define VIDEO_EVENT_VSYNC               4
> +	long timestamp;                 /* MPEG PTS */
> +	union {
> +	    video_size_t size;
> +	    unsigned int frame_rate;    /* in frames per 1000sec */
> +	    unsigned char vsync_field;  /* unknown/odd/even/progressive */
> +	} u;
> +    };

This one requires more explanation to help implementing userspace
support. for instance, what happens if another event occurs
before userspace reads the first one? Will they be preserved
or the new one will override the last one?

vsync_field is also not well specified.. e. g. what's a random 
value (2, for instance) means?

> +
> +
> +video_status
> +------------
> +
> +The `VIDEO_GET_STATUS`_ call returns the following structure informing
> +about various states of the playback operation.
> +
> +
> +.. code-block:: c
> +
> +    struct video_status {
> +	int                   video_blank;   /* blank video on freeze? */
> +	video_play_state_t    play_state;    /* current state of playback */
> +	video_stream_source_t stream_source; /* current source (demux/memory) */
> +	video_format_t        video_format;  /* current aspect ratio of stream */
> +	video_displayformat_t display_format;/* applied cropping mode */
> +    };

Better to use a table to explain each field, placing the possible values
and what they mean.

> +
> +If video_blank is set

Set to what? a value different than zero?

> video will be blanked out if the channel is
> +changed or if playback is stopped. Otherwise, the last picture will be
> +displayed. play_state indicates if the video is currently frozen,
> +stopped, or being played back. The stream_source corresponds to the
> +selected source for the video stream. It can come either from the
> +demultiplexer or from memory. The video_format indicates the aspect
> +ratio (one of 4:3 or 16:9) of the currently played video stream.
> +Finally, display_format corresponds to the applied cropping mode in
> +case the source video format is not the same as the format of the output
> +device.
> +
> +
> +video_still_picture
> +-------------------
> +
> +An I-frame displayed via the `VIDEO_STILLPICTURE`_ call is passed on
> +within the following structure.
> +
> +
> +.. code-block:: c
> +
> +    /* pointer to and size of a single iframe in memory */
> +    struct video_still_picture {
> +    char *iFrame;        /* pointer to a single iframe in memory */
> +    int32_t size;
> +    };
> +
> +
> +video capabilities
> +------------------
> +
> +A call to `VIDEO_GET_CAPABILITIES`_ returns an unsigned integer with the
> +following bits set according to the hardwares capabilities.
> +
> +
> +.. code-block:: c
> +
> +    /* bit definitions for capabilities: */
> +    /* can the hardware decode MPEG1 and/or MPEG2? */
> +    #define VIDEO_CAP_MPEG1   1
> +    #define VIDEO_CAP_MPEG2   2
> +    /* does the video device accept system and/or program stream?
> +    (you still have to open the video and the audio device
> +    but only send the stream to the video device) */
> +    #define VIDEO_CAP_SYS     4
> +    #define VIDEO_CAP_PROG    8


Please better describe the fields, specially bits 2 and 3
(VIDEO_CAP_SYS and VIDEO_CAP_PROG).

> +
> +
> +Video Function Calls
> +====================
> +
> +
> +VIDEO_STOP
> +----------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	int ioctl(fd, VIDEO_STOP, boolean mode)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals VIDEO_STOP for this command.
> +
> +    -  .. row 3
> +
> +       -  Boolean mode
> +
> +       -  Indicates how the screen shall be handled.
> +
> +    -  .. row 4
> +
> +       -
> +       -  TRUE: Blank screen when stop.
> +
> +    -  .. row 5
> +
> +       -
> +       -  FALSE: Show last decoded frame.
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl is for Digital TV devices only. To control a V4L2 decoder use the
> +V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
> +
> +This ioctl call asks the Video Device to stop playing the current
> +stream. Depending on the input parameter, the screen can be blanked out
> +or displaying the last decoded frame.
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +VIDEO_PLAY
> +----------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	int ioctl(fd, VIDEO_PLAY)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals VIDEO_PLAY for this command.
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl is for Digital TV devices only. To control a V4L2 decoder use the
> +V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
> +
> +This ioctl call asks the Video Device to start playing a video stream
> +from the selected source.
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +VIDEO_FREEZE
> +------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	int ioctl(fd, VIDEO_FREEZE)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals VIDEO_FREEZE for this command.
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl is for Digital TV devices only. To control a V4L2 decoder use the
> +V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
> +
> +This ioctl call suspends the live video stream being played. Decoding
> +and playing are frozen. It is then possible to restart the decoding and
> +playing process of the video stream using the `VIDEO_CONTINUE`_ command.
> +If VIDEO_SOURCE_MEMORY is selected in the ioctl call
> +`VIDEO_SELECT_SOURCE`_, the Digital TV subsystem will not decode any more data
> +until the ioctl call `VIDEO_CONTINUE`_ or `VIDEO_PLAY`_ is performed.

What if VIDEO_SOURCE_DEMUX is selected?

> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +VIDEO_CONTINUE
> +--------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	int ioctl(fd, VIDEO_CONTINUE)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals VIDEO_CONTINUE for this command.
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl is for Digital TV devices only. To control a V4L2 decoder use the
> +V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
> +
> +This ioctl call restarts decoding and playing processes of the video
> +stream which was played before a call to `VIDEO_FREEZE`_ was made.
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +VIDEO_SELECT_SOURCE
> +-------------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	int ioctl(fd, VIDEO_SELECT_SOURCE, video_stream_source_t source)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals VIDEO_SELECT_SOURCE for this command.
> +
> +    -  .. row 3
> +
> +       -  `video_stream_source_t`_ source
> +
> +       -  Indicates which source shall be used for the Video stream.
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl is for Digital TV devices only. This ioctl was also supported by the
> +V4L2 ivtv driver, but that has been replaced by the ivtv-specific
> +``IVTV_IOC_PASSTHROUGH_MODE`` ioctl.
> +
> +This ioctl call informs the video device which source shall be used for
> +the input data. The possible sources are demux or memory. If memory is
> +selected, the data is fed to the video device through the write command
> +using the struct `video_stream_source_t`_.
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +VIDEO_SET_BLANK
> +---------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	int ioctl(fd, VIDEO_SET_BLANK, boolean mode)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals VIDEO_SET_BLANK for this command.
> +
> +    -  .. row 3
> +
> +       -  boolean mode
> +
> +       -  TRUE: Blank screen when stop.
> +
> +    -  .. row 4
> +
> +       -
> +       -  FALSE: Show last decoded frame.
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl call asks the Video Device to blank out the picture.
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +VIDEO_GET_STATUS
> +----------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	int ioctl(fd, int request = VIDEO_GET_STATUS, struct video_status *status)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals VIDEO_GET_STATUS for this command.
> +
> +    -  .. row 3
> +
> +       -  struct `video_status`_ \*status
> +
> +       -  Returns the current status of the Video Device.
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl call asks the Video Device to return the current status of
> +the device.
> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +VIDEO_GET_EVENT
> +---------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	int ioctl(fd, int request = VIDEO_GET_EVENT, struct video_event *ev)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals VIDEO_GET_EVENT for this command.
> +
> +    -  .. row 3
> +
> +       -  struct `video_event`_ \*ev
> +
> +       -  Points to the location where the event, if any, is to be stored.
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl is for DVB devices only. To get events from a V4L2 decoder
> +use the V4L2 :ref:`VIDIOC_DQEVENT` ioctl instead.
> +
> +This ioctl call returns an event of type `video_event`_ if available. If
> +an event is not available, the behavior depends on whether the device is
> +in blocking or non-blocking mode. In the latter case, the call fails
> +immediately with errno set to ``EWOULDBLOCK``. In the former case, the call
> +blocks until an event becomes available. The standard Linux poll()
> +and/or select() system calls can be used with the device file descriptor
> +to watch for new events. For select(), the file descriptor should be
> +included in the exceptfds argument, and for poll(), POLLPRI should be
> +specified as the wake-up condition. Read-only permissions are sufficient
> +for this ioctl call.


Same comments as I did for demux event applies here: what happens if
userspace misses the event?

Btw, this explanation is a lot better than the one at demux. You
should probably place something like that there too... there is
block/nonblock mode for the demux event? Do they behave the same?

> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  ``EWOULDBLOCK``
> +
> +       -  There is no event pending, and the device is in non-blocking mode.
> +
> +    -  .. row 2
> +
> +       -  ``EOVERFLOW``
> +
> +       -  Overflow in event queue - one or more events were lost.
> +
> +
> +VIDEO_SET_DISPLAY_FORMAT
> +------------------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	int ioctl(fd, int request = VIDEO_SET_DISPLAY_FORMAT, video_display_format_t format)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals VIDEO_SET_DISPLAY_FORMAT for this command.
> +
> +    -  .. row 3
> +
> +       -  `video_displayformat_t`_ format
> +
> +       -  Selects the video format to be used.
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl call asks the Video Device to select the video format to be
> +applied by the MPEG chip on the video.
> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +VIDEO_STILLPICTURE
> +------------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	int ioctl(fd, int request = VIDEO_STILLPICTURE, struct video_still_picture *sp)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals VIDEO_STILLPICTURE for this command.
> +
> +    -  .. row 3
> +
> +       -  struct `video_still_picture`_ \*sp
> +
> +       -  Pointer to a location where an I-frame and size is stored.

Please describe it better. In particular, how the data is stored?

- video format(s);
- video codec (if the frame is not in raw format);
- colorspace;
- size;
- resolution;
- etc.

Is it a MJPEG/JPEG frame with all headers stored in a way it can be used by
a normal mjpeg-capable image viewer? Are there just one possible encoding?

On other words, the spec should let it clear about how userspace can
use this information to produce an image that can be displayed.

You may need to mention the need to call some other ioctls to get more
details about the image, if needed.

> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl call asks the Video Device to display a still picture
> +(I-frame). The input data shall contain an I-frame. If the pointer is
> +NULL, then the current displayed still picture is blanked.
> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +VIDEO_FAST_FORWARD
> +------------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	int ioctl(fd, int request = VIDEO_FAST_FORWARD, int nFrames)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals VIDEO_FAST_FORWARD for this command.
> +
> +    -  .. row 3
> +
> +       -  int nFrames
> +
> +       -  The number of frames to skip.
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl call asks the Video Device to skip decoding of N number of
> +I-frames. This call can only be used if VIDEO_SOURCE_MEMORY is
> +selected.
> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  ``EPERM``
> +
> +       -  Mode VIDEO_SOURCE_MEMORY not selected.
> +
> +
> +VIDEO_SLOWMOTION
> +----------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	int ioctl(fd, int request = VIDEO_SLOWMOTION, int nFrames)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals VIDEO_SLOWMOTION for this command.
> +
> +    -  .. row 3
> +
> +       -  int nFrames
> +
> +       -  The number of times to repeat each frame.
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl call asks the video device to repeat decoding frames N number
> +of times. This call can only be used if VIDEO_SOURCE_MEMORY is
> +selected.
> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  ``EPERM``
> +
> +       -  Mode VIDEO_SOURCE_MEMORY not selected.
> +
> +
> +VIDEO_GET_CAPABILITIES
> +----------------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	int ioctl(fd, int request = VIDEO_GET_CAPABILITIES, unsigned int *cap)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals VIDEO_GET_CAPABILITIES for this command.
> +
> +    -  .. row 3
> +
> +       -  unsigned int \*cap
> +
> +       -  Pointer to a location where to store the capability information.
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl call asks the video device about its decoding capabilities.
> +On success it returns and integer which has bits set according to the
> +defines in section ??.
> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +VIDEO_CLEAR_BUFFER
> +------------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	int ioctl(fd, int request = VIDEO_CLEAR_BUFFER)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals VIDEO_CLEAR_BUFFER for this command.
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl call clears all video buffers in the driver and in the
> +decoder hardware.
> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +VIDEO_SET_STREAMTYPE
> +--------------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	int ioctl(fd, int request = VIDEO_SET_STREAMTYPE, int type)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals VIDEO_SET_STREAMTYPE for this command.
> +
> +    -  .. row 3
> +
> +       -  int type
> +
> +       -  stream type

What are the valid types?

> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl tells the driver which kind of stream to expect being written
> +to it. If this call is not used the default of video PES is used. Some
> +drivers might not support this call and always expect PES.
> +Intelligent decoder might also not support or ignore this call and
> +determine the streamtype themselves.
> +
> +.. note:: See: :ref:`DVB Data Formats <legacy_dvb_decoder_formats>`
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +VIDEO_SET_FORMAT
> +----------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	int ioctl(fd, int request = VIDEO_SET_FORMAT, video_format_t format)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals VIDEO_SET_FORMAT for this command.
> +
> +    -  .. row 3
> +
> +       -  `video_format_t`_ format
> +
> +       -  video format of TV as defined in section ??.
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl sets the screen format (aspect ratio) of the connected output
> +device (TV) so that the output of the decoder can be adjusted
> +accordingly.
> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +VIDEO_GET_SIZE
> +--------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	int ioctl(int fd, int request = VIDEO_GET_SIZE, video_size_t *size)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals VIDEO_GET_SIZE for this command.
> +
> +    -  .. row 3
> +
> +       -  `video_size_t`_ \*size
> +
> +       -  Returns the size and aspect ratio.
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl returns the size and aspect ratio.
> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +VIDEO_GET_PTS
> +-------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	int ioctl(int fd, int request = VIDEO_GET_PTS, __u64 *pts)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals VIDEO_GET_PTS for this command.
> +
> +    -  .. row 3
> +
> +       -  __u64 \*pts
> +
> +       -  Returns the 33-bit timestamp as defined in ITU T-REC-H.222.0 /
> +	  ISO/IEC 13818-1.
> +
> +	  The PTS should belong to the currently played frame if possible,
> +	  but may also be a value close to it like the PTS of the last
> +	  decoded frame or the last PTS extracted by the PES parser.
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +For V4L2 decoders this ioctl has been replaced by the
> +``V4L2_CID_MPEG_VIDEO_DEC_PTS`` control.
> +
> +This ioctl call asks the Video Device to return the current PTS
> +timestamp.
> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +VIDEO_GET_FRAME_RATE
> +--------------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	int ioctl(int fd, int request = VIDEO_GET_FRAME_RATE, unsigned int *rate)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals VIDEO_GET_FRAME_RATE for this command.
> +
> +    -  .. row 3
> +
> +       -  unsigned int \*rate
> +
> +       -  Returns the framerate in number of frames per 1000 seconds.
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +This ioctl call asks the Video Device to return the current framerate.
> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +VIDEO_COMMAND
> +-------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	int ioctl(int fd, int request = VIDEO_COMMAND, struct video_command *cmd)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals VIDEO_COMMAND for this command.
> +
> +    -  .. row 3
> +
> +       -  `struct video_command`_ \*cmd
> +
> +       -  Commands the decoder.
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +For V4L2 decoders this ioctl has been replaced by the
> +:ref:`VIDIOC_DECODER_CMD` ioctl.
> +
> +This ioctl commands the decoder. The `struct video_command`_ is a
> +subset of the ``v4l2_decoder_cmd`` struct, so refer to the
> +:ref:`VIDIOC_DECODER_CMD` documentation for
> +more information.
> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +VIDEO_TRY_COMMAND
> +-----------------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	int ioctl(int fd, int request = VIDEO_TRY_COMMAND, struct video_command *cmd)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  int request
> +
> +       -  Equals VIDEO_TRY_COMMAND for this command.
> +
> +    -  .. row 3
> +
> +       -  `struct video_command`_ \*cmd
> +
> +       -  Try a decoder command.
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +.. attention:: Do **not** use in new drivers!
> +             See: :ref:`legacy_dvb_decoder_notes`
> +
> +For V4L2 decoders this ioctl has been replaced by the
> +:ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` ioctl.
> +
> +This ioctl tries a decoder command. The `struct video_command`_ is a
> +subset of the ``v4l2_decoder_cmd`` struct, so refer to the
> +:ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` documentation
> +for more information.
> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +On success 0 is returned, on error -1 and the ``errno`` variable is set
> +appropriately. The generic error codes are described at the
> +:ref:`Generic Error Codes <gen-errors>` chapter.
> +
> +
> +open()
> +------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	int open(const char *deviceName, int flags)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  const char \*deviceName
> +
> +       -  Name of specific video device.
> +
> +    -  .. row 2
> +
> +       -  int flags
> +
> +       -  A bit-wise OR of the following flags:
> +
> +    -  .. row 3
> +
> +       -
> +       -  O_RDONLY read-only access
> +
> +    -  .. row 4
> +
> +       -
> +       -  O_RDWR read/write access
> +
> +    -  .. row 5
> +
> +       -
> +       -  O_NONBLOCK open in non-blocking mode
> +
> +    -  .. row 6
> +
> +       -
> +       -  (blocking mode is the default)
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +This system call opens a named video device (e.g.
> +/dev/dvb/adapter?/video?) for subsequent use.
> +
> +When an open() call has succeeded, the device will be ready for use. The
> +significance of blocking or non-blocking mode is described in the
> +documentation for functions where there is a difference. It does not
> +affect the semantics of the open() call itself. A device opened in
> +blocking mode can later be put into non-blocking mode (and vice versa)
> +using the F_SETFL command of the fcntl system call. This is a standard
> +system call, documented in the Linux manual page for fcntl. Only one
> +user can open the Video Device in O_RDWR mode. All other attempts to
> +open the device in this mode will fail, and an error-code will be
> +returned. If the Video Device is opened in O_RDONLY mode, the only
> +ioctl call that can be used is `VIDEO_GET_STATUS`_. All other call will
> +return an error code.
> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  ``ENODEV``
> +
> +       -  Device driver not loaded/available.
> +
> +    -  .. row 2
> +
> +       -  ``EINTERNAL``
> +
> +       -  Internal error.
> +
> +    -  .. row 3
> +
> +       -  ``EBUSY``
> +
> +       -  Device or resource busy.
> +
> +    -  .. row 4
> +
> +       -  ``EINVAL``
> +
> +       -  Invalid argument.
> +
> +
> +close()
> +-------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	int close(int fd)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +This system call closes a previously opened video device.
> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  ``EBADF``
> +
> +       -  fd is not a valid open file descriptor.
> +
> +
> +write()
> +-------
> +
> +Synopsis
> +~~~~~~~~
> +
> +.. code-block:: c
> +
> +	size_t write(int fd, const void *buf, size_t count)
> +
> +
> +Arguments
> +~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  int fd
> +
> +       -  File descriptor returned by a previous call to `open()`_.
> +
> +    -  .. row 2
> +
> +       -  void \*buf
> +
> +       -  Pointer to the buffer containing the PES data.
> +
> +    -  .. row 3
> +
> +       -  size_t count
> +
> +       -  Size of buf.
> +
> +
> +Description
> +~~~~~~~~~~~
> +
> +This system call can only be used if VIDEO_SOURCE_MEMORY is selected
> +in the ioctl call `VIDEO_SELECT_SOURCE`_. The data provided shall be in
> +PES format, unless the capability allows other formats. TS is the
> +most common format for storing DVB-data, it is usually supported too.
> +If O_NONBLOCK is not specified the function will block until buffer space
> +is available. The amount of data to be transferred is implied by count.
> +
> +.. note:: See: :ref:`DVB Data Formats <legacy_dvb_decoder_formats>`
> +
> +
> +Return Value
> +~~~~~~~~~~~~
> +
> +.. flat-table::
> +    :header-rows:  0
> +    :stub-columns: 0
> +
> +
> +    -  .. row 1
> +
> +       -  ``EPERM``
> +
> +       -  Mode VIDEO_SOURCE_MEMORY not selected.
> +
> +    -  .. row 2
> +
> +       -  ``ENOMEM``
> +
> +       -  Attempted to write more data than the internal buffer can hold.
> +
> +    -  .. row 3
> +
> +       -  ``EBADF``
> +
> +       -  fd is not a valid open file descriptor.

Re: [PATCH v2] Legacy DVB API: completion of documentation

[Stefan Herdler]

Hi Mauro,

I just want to say thank you, for your very detailed review. It helps me a lot.
Now I know for sure which kind details have been missed.
Reading and writing such a documentation is definitely a different thing.

On 27/03/23 20:28, Mauro Carvalho Chehab wrote:
[...]
>
>>> At least everything in the header-files is in the documentation now. I hope, I have done it sufficiently.
>
> Good! It took me quite a while to read everything... At the end, as was
> a little tired, so I probably missed things.
>
> Next time, please split this on a patch series, in order to make
> easier for the poor reviewers to look into it ;-)

I have to apologies. I just realized, that it got that long,
while reading your answer.
I should have tried to scroll down to the end, before sending ;-).


[...]

>
>>> I haven't found any useful hint how to get rid of them.
>>> Should I switch to "code-block:: c" instead?
>>> But there are a lot of this warnings from other files too. It seems I'm mot the only one with this problem.
>> I switched to "code-block".
>> Now there are no warnings anymore.
>
> For things like ioctl, code-blocks are preferred. For other things,
> better to keep the warnings and not use code-block where not needed. The
> warnings are part of the Sphinx cross-reference system, which tries to
> create references to the C domain functions and data types.
>
> Unfortunately, Sphinx has a known bug that it is hit when the same symbol
> name is used with different meanings e.g., on C declarations like those:
>
> 	struct foo;
> 	enum foo;
> 	typedef foo;
> 	foo() {}
>
> Each one has a different type. So, `foo` cross-references depend on
> the context. Right now, Sphinx will just consider them to be attempts
> to re-define an existing name. There's already patches fixing it
> Sphinx upstream, but (last time I checked) not applied yet as those
> would cause regressions on intersphinx.
>
>> This functions shouldn't be referenced from outside this document anyway.
>
> No, we link the header files with the documentation, exactly to
> generate cross-references and detect gaps at the docsO.k., I thought this applies only to the inline-documentation generated from
source-code.
But it makes sense now.

Thanks to your tips I was able to find the solution for this problem in
minutes.
One of the versions I tried was already almost right. But I haven't seen it.



I already noticed, that not everything of the API is in use by the AV7110
driver, but I forgot it in the remarks.
I will provide a list next time.

I had searched for the declarations from the header-files in the projects
including them.
Almost everything was found in the AV7110 driver, only 2 or 3 items were
missing. And this rest seems to be used elsewhere.
My first target was to make the documentation consistent to the headers.
So I kept them, at least for now.



I'll mail again when I'm finished, but it may take a while.

Regards
Stefan

Re: saa7146: please test the vb2 conversion!

[Stefan Herdler]

Hi Hans,

I'm sorry for my late replay, but it was quiet troublesome to build
a kernel with the patch, also running on the rest of my hardware.


On 24/03/23 22:21, Stefan Herdler wrote:
> Hi Hans,
>
> great to read, that it is finally done, thank you for your work!
>
>
> On 24/03/23 11:40 Hans Verkuil wrote:
>> On 24/03/2023 11:37, Hans Verkuil wrote:
>>> Hi all,
>>>
>>> I finished the vb2 conversion and tested what I could test. I am missing
>>> 'full featured' hardware, so I could not test the analog video capture part
> There is some miss understanding.
> At VDR 'full featured' refers to all DVB-cards with decoder and OSD.
>
> I wasn't aware, that this definition doesn't seem to be common, sorry.
>>> of that. It's not clear to me if VBI capture is also supported on those
>>> cards, if so, then that needs to be tested as well.

I have talked to the "cable-guys" and they didn't know about VBI capture.

The whole analog capture of this cards was never very popular with VDR.
The signal had to be encoded on the fly, this was never reliable as the
PVR-cards with encoder.

I think it is o.k. to leave it untested.
>>>
>>> Note that there is one userspace-facing change: the VBI output settings
>>> are kept, even if the vbi device is closed by the application.
>>>
>>> Before you had to open the vbi device, format the slice VBI output, and
>>> write sliced VBI data to it. Closing the device would reset how VBI output
>>> behaves. That is not in spec with the V4L2 API. The format is kept after
>>> the device is closed.
>>>
>>> Any application that uses VBI output and that wants to keep the same
>>> behavior would have to call VIDIOC_S_FMT with a struct v4l2_sliced_vbi_format
>>> with a service_set field set to 0 to indicate that you don't want to
>>> output any VBI anymore.

VBI output is used to switch the aspect-ratio via WSS.
this should be supported by any av7110 card.

The software is run a daemon or plugin, so the userspace-facing change
shouldn't matter.

I'll test this as soon as possible.




I've done only basic testing so far, but unfortunately it already failed.

The test:
Switch to a channel[*] and view the decoded video with tvtime.

The resulting picture is corrupted.
Almost green with some pink traces at the outlines.

It reminds me to YCbCr component-yideo on a RGB-input.
Maybe the input-format of saa7146 not set correctly?

The OSD is equally affected, but the card seems to run stable.



* I used VDR for this, but it shouldn't matter.

Regards
Stefan

>>>
>>> If this is a problem, then I can make a module option that selects the old
>>> behavior.
>>>
>>> BTW, if anyone has a spare full-featured card (i.e. with analog video capture
>>> as well), then I would love to take it off your hands so that I can test that
>>> myself!
> There are only DVB-C boards with analog features.
>
> I personally never had cable-TV nor own any DVB-C cards.
> But I try to find such a card with an analog module on it.
>>>
>>> This series has been tested on the two Hexium boards, the mxb board, and two
>>> av7710 boards (DVB-C and DVB-T).
>
> I can test on the DVB-S hardware.
>
> But let me finish the API-documentation fist, it is almost done.
> There are only the complains from chackpatch left to fix, I hope it is done quickly.
>
>
> Regards
> Stefan
>
>
>>
>> It does help if I point to the patches :-)
>>
>> The patch series is here:
>>
>> https://patchwork.linuxtv.org/project/linux-media/list/?series=10140
>>
>> It's also in my git tree:
>>
>> https://git.linuxtv.org/hverkuil/media_tree.git/log/?h=saa7146-clean
>>
>> Regards,
>>
>> 	Hans

Re: saa7146: please test the vb2 conversion!

[Hans Verkuil]

On 07/04/2023 00:43, Stefan Herdler wrote:
> Hi Hans,
> 
> I'm sorry for my late replay, but it was quiet troublesome to build
> a kernel with the patch, also running on the rest of my hardware.
> 
> 
> On 24/03/23 22:21, Stefan Herdler wrote:
>> Hi Hans,
>>
>> great to read, that it is finally done, thank you for your work!
>>
>>
>> On 24/03/23 11:40 Hans Verkuil wrote:
>>> On 24/03/2023 11:37, Hans Verkuil wrote:
>>>> Hi all,
>>>>
>>>> I finished the vb2 conversion and tested what I could test. I am missing
>>>> 'full featured' hardware, so I could not test the analog video capture part
>> There is some miss understanding.
>> At VDR 'full featured' refers to all DVB-cards with decoder and OSD.
>>
>> I wasn't aware, that this definition doesn't seem to be common, sorry.
>>>> of that. It's not clear to me if VBI capture is also supported on those
>>>> cards, if so, then that needs to be tested as well.
> 
> I have talked to the "cable-guys" and they didn't know about VBI capture.
> 
> The whole analog capture of this cards was never very popular with VDR.
> The signal had to be encoded on the fly, this was never reliable as the
> PVR-cards with encoder.
> 
> I think it is o.k. to leave it untested.
>>>>
>>>> Note that there is one userspace-facing change: the VBI output settings
>>>> are kept, even if the vbi device is closed by the application.
>>>>
>>>> Before you had to open the vbi device, format the slice VBI output, and
>>>> write sliced VBI data to it. Closing the device would reset how VBI output
>>>> behaves. That is not in spec with the V4L2 API. The format is kept after
>>>> the device is closed.
>>>>
>>>> Any application that uses VBI output and that wants to keep the same
>>>> behavior would have to call VIDIOC_S_FMT with a struct v4l2_sliced_vbi_format
>>>> with a service_set field set to 0 to indicate that you don't want to
>>>> output any VBI anymore.
> 
> VBI output is used to switch the aspect-ratio via WSS.
> this should be supported by any av7110 card.
> 
> The software is run a daemon or plugin, so the userspace-facing change
> shouldn't matter.
> 
> I'll test this as soon as possible.
> 
> 
> 
> 
> I've done only basic testing so far, but unfortunately it already failed.
> 
> The test:
> Switch to a channel[*] and view the decoded video with tvtime.
> 
> The resulting picture is corrupted.
> Almost green with some pink traces at the outlines.
> 
> It reminds me to YCbCr component-yideo on a RGB-input.
> Maybe the input-format of saa7146 not set correctly?
> 
> The OSD is equally affected, but the card seems to run stable.

That's weird. When you are in this state, can you run
'v4l2-ctl -V -d /dev/videoX' for the video device that tvtime
is using? I'll try to test it with tvtime as well next week.
I have done my tests using qvidcap and qv4l2, and that looked fine.

Regards,

	Hans

> 
> 
> 
> * I used VDR for this, but it shouldn't matter.
> 
> Regards
> Stefan
> 
>>>>
>>>> If this is a problem, then I can make a module option that selects the old
>>>> behavior.
>>>>
>>>> BTW, if anyone has a spare full-featured card (i.e. with analog video capture
>>>> as well), then I would love to take it off your hands so that I can test that
>>>> myself!
>> There are only DVB-C boards with analog features.
>>
>> I personally never had cable-TV nor own any DVB-C cards.
>> But I try to find such a card with an analog module on it.
>>>>
>>>> This series has been tested on the two Hexium boards, the mxb board, and two
>>>> av7710 boards (DVB-C and DVB-T).
>>
>> I can test on the DVB-S hardware.
>>
>> But let me finish the API-documentation fist, it is almost done.
>> There are only the complains from chackpatch left to fix, I hope it is done quickly.
>>
>>
>> Regards
>> Stefan
>>
>>
>>>
>>> It does help if I point to the patches :-)
>>>
>>> The patch series is here:
>>>
>>> https://patchwork.linuxtv.org/project/linux-media/list/?series=10140
>>>
>>> It's also in my git tree:
>>>
>>> https://git.linuxtv.org/hverkuil/media_tree.git/log/?h=saa7146-clean
>>>
>>> Regards,
>>>
>>> 	Hans

Re: saa7146: please test the vb2 conversion!

[Stefan Herdler]

On 07/04/23 09:04, Hans Verkuil wrote:
> On 07/04/2023 00:43, Stefan Herdler wrote:
[...]
>>
>> VBI output is used to switch the aspect-ratio via WSS.
>> this should be supported by any av7110 card.
>>
>> The software is run a daemon or plugin, so the userspace-facing change
>> shouldn't matter.
>>
>> I'll test this as soon as possible.
>>
>>
>>
>>
>> I've done only basic testing so far, but unfortunately it already failed.
>>
>> The test:
>> Switch to a channel[*] and view the decoded video with tvtime.
>>
>> The resulting picture is corrupted.
>> Almost green with some pink traces at the outlines.
>>
>> It reminds me to YCbCr component-yideo on a RGB-input.
>> Maybe the input-format of saa7146 not set correctly?
>>
>> The OSD is equally affected, but the card seems to run stable.
>
> That's weird. When you are in this state, can you run
> 'v4l2-ctl -V -d /dev/videoX' for the video device that tvtime
> is using? I'll try to test it with tvtime as well next week.
> I have done my tests using qvidcap and qv4l2, and that looked fine.

I've done some more testing and the result is somehow confusing to me.

At first I tried qv4l and it shows correct videos with any driver.
And with any pixel format setting I tried.


After boot /dev/video0 (there is only this device) starts always with
this settings:
Format Video Capture:
        Width/Height      : 384/288
        Pixel Format      : 'BGR3' (24-bit BGR 8-8-8)
        Field             : Interlaced
        Bytes per Line    : 1152
        Size Image        : 331776
        Colorspace        : SMPTE 170M
        Transfer Function : Default (maps to Rec. 709)
        YCbCr/HSV Encoding: Default (maps to ITU-R 601)
        Quantization      : Default (maps to Full Range)
        Flags             :


On the working "old" driver tvtime switches to the following settings:
Format Video Capture:
        Width/Height      : 720/576
        Pixel Format      : 'UYVY' (UYVY 4:2:2)
        Field             : Interlaced
        Bytes per Line    : 1440
        Size Image        : 829440
        Colorspace        : SMPTE 170M
        Transfer Function : Default (maps to Rec. 709)
        YCbCr/HSV Encoding: Default (maps to ITU-R 601)
        Quantization      : Default (maps to Limited Range)
        Flags             :
It seems tvtime needs this 'UYVY' pixel format to work.


On the "new" driver, with patches [1], tvtime switches to:
Format Video Capture:
        Width/Height      : 720/576
        Pixel Format      : 'BGR3' (24-bit BGR 8-8-8)
        Field             : Interlaced
        Bytes per Line    : 2160
        Size Image        : 1244160
        Colorspace        : SMPTE 170M
        Transfer Function : Default (maps to Rec. 709)
        YCbCr/HSV Encoding: Default (maps to ITU-R 601)
        Quantization      : Default (maps to Full Range)
        Flags             :
And now it is getting weird:
I can switch to the correct 'UYVY' settings using qv4l.
But tvtime always switches back to 'BGR3'.

Using qv4l while tvtime is running doesn't work and sometimes
causes freezing of both programs (on all drivers).


I have also build a new driver just without the patches [2].
It shows the "old" correct behavior.
So I think, the cause of the change must be somewhere in the
patches.



Btw.:
I also tried to open the video device with the usual
media-players, but I had no luck so far (with any driver).


Regards

Stefan


[1] git checkout -B saa7146-clean 837736a79a76c9becddf0caf905b27c144a64030
[2] git checkout -B saa7146-clean 2653fad0d8a9625667e9a78133ea9e1245b7c40c

>
> Regards,
>
> 	Hans
>
[...]

Re: saa7146: please test the vb2 conversion!

[Hans Verkuil]

On 10/04/2023 00:36, Stefan Herdler wrote:
> On 07/04/23 09:04, Hans Verkuil wrote:
>> On 07/04/2023 00:43, Stefan Herdler wrote:
> [...]
>>>
>>> VBI output is used to switch the aspect-ratio via WSS.
>>> this should be supported by any av7110 card.
>>>
>>> The software is run a daemon or plugin, so the userspace-facing change
>>> shouldn't matter.
>>>
>>> I'll test this as soon as possible.
>>>
>>>
>>>
>>>
>>> I've done only basic testing so far, but unfortunately it already failed.
>>>
>>> The test:
>>> Switch to a channel[*] and view the decoded video with tvtime.
>>>
>>> The resulting picture is corrupted.
>>> Almost green with some pink traces at the outlines.
>>>
>>> It reminds me to YCbCr component-yideo on a RGB-input.
>>> Maybe the input-format of saa7146 not set correctly?
>>>
>>> The OSD is equally affected, but the card seems to run stable.
>>
>> That's weird. When you are in this state, can you run
>> 'v4l2-ctl -V -d /dev/videoX' for the video device that tvtime
>> is using? I'll try to test it with tvtime as well next week.
>> I have done my tests using qvidcap and qv4l2, and that looked fine.
> 
> I've done some more testing and the result is somehow confusing to me.
> 
> At first I tried qv4l and it shows correct videos with any driver.
> And with any pixel format setting I tried.
> 
> 
> After boot /dev/video0 (there is only this device) starts always with
> this settings:
> Format Video Capture:
>         Width/Height      : 384/288
>         Pixel Format      : 'BGR3' (24-bit BGR 8-8-8)
>         Field             : Interlaced
>         Bytes per Line    : 1152
>         Size Image        : 331776
>         Colorspace        : SMPTE 170M
>         Transfer Function : Default (maps to Rec. 709)
>         YCbCr/HSV Encoding: Default (maps to ITU-R 601)
>         Quantization      : Default (maps to Full Range)
>         Flags             :
> 
> 
> On the working "old" driver tvtime switches to the following settings:
> Format Video Capture:
>         Width/Height      : 720/576
>         Pixel Format      : 'UYVY' (UYVY 4:2:2)
>         Field             : Interlaced
>         Bytes per Line    : 1440
>         Size Image        : 829440
>         Colorspace        : SMPTE 170M
>         Transfer Function : Default (maps to Rec. 709)
>         YCbCr/HSV Encoding: Default (maps to ITU-R 601)
>         Quantization      : Default (maps to Limited Range)
>         Flags             :
> It seems tvtime needs this 'UYVY' pixel format to work.
> 
> 
> On the "new" driver, with patches [1], tvtime switches to:
> Format Video Capture:
>         Width/Height      : 720/576
>         Pixel Format      : 'BGR3' (24-bit BGR 8-8-8)
>         Field             : Interlaced
>         Bytes per Line    : 2160
>         Size Image        : 1244160
>         Colorspace        : SMPTE 170M
>         Transfer Function : Default (maps to Rec. 709)
>         YCbCr/HSV Encoding: Default (maps to ITU-R 601)
>         Quantization      : Default (maps to Full Range)
>         Flags             :
> And now it is getting weird:
> I can switch to the correct 'UYVY' settings using qv4l.
> But tvtime always switches back to 'BGR3'.
> 
> Using qv4l while tvtime is running doesn't work and sometimes
> causes freezing of both programs (on all drivers).
> 
> 
> I have also build a new driver just without the patches [2].
> It shows the "old" correct behavior.
> So I think, the cause of the change must be somewhere in the
> patches.

That's useful information, thank you!

I'll do some testing this week.

Regards,

	Hans

> 
> 
> 
> Btw.:
> I also tried to open the video device with the usual
> media-players, but I had no luck so far (with any driver).
> 
> 
> Regards
> 
> Stefan
> 
> 
> [1] git checkout -B saa7146-clean 837736a79a76c9becddf0caf905b27c144a64030
> [2] git checkout -B saa7146-clean 2653fad0d8a9625667e9a78133ea9e1245b7c40c
> 
>>
>> Regards,
>>
>> 	Hans
>>
> [...]

Re: saa7146: please test the vb2 conversion!

[Hans Verkuil]

On 10/04/2023 00:36, Stefan Herdler wrote:
> On 07/04/23 09:04, Hans Verkuil wrote:
>> On 07/04/2023 00:43, Stefan Herdler wrote:
> [...]
>>>
>>> VBI output is used to switch the aspect-ratio via WSS.
>>> this should be supported by any av7110 card.
>>>
>>> The software is run a daemon or plugin, so the userspace-facing change
>>> shouldn't matter.
>>>
>>> I'll test this as soon as possible.
>>>
>>>
>>>
>>>
>>> I've done only basic testing so far, but unfortunately it already failed.
>>>
>>> The test:
>>> Switch to a channel[*] and view the decoded video with tvtime.
>>>
>>> The resulting picture is corrupted.
>>> Almost green with some pink traces at the outlines.
>>>
>>> It reminds me to YCbCr component-yideo on a RGB-input.
>>> Maybe the input-format of saa7146 not set correctly?
>>>
>>> The OSD is equally affected, but the card seems to run stable.
>>
>> That's weird. When you are in this state, can you run
>> 'v4l2-ctl -V -d /dev/videoX' for the video device that tvtime
>> is using? I'll try to test it with tvtime as well next week.
>> I have done my tests using qvidcap and qv4l2, and that looked fine.
> 
> I've done some more testing and the result is somehow confusing to me.
> 
> At first I tried qv4l and it shows correct videos with any driver.
> And with any pixel format setting I tried.
> 
> 
> After boot /dev/video0 (there is only this device) starts always with
> this settings:
> Format Video Capture:
>         Width/Height      : 384/288
>         Pixel Format      : 'BGR3' (24-bit BGR 8-8-8)
>         Field             : Interlaced
>         Bytes per Line    : 1152
>         Size Image        : 331776
>         Colorspace        : SMPTE 170M
>         Transfer Function : Default (maps to Rec. 709)
>         YCbCr/HSV Encoding: Default (maps to ITU-R 601)
>         Quantization      : Default (maps to Full Range)
>         Flags             :
> 
> 
> On the working "old" driver tvtime switches to the following settings:
> Format Video Capture:
>         Width/Height      : 720/576
>         Pixel Format      : 'UYVY' (UYVY 4:2:2)
>         Field             : Interlaced
>         Bytes per Line    : 1440
>         Size Image        : 829440
>         Colorspace        : SMPTE 170M
>         Transfer Function : Default (maps to Rec. 709)
>         YCbCr/HSV Encoding: Default (maps to ITU-R 601)
>         Quantization      : Default (maps to Limited Range)
>         Flags             :
> It seems tvtime needs this 'UYVY' pixel format to work.
> 
> 
> On the "new" driver, with patches [1], tvtime switches to:
> Format Video Capture:
>         Width/Height      : 720/576
>         Pixel Format      : 'BGR3' (24-bit BGR 8-8-8)
>         Field             : Interlaced
>         Bytes per Line    : 2160
>         Size Image        : 1244160
>         Colorspace        : SMPTE 170M
>         Transfer Function : Default (maps to Rec. 709)
>         YCbCr/HSV Encoding: Default (maps to ITU-R 601)
>         Quantization      : Default (maps to Full Range)
>         Flags             :
> And now it is getting weird:
> I can switch to the correct 'UYVY' settings using qv4l.
> But tvtime always switches back to 'BGR3'.

The cause is "[PATCH 10/17] media: common: saa7146: fall back to V4L2_PIX_FMT_BGR24".

Can you drop that patch and test again?

It's really a tvtime bug since drivers are allowed to either reject an unsupported
pixelformat (the old behavior) or replace it with a supported pixelformat (the
new behavior). And tvtime only supports the old behavior.

> 
> Using qv4l while tvtime is running doesn't work and sometimes
> causes freezing of both programs (on all drivers).

Are you just starting qv4l2 when tvtime is running? Or trying to stream?
Do you see messages in the kernel log?

I couldn't reproduce this. Since tvtime is streaming, qv4l2 shouldn't be able to
do anything since all attempts to change something should result in EBUSY.

Regards,

	Hans

> 
> 
> I have also build a new driver just without the patches [2].
> It shows the "old" correct behavior.
> So I think, the cause of the change must be somewhere in the
> patches.
> 
> 
> 
> Btw.:
> I also tried to open the video device with the usual
> media-players, but I had no luck so far (with any driver).
> 
> 
> Regards
> 
> Stefan
> 
> 
> [1] git checkout -B saa7146-clean 837736a79a76c9becddf0caf905b27c144a64030
> [2] git checkout -B saa7146-clean 2653fad0d8a9625667e9a78133ea9e1245b7c40c
> 
>>
>> Regards,
>>
>> 	Hans
>>
> [...]

Re: saa7146: please test the vb2 conversion!

[Hans Verkuil]

On 12/04/2023 12:11, Hans Verkuil wrote:
> On 10/04/2023 00:36, Stefan Herdler wrote:
>> On 07/04/23 09:04, Hans Verkuil wrote:
>>> On 07/04/2023 00:43, Stefan Herdler wrote:
>> [...]
>>>>
>>>> VBI output is used to switch the aspect-ratio via WSS.
>>>> this should be supported by any av7110 card.
>>>>
>>>> The software is run a daemon or plugin, so the userspace-facing change
>>>> shouldn't matter.
>>>>
>>>> I'll test this as soon as possible.
>>>>
>>>>
>>>>
>>>>
>>>> I've done only basic testing so far, but unfortunately it already failed.
>>>>
>>>> The test:
>>>> Switch to a channel[*] and view the decoded video with tvtime.
>>>>
>>>> The resulting picture is corrupted.
>>>> Almost green with some pink traces at the outlines.
>>>>
>>>> It reminds me to YCbCr component-yideo on a RGB-input.
>>>> Maybe the input-format of saa7146 not set correctly?
>>>>
>>>> The OSD is equally affected, but the card seems to run stable.
>>>
>>> That's weird. When you are in this state, can you run
>>> 'v4l2-ctl -V -d /dev/videoX' for the video device that tvtime
>>> is using? I'll try to test it with tvtime as well next week.
>>> I have done my tests using qvidcap and qv4l2, and that looked fine.
>>
>> I've done some more testing and the result is somehow confusing to me.
>>
>> At first I tried qv4l and it shows correct videos with any driver.
>> And with any pixel format setting I tried.
>>
>>
>> After boot /dev/video0 (there is only this device) starts always with
>> this settings:
>> Format Video Capture:
>>         Width/Height      : 384/288
>>         Pixel Format      : 'BGR3' (24-bit BGR 8-8-8)
>>         Field             : Interlaced
>>         Bytes per Line    : 1152
>>         Size Image        : 331776
>>         Colorspace        : SMPTE 170M
>>         Transfer Function : Default (maps to Rec. 709)
>>         YCbCr/HSV Encoding: Default (maps to ITU-R 601)
>>         Quantization      : Default (maps to Full Range)
>>         Flags             :
>>
>>
>> On the working "old" driver tvtime switches to the following settings:
>> Format Video Capture:
>>         Width/Height      : 720/576
>>         Pixel Format      : 'UYVY' (UYVY 4:2:2)
>>         Field             : Interlaced
>>         Bytes per Line    : 1440
>>         Size Image        : 829440
>>         Colorspace        : SMPTE 170M
>>         Transfer Function : Default (maps to Rec. 709)
>>         YCbCr/HSV Encoding: Default (maps to ITU-R 601)
>>         Quantization      : Default (maps to Limited Range)
>>         Flags             :
>> It seems tvtime needs this 'UYVY' pixel format to work.
>>
>>
>> On the "new" driver, with patches [1], tvtime switches to:
>> Format Video Capture:
>>         Width/Height      : 720/576
>>         Pixel Format      : 'BGR3' (24-bit BGR 8-8-8)
>>         Field             : Interlaced
>>         Bytes per Line    : 2160
>>         Size Image        : 1244160
>>         Colorspace        : SMPTE 170M
>>         Transfer Function : Default (maps to Rec. 709)
>>         YCbCr/HSV Encoding: Default (maps to ITU-R 601)
>>         Quantization      : Default (maps to Full Range)
>>         Flags             :
>> And now it is getting weird:
>> I can switch to the correct 'UYVY' settings using qv4l.
>> But tvtime always switches back to 'BGR3'.
> 
> The cause is "[PATCH 10/17] media: common: saa7146: fall back to V4L2_PIX_FMT_BGR24".
> 
> Can you drop that patch and test again?
> 
> It's really a tvtime bug since drivers are allowed to either reject an unsupported
> pixelformat (the old behavior) or replace it with a supported pixelformat (the
> new behavior). And tvtime only supports the old behavior.

FYI: I posted a patch fixing tvtime:

https://patchwork.linuxtv.org/project/linux-media/patch/a5dff340-ab8a-46e0-1f0c-25ceaf9fe5ca@xs4all.nl/

That said, I do plan to drop patch 10/17 from the saa7146 series, since it is better
to keep the old behavior.

Once I get the green light from you, I will make a pull request for this vb2 conversion.

Regards,

	Hans

> 
>>
>> Using qv4l while tvtime is running doesn't work and sometimes
>> causes freezing of both programs (on all drivers).
> 
> Are you just starting qv4l2 when tvtime is running? Or trying to stream?
> Do you see messages in the kernel log?
> 
> I couldn't reproduce this. Since tvtime is streaming, qv4l2 shouldn't be able to
> do anything since all attempts to change something should result in EBUSY.
> 
> Regards,
> 
> 	Hans
> 
>>
>>
>> I have also build a new driver just without the patches [2].
>> It shows the "old" correct behavior.
>> So I think, the cause of the change must be somewhere in the
>> patches.
>>
>>
>>
>> Btw.:
>> I also tried to open the video device with the usual
>> media-players, but I had no luck so far (with any driver).
>>
>>
>> Regards
>>
>> Stefan
>>
>>
>> [1] git checkout -B saa7146-clean 837736a79a76c9becddf0caf905b27c144a64030
>> [2] git checkout -B saa7146-clean 2653fad0d8a9625667e9a78133ea9e1245b7c40c
>>
>>>
>>> Regards,
>>>
>>> 	Hans
>>>
>> [...]
> 

Re: saa7146: please test the vb2 conversion!

[Stefan Herdler]

On 12/04/23 13:16 Hans Verkuil wrote:
> On 12/04/2023 12:11, Hans Verkuil wrote:
>> On 10/04/2023 00:36, Stefan Herdler wrote:
>>> On 07/04/23 09:04, Hans Verkuil wrote:
>>>> On 07/04/2023 00:43, Stefan Herdler wrote:
>>> [...]
>>>>>
>>>>> VBI output is used to switch the aspect-ratio via WSS.
>>>>> this should be supported by any av7110 card.
>>>>>
>>>>> The software is run a daemon or plugin, so the userspace-facing change
>>>>> shouldn't matter.
>>>>>
>>>>> I'll test this as soon as possible.
>>>>>
>>>>>
>>>>>
>>>>>
>>>>> I've done only basic testing so far, but unfortunately it already failed.
>>>>>
>>>>> The test:
>>>>> Switch to a channel[*] and view the decoded video with tvtime.
>>>>>
>>>>> The resulting picture is corrupted.
>>>>> Almost green with some pink traces at the outlines.
>>>>>
>>>>> It reminds me to YCbCr component-yideo on a RGB-input.
>>>>> Maybe the input-format of saa7146 not set correctly?
>>>>>
>>>>> The OSD is equally affected, but the card seems to run stable.
>>>>
>>>> That's weird. When you are in this state, can you run
>>>> 'v4l2-ctl -V -d /dev/videoX' for the video device that tvtime
>>>> is using? I'll try to test it with tvtime as well next week.
>>>> I have done my tests using qvidcap and qv4l2, and that looked fine.
>>>
>>> I've done some more testing and the result is somehow confusing to me.
>>>
>>> At first I tried qv4l and it shows correct videos with any driver.
>>> And with any pixel format setting I tried.
>>>
>>>
>>> After boot /dev/video0 (there is only this device) starts always with
>>> this settings:
>>> Format Video Capture:
>>>         Width/Height      : 384/288
>>>         Pixel Format      : 'BGR3' (24-bit BGR 8-8-8)
>>>         Field             : Interlaced
>>>         Bytes per Line    : 1152
>>>         Size Image        : 331776
>>>         Colorspace        : SMPTE 170M
>>>         Transfer Function : Default (maps to Rec. 709)
>>>         YCbCr/HSV Encoding: Default (maps to ITU-R 601)
>>>         Quantization      : Default (maps to Full Range)
>>>         Flags             :
>>>
>>>
>>> On the working "old" driver tvtime switches to the following settings:
>>> Format Video Capture:
>>>         Width/Height      : 720/576
>>>         Pixel Format      : 'UYVY' (UYVY 4:2:2)
>>>         Field             : Interlaced
>>>         Bytes per Line    : 1440
>>>         Size Image        : 829440
>>>         Colorspace        : SMPTE 170M
>>>         Transfer Function : Default (maps to Rec. 709)
>>>         YCbCr/HSV Encoding: Default (maps to ITU-R 601)
>>>         Quantization      : Default (maps to Limited Range)
>>>         Flags             :
>>> It seems tvtime needs this 'UYVY' pixel format to work.
>>>
>>>
>>> On the "new" driver, with patches [1], tvtime switches to:
>>> Format Video Capture:
>>>         Width/Height      : 720/576
>>>         Pixel Format      : 'BGR3' (24-bit BGR 8-8-8)
>>>         Field             : Interlaced
>>>         Bytes per Line    : 2160
>>>         Size Image        : 1244160
>>>         Colorspace        : SMPTE 170M
>>>         Transfer Function : Default (maps to Rec. 709)
>>>         YCbCr/HSV Encoding: Default (maps to ITU-R 601)
>>>         Quantization      : Default (maps to Full Range)
>>>         Flags             :
>>> And now it is getting weird:
>>> I can switch to the correct 'UYVY' settings using qv4l.
>>> But tvtime always switches back to 'BGR3'.
>>
>> The cause is "[PATCH 10/17] media: common: saa7146: fall back to V4L2_PIX_FMT_BGR24".
>>
>> Can you drop that patch and test again?

Without this patch tvtime is working again.

>>
>> It's really a tvtime bug since drivers are allowed to either reject an unsupported
>> pixelformat (the old behavior) or replace it with a supported pixelformat (the
>> new behavior). And tvtime only supports the old behavior.
>
> FYI: I posted a patch fixing tvtime:
>
> https://patchwork.linuxtv.org/project/linux-media/patch/a5dff340-ab8a-46e0-1f0c-25ceaf9fe5ca@xs4all.nl/
>
> That said, I do plan to drop patch 10/17 from the saa7146 series, since it is better
> to keep the old behavior.
>
> Once I get the green light from you, I will make a pull request for this vb2 conversion.
>
> Regards,
>
> 	Hans
>
>>
>>>
>>> Using qv4l while tvtime is running doesn't work and sometimes
>>> causes freezing of both programs (on all drivers).
>>
>> Are you just starting qv4l2 when tvtime is running? Or trying to stream?
>> Do you see messages in the kernel log?
Just starting qv4l2 and trying to switch the pixelformat.
I haven't seen any related messages appearing while playing with qv4l2.
>>
>> I couldn't reproduce this. Since tvtime is streaming, qv4l2 shouldn't be able to
>> do anything since all attempts to change something should result in EBUSY.
Normally with qv4l2 it just happens nothing.
v4l2-ctl tells something like "device is busy".

I couldn't reproduce the freeze anymore today.
It was never really reproduce able, it only happened twice and
with different drivers. And it was always unexpected.

Today I found messages about an ARM-Crash on that particular day,
which I haven't seen before. They must have been come before or
after the tests.
The driver should recover the decoder, but sometimes it takes
a while until the it notices a crash.
So probably I haven't had connected the provisional cable to my
desktop properly that day, which caused a bad signal. That caused
an ARM-Crash, which caused the driver to freeze for a while.
And I killed applications to early.
At least that is the best explanation I have.




The vbi output is operational too.
I have verified, that the WSS bits change at the analog output.
The old tools are still working with the modified driver.


Regards

Stefan


>>
>> Regards,
>>
>> 	Hans
>>
>>>
>>>
>>> I have also build a new driver just without the patches [2].
>>> It shows the "old" correct behavior.
>>> So I think, the cause of the change must be somewhere in the
>>> patches.
>>>
>>>
>>>
>>> Btw.:
>>> I also tried to open the video device with the usual
>>> media-players, but I had no luck so far (with any driver).
>>>
>>>
>>> Regards
>>>
>>> Stefan
>>>
>>>
>>> [1] git checkout -B saa7146-clean 837736a79a76c9becddf0caf905b27c144a64030
>>> [2] git checkout -B saa7146-clean 2653fad0d8a9625667e9a78133ea9e1245b7c40c
>>>
>>>>
>>>> Regards,
>>>>
>>>> 	Hans
>>>>
>>> [...]
>>
>

Re: saa7146: please test the vb2 conversion!

[Hans Verkuil]

On 14/04/2023 02:15, Stefan Herdler wrote:
> On 12/04/23 13:16 Hans Verkuil wrote:
>> On 12/04/2023 12:11, Hans Verkuil wrote:
>>> On 10/04/2023 00:36, Stefan Herdler wrote:
>>>> On 07/04/23 09:04, Hans Verkuil wrote:
>>>>> On 07/04/2023 00:43, Stefan Herdler wrote:
>>>> [...]
>>>>>>
>>>>>> VBI output is used to switch the aspect-ratio via WSS.
>>>>>> this should be supported by any av7110 card.
>>>>>>
>>>>>> The software is run a daemon or plugin, so the userspace-facing change
>>>>>> shouldn't matter.
>>>>>>
>>>>>> I'll test this as soon as possible.
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>> I've done only basic testing so far, but unfortunately it already failed.
>>>>>>
>>>>>> The test:
>>>>>> Switch to a channel[*] and view the decoded video with tvtime.
>>>>>>
>>>>>> The resulting picture is corrupted.
>>>>>> Almost green with some pink traces at the outlines.
>>>>>>
>>>>>> It reminds me to YCbCr component-yideo on a RGB-input.
>>>>>> Maybe the input-format of saa7146 not set correctly?
>>>>>>
>>>>>> The OSD is equally affected, but the card seems to run stable.
>>>>>
>>>>> That's weird. When you are in this state, can you run
>>>>> 'v4l2-ctl -V -d /dev/videoX' for the video device that tvtime
>>>>> is using? I'll try to test it with tvtime as well next week.
>>>>> I have done my tests using qvidcap and qv4l2, and that looked fine.
>>>>
>>>> I've done some more testing and the result is somehow confusing to me.
>>>>
>>>> At first I tried qv4l and it shows correct videos with any driver.
>>>> And with any pixel format setting I tried.
>>>>
>>>>
>>>> After boot /dev/video0 (there is only this device) starts always with
>>>> this settings:
>>>> Format Video Capture:
>>>>         Width/Height      : 384/288
>>>>         Pixel Format      : 'BGR3' (24-bit BGR 8-8-8)
>>>>         Field             : Interlaced
>>>>         Bytes per Line    : 1152
>>>>         Size Image        : 331776
>>>>         Colorspace        : SMPTE 170M
>>>>         Transfer Function : Default (maps to Rec. 709)
>>>>         YCbCr/HSV Encoding: Default (maps to ITU-R 601)
>>>>         Quantization      : Default (maps to Full Range)
>>>>         Flags             :
>>>>
>>>>
>>>> On the working "old" driver tvtime switches to the following settings:
>>>> Format Video Capture:
>>>>         Width/Height      : 720/576
>>>>         Pixel Format      : 'UYVY' (UYVY 4:2:2)
>>>>         Field             : Interlaced
>>>>         Bytes per Line    : 1440
>>>>         Size Image        : 829440
>>>>         Colorspace        : SMPTE 170M
>>>>         Transfer Function : Default (maps to Rec. 709)
>>>>         YCbCr/HSV Encoding: Default (maps to ITU-R 601)
>>>>         Quantization      : Default (maps to Limited Range)
>>>>         Flags             :
>>>> It seems tvtime needs this 'UYVY' pixel format to work.
>>>>
>>>>
>>>> On the "new" driver, with patches [1], tvtime switches to:
>>>> Format Video Capture:
>>>>         Width/Height      : 720/576
>>>>         Pixel Format      : 'BGR3' (24-bit BGR 8-8-8)
>>>>         Field             : Interlaced
>>>>         Bytes per Line    : 2160
>>>>         Size Image        : 1244160
>>>>         Colorspace        : SMPTE 170M
>>>>         Transfer Function : Default (maps to Rec. 709)
>>>>         YCbCr/HSV Encoding: Default (maps to ITU-R 601)
>>>>         Quantization      : Default (maps to Full Range)
>>>>         Flags             :
>>>> And now it is getting weird:
>>>> I can switch to the correct 'UYVY' settings using qv4l.
>>>> But tvtime always switches back to 'BGR3'.
>>>
>>> The cause is "[PATCH 10/17] media: common: saa7146: fall back to V4L2_PIX_FMT_BGR24".
>>>
>>> Can you drop that patch and test again?
> 
> Without this patch tvtime is working again.

Good news! I'll prepare a pull request later today.

> 
>>>
>>> It's really a tvtime bug since drivers are allowed to either reject an unsupported
>>> pixelformat (the old behavior) or replace it with a supported pixelformat (the
>>> new behavior). And tvtime only supports the old behavior.
>>
>> FYI: I posted a patch fixing tvtime:
>>
>> https://patchwork.linuxtv.org/project/linux-media/patch/a5dff340-ab8a-46e0-1f0c-25ceaf9fe5ca@xs4all.nl/
>>
>> That said, I do plan to drop patch 10/17 from the saa7146 series, since it is better
>> to keep the old behavior.
>>
>> Once I get the green light from you, I will make a pull request for this vb2 conversion.
>>
>> Regards,
>>
>> 	Hans
>>
>>>
>>>>
>>>> Using qv4l while tvtime is running doesn't work and sometimes
>>>> causes freezing of both programs (on all drivers).
>>>
>>> Are you just starting qv4l2 when tvtime is running? Or trying to stream?
>>> Do you see messages in the kernel log?
> Just starting qv4l2 and trying to switch the pixelformat.
> I haven't seen any related messages appearing while playing with qv4l2.
>>>
>>> I couldn't reproduce this. Since tvtime is streaming, qv4l2 shouldn't be able to
>>> do anything since all attempts to change something should result in EBUSY.
> Normally with qv4l2 it just happens nothing.
> v4l2-ctl tells something like "device is busy".
> 
> I couldn't reproduce the freeze anymore today.
> It was never really reproduce able, it only happened twice and
> with different drivers. And it was always unexpected.
> 
> Today I found messages about an ARM-Crash on that particular day,
> which I haven't seen before. They must have been come before or
> after the tests.
> The driver should recover the decoder, but sometimes it takes
> a while until the it notices a crash.
> So probably I haven't had connected the provisional cable to my
> desktop properly that day, which caused a bad signal. That caused
> an ARM-Crash, which caused the driver to freeze for a while.
> And I killed applications to early.
> At least that is the best explanation I have.

Is this something that also happens with the old (vb1) version of
the driver? I'm not sure if this is related to my changes at all.

I don't see how qv4l2 can cause this to happen since trying to change
the format while tvtime is running will just return EBUSY and not do
anything else.

Regards,

	Hans

> 
> 
> 
> 
> The vbi output is operational too.
> I have verified, that the WSS bits change at the analog output.
> The old tools are still working with the modified driver.
> 
> 
> Regards
> 
> Stefan
> 
> 
>>>
>>> Regards,
>>>
>>> 	Hans
>>>
>>>>
>>>>
>>>> I have also build a new driver just without the patches [2].
>>>> It shows the "old" correct behavior.
>>>> So I think, the cause of the change must be somewhere in the
>>>> patches.
>>>>
>>>>
>>>>
>>>> Btw.:
>>>> I also tried to open the video device with the usual
>>>> media-players, but I had no luck so far (with any driver).
>>>>
>>>>
>>>> Regards
>>>>
>>>> Stefan
>>>>
>>>>
>>>> [1] git checkout -B saa7146-clean 837736a79a76c9becddf0caf905b27c144a64030
>>>> [2] git checkout -B saa7146-clean 2653fad0d8a9625667e9a78133ea9e1245b7c40c
>>>>
>>>>>
>>>>> Regards,
>>>>>
>>>>> 	Hans
>>>>>
>>>> [...]
>>>
>>

Re: saa7146: please test the vb2 conversion!

[Stefan Herdler]

On 14/04/23 10:36 Hans Verkuil wrote:
> On 14/04/2023 02:15, Stefan Herdler wrote:
>> On 12/04/23 13:16 Hans Verkuil wrote:
>>> On 12/04/2023 12:11, Hans Verkuil wrote:
>>>> On 10/04/2023 00:36, Stefan Herdler wrote:
>>>>> On 07/04/23 09:04, Hans Verkuil wrote:
>>>>>> On 07/04/2023 00:43, Stefan Herdler wrote:
>>>>> [...]
>>>>>>>
>>>>>>> VBI output is used to switch the aspect-ratio via WSS.
>>>>>>> this should be supported by any av7110 card.
>>>>>>>
>>>>>>> The software is run a daemon or plugin, so the userspace-facing change
>>>>>>> shouldn't matter.
>>>>>>>
>>>>>>> I'll test this as soon as possible.
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> I've done only basic testing so far, but unfortunately it already failed.
>>>>>>>
>>>>>>> The test:
>>>>>>> Switch to a channel[*] and view the decoded video with tvtime.
>>>>>>>
>>>>>>> The resulting picture is corrupted.
>>>>>>> Almost green with some pink traces at the outlines.
>>>>>>>
>>>>>>> It reminds me to YCbCr component-yideo on a RGB-input.
>>>>>>> Maybe the input-format of saa7146 not set correctly?
>>>>>>>
>>>>>>> The OSD is equally affected, but the card seems to run stable.
>>>>>>
>>>>>> That's weird. When you are in this state, can you run
>>>>>> 'v4l2-ctl -V -d /dev/videoX' for the video device that tvtime
>>>>>> is using? I'll try to test it with tvtime as well next week.
>>>>>> I have done my tests using qvidcap and qv4l2, and that looked fine.
>>>>>
>>>>> I've done some more testing and the result is somehow confusing to me.
>>>>>
>>>>> At first I tried qv4l and it shows correct videos with any driver.
>>>>> And with any pixel format setting I tried.
>>>>>
>>>>>
>>>>> After boot /dev/video0 (there is only this device) starts always with
>>>>> this settings:
>>>>> Format Video Capture:
>>>>>         Width/Height      : 384/288
>>>>>         Pixel Format      : 'BGR3' (24-bit BGR 8-8-8)
>>>>>         Field             : Interlaced
>>>>>         Bytes per Line    : 1152
>>>>>         Size Image        : 331776
>>>>>         Colorspace        : SMPTE 170M
>>>>>         Transfer Function : Default (maps to Rec. 709)
>>>>>         YCbCr/HSV Encoding: Default (maps to ITU-R 601)
>>>>>         Quantization      : Default (maps to Full Range)
>>>>>         Flags             :
>>>>>
>>>>>
>>>>> On the working "old" driver tvtime switches to the following settings:
>>>>> Format Video Capture:
>>>>>         Width/Height      : 720/576
>>>>>         Pixel Format      : 'UYVY' (UYVY 4:2:2)
>>>>>         Field             : Interlaced
>>>>>         Bytes per Line    : 1440
>>>>>         Size Image        : 829440
>>>>>         Colorspace        : SMPTE 170M
>>>>>         Transfer Function : Default (maps to Rec. 709)
>>>>>         YCbCr/HSV Encoding: Default (maps to ITU-R 601)
>>>>>         Quantization      : Default (maps to Limited Range)
>>>>>         Flags             :
>>>>> It seems tvtime needs this 'UYVY' pixel format to work.
>>>>>
>>>>>
>>>>> On the "new" driver, with patches [1], tvtime switches to:
>>>>> Format Video Capture:
>>>>>         Width/Height      : 720/576
>>>>>         Pixel Format      : 'BGR3' (24-bit BGR 8-8-8)
>>>>>         Field             : Interlaced
>>>>>         Bytes per Line    : 2160
>>>>>         Size Image        : 1244160
>>>>>         Colorspace        : SMPTE 170M
>>>>>         Transfer Function : Default (maps to Rec. 709)
>>>>>         YCbCr/HSV Encoding: Default (maps to ITU-R 601)
>>>>>         Quantization      : Default (maps to Full Range)
>>>>>         Flags             :
>>>>> And now it is getting weird:
>>>>> I can switch to the correct 'UYVY' settings using qv4l.
>>>>> But tvtime always switches back to 'BGR3'.
>>>>
>>>> The cause is "[PATCH 10/17] media: common: saa7146: fall back to V4L2_PIX_FMT_BGR24".
>>>>
>>>> Can you drop that patch and test again?
>>
>> Without this patch tvtime is working again.
>
> Good news! I'll prepare a pull request later today.
>
>>
>>>>
>>>> It's really a tvtime bug since drivers are allowed to either reject an unsupported
>>>> pixelformat (the old behavior) or replace it with a supported pixelformat (the
>>>> new behavior). And tvtime only supports the old behavior.
>>>
>>> FYI: I posted a patch fixing tvtime:
>>>
>>> https://patchwork.linuxtv.org/project/linux-media/patch/a5dff340-ab8a-46e0-1f0c-25ceaf9fe5ca@xs4all.nl/
>>>
>>> That said, I do plan to drop patch 10/17 from the saa7146 series, since it is better
>>> to keep the old behavior.
>>>
>>> Once I get the green light from you, I will make a pull request for this vb2 conversion.
>>>
>>> Regards,
>>>
>>> 	Hans
>>>
>>>>
>>>>>
>>>>> Using qv4l while tvtime is running doesn't work and sometimes
>>>>> causes freezing of both programs (on all drivers).
>>>>
>>>> Are you just starting qv4l2 when tvtime is running? Or trying to stream?
>>>> Do you see messages in the kernel log?
>> Just starting qv4l2 and trying to switch the pixelformat.
>> I haven't seen any related messages appearing while playing with qv4l2.
>>>>
>>>> I couldn't reproduce this. Since tvtime is streaming, qv4l2 shouldn't be able to
>>>> do anything since all attempts to change something should result in EBUSY.
>> Normally with qv4l2 it just happens nothing.
>> v4l2-ctl tells something like "device is busy".
>>
>> I couldn't reproduce the freeze anymore today.
>> It was never really reproduce able, it only happened twice and
>> with different drivers. And it was always unexpected.
>>
>> Today I found messages about an ARM-Crash on that particular day,
>> which I haven't seen before. They must have been come before or
>> after the tests.
>> The driver should recover the decoder, but sometimes it takes
>> a while until the it notices a crash.
>> So probably I haven't had connected the provisional cable to my
>> desktop properly that day, which caused a bad signal. That caused
>> an ARM-Crash, which caused the driver to freeze for a while.
>> And I killed applications to early.
>> At least that is the best explanation I have.
>
> Is this something that also happens with the old (vb1) version of
> the driver? I'm not sure if this is related to my changes at all.

I am pretty sure, that it was not related to the changes.
It happened with the old (vb1) driver of the stock kernel too.

And it happened only at this single day.
I have tried at least 50 times since then and it didn't happen again.

I'm sorry for the confusion, there must have been something else
wrong that day. But I still don't really know what.



Regards

Stefan


>
> I don't see how qv4l2 can cause this to happen since trying to change
> the format while tvtime is running will just return EBUSY and not do
> anything else.
>
> Regards,
>
> 	Hans
>
>>
>>
>>
>>
>> The vbi output is operational too.
>> I have verified, that the WSS bits change at the analog output.
>> The old tools are still working with the modified driver.
>>
>>
>> Regards
>>
>> Stefan
>>
>>
>>>>
>>>> Regards,
>>>>
>>>> 	Hans
>>>>
>>>>>
>>>>>
>>>>> I have also build a new driver just without the patches [2].
>>>>> It shows the "old" correct behavior.
>>>>> So I think, the cause of the change must be somewhere in the
>>>>> patches.
>>>>>
>>>>>
>>>>>
>>>>> Btw.:
>>>>> I also tried to open the video device with the usual
>>>>> media-players, but I had no luck so far (with any driver).
>>>>>
>>>>>
>>>>> Regards
>>>>>
>>>>> Stefan
>>>>>
>>>>>
>>>>> [1] git checkout -B saa7146-clean 837736a79a76c9becddf0caf905b27c144a64030
>>>>> [2] git checkout -B saa7146-clean 2653fad0d8a9625667e9a78133ea9e1245b7c40c
>>>>>
>>>>>>
>>>>>> Regards,
>>>>>>
>>>>>> 	Hans
>>>>>>
>>>>> [...]
>>>>
>>>
>

[PATCH v3 0/6] Legacy DVB API: completion of documentation

[Stefan Herdler]

Changes since v2:
* Split the patch into a patch series.
* Incorporate the changes requested.
* Style updates to better match the existing documentation.
* And a lot of small fixes.


Hi Mauro,

it took a little longer then expected, but I didn't had much time in spare
for this. I'm pretty much occupied by other things at the moment.
The winter season would be better for things like this, but I try to
finish it as quick as possible.

I went through your mail point by point and I'm confident, that I was able
to sort out your questions now. At least I don't see anything that need to
be improved anymore.
The work has been done in a lot of small blocks over a pretty long period
after my daily work, mostly late at night. Despite double checking
everything, I maybe still have missed something. I hope it is not too
much.

For usage it has been checked against the known projects using the DVB
decoder APIs:
* The AV7110 kernel driver.
* The out of tree driver for the HD full featured cards.[1]
* The "Enigma2" sources from openatv team.[2]
  (The drivers of the boxes are binary only.)

Possibly unused items have been listed in the comment of the patches.
Please take this lists with a pinch of salt. With the number of items
checked, it is pretty easy to miss an occurrence or have a false positive.
Although I've done my best, there is still the chance that I've missed an
use case.

I tried to complete the documentation of this unused definition too.
Most information had been collect anyway and writing it down wasn't that
much of effort.

Removing the definition and documentation later at once is always an
option.
I would prefer to do it this way, if something has to be removed.
It is easier to revert the change in case of a regression.
If necessary I can provide the patches too.

Regards
Stefan

[1: https://github.com/s-moch/linux-saa716x]
[2: https://github.com/openatv/enigma2/tree/master]



Stefan Herdler (6):
  Add documentation for legacy DVB decoder API
  Add documentation for osd.h
  Add documentation for audio.h (data types)
  Add documentation for audio.h (function calls)
  Add documentation for video.h (data types)
  Add documentation for video.h (function calls)

 .../media/dvb/legacy_dvb_apis.rst             |    1 +
 .../media/dvb/legacy_dvb_audio.rst            | 1642 +++++++++++
 .../media/dvb/legacy_dvb_decoder_api.rst      |   61 +
 .../media/dvb/legacy_dvb_osd.rst              |  883 ++++++
 .../media/dvb/legacy_dvb_video.rst            | 2430 +++++++++++++++++
 5 files changed, 5017 insertions(+)
 create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst
 create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst
 create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst
 create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_video.rst

--
2.34.0

[PATCH v3 1/6] Add documentation for legacy DVB decoder API

[Stefan Herdler]

Add new indexfile and link to it.

Signed-off-by: Stefan Herdler <herdler@nurfuerspam.de>
---

>> +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
>
> Please place it dual licensed with GFDL and GPL 2.0.

Changed to GFDL OR GPL-2.0 like in "media/glossary.rst".

GPL 2.0 is fine for me too, but the old documentation, my work is based on, was GFDL.
Can we just change the license?
That's not mine to judge.



 .../media/dvb/legacy_dvb_apis.rst             |  1 +
 .../media/dvb/legacy_dvb_decoder_api.rst      | 61 +++++++++++++++++++
 2 files changed, 62 insertions(+)
 create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst

diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst
index b97d56ee543c..ffe8325749e5 100644
--- a/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst
+++ b/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst
@@ -23,3 +23,4 @@ DVB-S2, DVB-T2, ISDB, etc.
     :maxdepth: 1

     frontend_legacy_dvbv3_api
+    legacy_dvb_decoder_api
diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst
new file mode 100644
index 000000000000..f6e2f28b1fcb
--- /dev/null
+++ b/Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst
@@ -0,0 +1,61 @@
+.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0
+
+.. _legacy_dvb_decoder_api:
+
+============================
+Legacy DVB MPEG Decoder APIs
+============================
+
+.. _legacy_dvb_decoder_notes:
+
+General Notes
+=============
+
+This API has originally been designed for DVB only and is therefore limited to
+the :ref:`legacy_dvb_decoder_formats` used in such digital TV-broadcastsystems.
+
+To circumvent this limitations the more versatile :ref:`V4L2 <v4l2spec>` API has
+been designed. Which replaces this part of the DVB API.
+
+Nevertheless there have been projects build around this API.
+To ensure compatibility this API is kept as it is.
+
+.. attention:: Do **not** use this API in new drivers!
+
+    For audio and video use the :ref:`V4L2 <v4l2spec>` and ALSA APIs.
+
+    Pipelines should be set up using the :ref:`Media Controller  API<media_controller>`.
+
+Practically the decoders seem to be treated differently. The application typically
+knows which decoder is in use or it is specially written for one decoder type.
+Querying capabilities are rarely used because they are already known.
+
+
+.. _legacy_dvb_decoder_formats:
+
+Data Formats
+============
+
+The API has been designed for DVB and compatible broadcastsystems.
+Because of that fact the only supported data formats are ISO/IEC 13818-1
+compatible MPEG streams. The supported payloads may vary depending on the
+used decoder.
+
+Timestamps are always MPEG PTS as defined in ITU T-REC-H.222.0 /
+ISO/IEC 13818-1, if not otherwise noted.
+
+For storing recordings typically TS streams are used, in lesser extent PES.
+Both variants are commonly accepted for playback, but it may be driver dependent.
+
+
+
+
+Table of Contents
+=================
+
+.. toctree::
+    :maxdepth: 2
+
+    legacy_dvb_video
+    legacy_dvb_audio
+    legacy_dvb_osd
--
2.34.0

[PATCH v3 2/6] Add documentation for osd.h

[Stefan Herdler]

Add new documentation file for osd.h

Signed-off-by: Stefan Herdler <herdler@nurfuerspam.de>
---

Everything is used by the AV7110 driver, except 3 OSD_Commands.
Remarks has been placed there.

That's probably the best solution.
Removing would create a gap in the enumeration.
Omitting in the documentation would make header and documentation
inconsistent again.



 .../media/dvb/legacy_dvb_osd.rst              | 883 ++++++++++++++++++
 1 file changed, 883 insertions(+)
 create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst

diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst
new file mode 100644
index 000000000000..eb4754bb00d0
--- /dev/null
+++ b/Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst
@@ -0,0 +1,883 @@
+.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0
+
+.. c:namespace:: dtv.legacy.osd
+
+.. _dvb_osd:
+
+==============
+DVB OSD Device
+==============
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+The DVB OSD device controls the OnScreen-Display of the AV7110 based
+DVB-cards with hardware MPEG2 decoder. It can be accessed through
+``/dev/dvb/adapter?/osd0``.
+Data types and ioctl definitions can be accessed by including
+``linux/dvb/osd.h`` in your application.
+
+The OSD is not a frame-buffer like on many other cards.
+It is a kind of canvas one can draw on.
+The color-depth is limited depending on the memory size installed.
+An appropriate palette of colors has to be set up.
+The installed memory size can be identified with the `OSD_GET_CAPABILITY`_
+ioctl.
+
+OSD Data Types
+==============
+
+OSD_Command
+-----------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    typedef enum {
+	/* All functions return -2 on "not open" */
+	OSD_Close = 1,
+	OSD_Open,
+	OSD_Show,
+	OSD_Hide,
+	OSD_Clear,
+	OSD_Fill,
+	OSD_SetColor,
+	OSD_SetPalette,
+	OSD_SetTrans,
+	OSD_SetPixel,
+	OSD_GetPixel,
+	OSD_SetRow,
+	OSD_SetBlock,
+	OSD_FillRow,
+	OSD_FillBlock,
+	OSD_Line,
+	OSD_Query,
+	OSD_Test,
+	OSD_Text,
+	OSD_SetWindow,
+	OSD_MoveWindow,
+	OSD_OpenRaw,
+    } OSD_Command;
+
+Commands
+~~~~~~~~
+
+.. note::  All functions return -2 on "not open"
+
+.. flat-table::
+    :header-rows:  1
+    :stub-columns: 0
+
+    -  ..
+
+       -  Command
+
+       -  | Used variables of ``struct`` `osd_cmd_t`_.
+          | Usage{variable} if alternative use.
+
+       -  :cspan:`2` Description
+
+
+
+    -  ..
+
+       -  ``OSD_Close``
+
+       -  -
+
+       -  | Disables OSD and releases the buffers.
+          | Returns 0 on success.
+
+    -  ..
+
+       -  ``OSD_Open``
+
+       -  | x0,y0,x1,y1,
+          | BitPerPixel[2/4/8]{color&0x0F},
+          | mix[0..15]{color&0xF0}
+
+       -  | Opens OSD with this size and bit depth
+          | Returns 0 on success,
+          | -1 on DRAM allocation error,
+          | -2 on "already open".
+
+    -  ..
+
+       -  ``OSD_Show``
+
+       - -
+
+       -  | Enables OSD mode.
+          | Returns 0 on success.
+
+    -  ..
+
+       -  ``OSD_Hide``
+
+       - -
+
+       -  | Disables OSD mode.
+          | Returns 0 on success.
+
+    -  ..
+
+       -  ``OSD_Clear``
+
+       - -
+
+       -  | Sets all pixel to color 0.
+          | Returns 0 on success.
+
+    -  ..
+
+       -  ``OSD_Fill``
+
+       -  color
+
+       -  | Sets all pixel to color <color>.
+          | Returns 0 on success.
+
+    -  ..
+
+       -  ``OSD_SetColor``
+
+       -  | color,
+          | R{x0},G{y0},B{x1},
+          | opacity{y1}
+
+       -  | Set palette entry <num> to <r,g,b>, <mix> and <trans> apply
+          | R,G,B: 0..255
+          | R=Red, G=Green, B=Blue
+          | opacity=0:      pixel opacity 0% (only video pixel shows)
+          | opacity=1..254: pixel opacity as specified in header
+          | opacity=255:    pixel opacity 100% (only OSD pixel shows)
+          | Returns 0 on success, -1 on error.
+
+    -  ..
+
+       -  ``OSD_SetPalette``
+
+       -  | firstcolor{color},
+          | lastcolor{x0},data
+
+       -  | Set a number of entries in the palette.
+          | Sets the entries "firstcolor" through "lastcolor" from the
+            array "data".
+          | Data has 4 byte for each color:
+          | R,G,B, and a opacity value: 0->transparent, 1..254->mix,
+            255->pixel
+
+    -  ..
+
+       -  ``OSD_SetTrans``
+
+       -  transparency{color}
+
+       -  | Sets transparency of mixed pixel (0..15).
+          | Returns 0 on success.
+
+    -  ..
+
+       -  ``OSD_SetPixel``
+
+       -  x0,y0,color
+
+       -  | Sets pixel <x>,<y> to color number <color>.
+          | Returns 0 on success, -1 on error.
+
+    -  ..
+
+       -  ``OSD_GetPixel``
+
+       -  x0,y0
+
+       -  | Returns color number of pixel <x>,<y>,  or -1.
+          | Command currently not supported by the AV7110!
+
+    -  ..
+
+       -  ``OSD_SetRow``
+
+       -  x0,y0,x1,data
+
+       -  | Fills pixels x0,y through  x1,y with the content of data[].
+          | Returns 0 on success, -1 on clipping all pixel (no pixel
+            drawn).
+
+    -  ..
+
+       -  ``OSD_SetBlock``
+
+       -  | x0,y0,x1,y1,
+          | increment{color},
+          | data
+
+       -  | Fills pixels x0,y0 through  x1,y1 with the content of data[].
+          | Inc contains the width of one line in the data block,
+          | inc<=0 uses block width as line width.
+          | Returns 0 on success, -1 on clipping all pixel.
+
+    -  ..
+
+       -  ``OSD_FillRow``
+
+       -  x0,y0,x1,color
+
+       -  | Fills pixels x0,y through  x1,y with the color <color>.
+          | Returns 0 on success, -1 on clipping all pixel.
+
+    -  ..
+
+       -  ``OSD_FillBlock``
+
+       -  x0,y0,x1,y1,color
+
+       -  | Fills pixels x0,y0 through  x1,y1 with the color <color>.
+          | Returns 0 on success, -1 on clipping all pixel.
+
+    -  ..
+
+       -  ``OSD_Line``
+
+       -  x0,y0,x1,y1,color
+
+       -  | Draw a line from x0,y0 to x1,y1 with the color <color>.
+          | Returns 0 on success.
+
+    -  ..
+
+       -  ``OSD_Query``
+
+       -  | x0,y0,x1,y1,
+          | xasp{color}; yasp=11
+
+       -  | Fills parameters with the picture dimensions and the pixel
+            aspect ratio.
+          | Returns 0 on success.
+          | Command currently not supported by the AV7110!
+
+    -  ..
+
+       -  ``OSD_Test``
+
+       -  -
+
+       -  | Draws a test picture.
+          | For debugging purposes only.
+          | Returns 0 on success.
+    -  ..
+
+       -  ``OSD_Text``
+
+       -  x0,y0,size,color,text
+
+       -  Draws a text at position x0,y0 with the color <color>.
+
+    -  ..
+
+       -  ``OSD_SetWindow``
+
+       -  x0
+
+       -  Set window with number 0<x0<8 as current.
+
+    -  ..
+
+       -  ``OSD_MoveWindow``
+
+       -  x0,y0
+
+       -  Move current window to (x0, y0).
+
+    -  ..
+
+       -  ``OSD_OpenRaw``
+
+       -  | x0,y0,x1,y1,
+          | `osd_raw_window_t`_ {color}
+
+       -  Open other types of OSD windows.
+
+Description
+~~~~~~~~~~~
+
+The ``OSD_Command`` data type is used with the `OSD_SEND_CMD`_ ioctl to
+tell the driver which OSD_Command to execute.
+
+
+-----
+
+osd_cmd_t
+---------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    typedef struct osd_cmd_s {
+	OSD_Command cmd;
+	int x0;
+	int y0;
+	int x1;
+	int y1;
+	int color;
+	void __user *data;
+    } osd_cmd_t;
+
+Variables
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``OSD_Command cmd``
+
+       -  `OSD_Command`_ to be executed.
+
+    -  ..
+
+       -  ``int x0``
+
+       -  First horizontal position.
+
+    -  ..
+
+       -  ``int y0``
+
+       -  First vertical position.
+
+    -  ..
+
+       -  ``int x1``
+
+       -  Second horizontal position.
+
+    -  ..
+
+       -  ``int y1``
+
+       -  Second vertical position.
+
+    -  ..
+
+       -  ``int color``
+
+       -  Number of the color in the palette.
+
+    -  ..
+
+       -  ``void __user *data``
+
+       -  Command specific Data.
+
+Description
+~~~~~~~~~~~
+
+The ``osd_cmd_t`` data type is used with the `OSD_SEND_CMD`_ ioctl.
+It contains the data for the OSD_Command and the `OSD_Command`_ itself.
+The structure has to be passed to the driver and the components may be
+modified by it.
+
+
+-----
+
+
+osd_raw_window_t
+----------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    typedef enum {
+	OSD_BITMAP1,
+	OSD_BITMAP2,
+	OSD_BITMAP4,
+	OSD_BITMAP8,
+	OSD_BITMAP1HR,
+	OSD_BITMAP2HR,
+	OSD_BITMAP4HR,
+	OSD_BITMAP8HR,
+	OSD_YCRCB422,
+	OSD_YCRCB444,
+	OSD_YCRCB444HR,
+	OSD_VIDEOTSIZE,
+	OSD_VIDEOHSIZE,
+	OSD_VIDEOQSIZE,
+	OSD_VIDEODSIZE,
+	OSD_VIDEOTHSIZE,
+	OSD_VIDEOTQSIZE,
+	OSD_VIDEOTDSIZE,
+	OSD_VIDEONSIZE,
+	OSD_CURSOR
+    } osd_raw_window_t;
+
+Constants
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``OSD_BITMAP1``
+
+       -  :cspan:`1` 1 bit bitmap
+
+    -  ..
+
+       -  ``OSD_BITMAP2``
+
+       -  2 bit bitmap
+
+    -  ..
+
+       -  ``OSD_BITMAP4``
+
+       -  4 bit bitmap
+
+    -  ..
+
+       -  ``OSD_BITMAP8``
+
+       -  8 bit bitmap
+
+    -  ..
+
+       -  ``OSD_BITMAP1HR``
+
+       -  1 Bit bitmap half resolution
+
+    -  ..
+
+       -  ``OSD_BITMAP2HR``
+
+       -  2 Bit bitmap half resolution
+
+    -  ..
+
+       -  ``OSD_BITMAP4HR``
+
+       -  4 Bit bitmap half resolution
+
+    -  ..
+
+       -  ``OSD_BITMAP8HR``
+
+       -  8 Bit bitmap half resolution
+
+    -  ..
+
+       -  ``OSD_YCRCB422``
+
+       -  4:2:2 YCRCB Graphic Display
+
+    -  ..
+
+       -  ``OSD_YCRCB444``
+
+       -  4:4:4 YCRCB Graphic Display
+
+    -  ..
+
+       -  ``OSD_YCRCB444HR``
+
+       -  4:4:4 YCRCB graphic half resolution
+
+    -  ..
+
+       -  ``OSD_VIDEOTSIZE``
+
+       -  True Size Normal MPEG Video Display
+
+    -  ..
+
+       -  ``OSD_VIDEOHSIZE``
+
+       -  MPEG Video Display Half Resolution
+
+    -  ..
+
+       -  ``OSD_VIDEOQSIZE``
+
+       -  MPEG Video Display Quarter Resolution
+
+    -  ..
+
+       -  ``OSD_VIDEODSIZE``
+
+       -  MPEG Video Display Double Resolution
+
+    -  ..
+
+       -  ``OSD_VIDEOTHSIZE``
+
+       -  True Size MPEG Video Display Half Resolution
+
+    -  ..
+
+       -  ``OSD_VIDEOTQSIZE``
+
+       -  True Size MPEG Video Display Quarter Resolution
+
+    -  ..
+
+       -  ``OSD_VIDEOTDSIZE``
+
+       -  True Size MPEG Video Display Double Resolution
+
+    -  ..
+
+       -  ``OSD_VIDEONSIZE``
+
+       -  Full Size MPEG Video Display
+
+    -  ..
+
+       -  ``OSD_CURSOR``
+
+       -  Cursor
+
+Description
+~~~~~~~~~~~
+
+The ``osd_raw_window_t`` data type is used with the `OSD_Command`_
+OSD_OpenRaw to tell the driver which type of OSD to open.
+
+
+-----
+
+
+osd_cap_t
+---------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    typedef struct osd_cap_s {
+	int  cmd;
+    #define OSD_CAP_MEMSIZE         1
+	long val;
+    } osd_cap_t;
+
+Variables
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int  cmd``
+
+       -  Capability to query.
+
+    -  ..
+
+       -  ``long val``
+
+       -  Used to store the Data.
+
+Supported capabilities
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``OSD_CAP_MEMSIZE``
+
+       -  Memory size installed on the card.
+
+Description
+~~~~~~~~~~~
+
+This structure of data used with the `OSD_GET_CAPABILITY`_ call.
+
+
+-----
+
+
+OSD Function Calls
+==================
+
+OSD_SEND_CMD
+------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: OSD_SEND_CMD
+
+.. code-block:: c
+
+    int ioctl(int fd, int request = OSD_SEND_CMD, enum osd_cmd_t *cmd)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Pointer to the location of the structure `osd_cmd_t`_ for this
+          command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl sends the `OSD_Command`_ to the card.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``EINVAL``
+
+       -  Command is out of range.
+
+
+-----
+
+
+OSD_GET_CAPABILITY
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: OSD_GET_CAPABILITY
+
+.. code-block:: c
+
+    int ioctl(int fd, int request = OSD_GET_CAPABILITY,
+    struct osd_cap_t *cap)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``OSD_GET_CAPABILITY`` for this command.
+
+    -  ..
+
+       -  ``unsigned int *cap``
+
+       -  Pointer to the location of the structure `osd_cap_t`_ for this
+          command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is used to get the capabilities of the OSD of the AV7110 based
+DVB-decoder-card in use.
+
+.. note::
+    The structure osd_cap_t has to be setup by the user and passed to the
+    driver.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  ..
+
+       -  ``EINVAL``
+
+       -  Unsupported capability.
+
+
+-----
+
+
+open()
+------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    #include <fcntl.h>
+
+.. c:function:: int open(const char *deviceName, int flags)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``const char *deviceName``
+
+       -  Name of specific OSD device.
+
+    -  ..
+
+       -  :rspan:`3` ``int flags``
+
+       -  :cspan:`1` A bit-wise OR of the following flags:
+
+    -  ..
+
+       -  ``O_RDONLY``
+
+       -  read-only access
+
+    -  ..
+
+       -  ``O_RDWR``
+
+       -  read/write access
+
+    -  ..
+
+       -  ``O_NONBLOCK``
+       -  | Open in non-blocking mode
+          | (blocking mode is the default)
+
+Description
+~~~~~~~~~~~
+
+This system call opens a named OSD device (e.g.
+``/dev/dvb/adapter?/osd0``) for subsequent use.
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``ENODEV``
+
+       -  Device driver not loaded/available.
+
+    -  ..
+
+       -  ``EINTERNAL``
+
+       -  Internal error.
+
+    -  ..
+
+       -  ``EBUSY``
+
+       -  Device or resource busy.
+
+    -  ..
+
+       -  ``EINVAL``
+
+       -  Invalid argument.
+
+
+-----
+
+
+close()
+-------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int close(int fd)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_ .
+
+Description
+~~~~~~~~~~~
+
+This system call closes a previously opened OSD device.
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``EBADF``
+
+       -  fd is not a valid open file descriptor.
--
2.34.0

[PATCH v3 3/6] Add documentation for audio.h (data types)

[Stefan Herdler]

Add new documentation file for audio.h
Step 1: data types only

Signed-off-by: Stefan Herdler <herdler@nurfuerspam.de>
---
 .../media/dvb/legacy_dvb_audio.rst            | 447 ++++++++++++++++++
 1 file changed, 447 insertions(+)
 create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst

diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst
new file mode 100644
index 000000000000..4c994f8c97e5
--- /dev/null
+++ b/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst
@@ -0,0 +1,447 @@
+.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0
+
+.. c:namespace:: dtv.legacy.audio
+
+.. _dvb_audio:
+
+================
+DVB Audio Device
+================
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+The DVB audio device controls the MPEG2 audio decoder of the DVB
+hardware. It can be accessed through ``/dev/dvb/adapter?/audio?``. Data
+types and ioctl definitions can be accessed by including
+``linux/dvb/audio.h`` in your application.
+
+Please note that most DVB cards don’t have their own MPEG decoder, which
+results in the omission of the audio and video device.
+
+These ioctls were also used by V4L2 to control MPEG decoders implemented
+in V4L2. The use of these ioctls for that purpose has been made obsolete
+and proper V4L2 ioctls or controls have been created to replace that
+functionality. Use :ref:`V4L2 ioctls<video>` for new drivers!
+
+
+Audio Data Types
+================
+
+This section describes the structures, data types and defines used when
+talking to the audio device.
+
+
+-----
+
+
+audio_stream_source_t
+---------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:enum:: audio_stream_source_t
+
+.. code-block:: c
+
+    typedef enum {
+    AUDIO_SOURCE_DEMUX,
+    AUDIO_SOURCE_MEMORY
+    } audio_stream_source_t;
+
+Constants
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``AUDIO_SOURCE_DEMUX``
+
+       -  :cspan:`1` Selects the demultiplexer (fed either by the frontend
+          or the DVR device) as the source of the video stream.
+
+    -  ..
+
+       -  ``AUDIO_SOURCE_MEMORY``
+
+       -  Selects the stream from the application that comes through
+          the `write()`_ system call.
+
+Description
+~~~~~~~~~~~
+
+The audio stream source is set through the `AUDIO_SELECT_SOURCE`_ call
+and can take the following values, depending on whether we are replaying
+from an internal (demux) or external (user write) source.
+
+The data fed to the decoder is also controlled by the PID-filter.
+Output selection: :c:enum:`dmx_output` ``DMX_OUT_DECODER``.
+
+
+-----
+
+
+audio_play_state_t
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:enum:: audio_play_state_t
+
+.. code-block:: c
+
+    typedef enum {
+	AUDIO_STOPPED,
+	AUDIO_PLAYING,
+	AUDIO_PAUSED
+    } audio_play_state_t;
+
+Constants
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``AUDIO_STOPPED``
+
+       -  Audio is stopped.
+
+    -  ..
+
+       -  ``AUDIO_PLAYING``
+
+       -  Audio is currently playing.
+
+    -  ..
+
+       -  ``AUDIO_PAUSE``
+
+       -  Audio is frozen.
+
+Description
+~~~~~~~~~~~
+
+This values can be returned by the `AUDIO_GET_STATUS`_ call
+representing the state of audio playback.
+
+
+-----
+
+
+audio_channel_select_t
+----------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:enum:: audio_channel_select_t
+
+.. code-block:: c
+
+    typedef enum {
+	AUDIO_STEREO,
+	AUDIO_MONO_LEFT,
+	AUDIO_MONO_RIGHT,
+	AUDIO_MONO,
+	AUDIO_STEREO_SWAPPED
+    } audio_channel_select_t;
+
+Constants
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``AUDIO_STEREO``
+
+       -  Stereo.
+
+    -  ..
+
+       -  ``AUDIO_MONO_LEFT``
+
+       -  Mono, select left stereo channel as source.
+
+    -  ..
+
+       -  ``AUDIO_MONO_RIGHT``
+
+       -  Mono, select right stereo channel as source.
+
+    -  ..
+
+       -  ``AUDIO_MONO``
+
+       -  Mono source only.
+
+    -  ..
+
+       -  ``AUDIO_STEREO_SWAPPED``
+
+       -  Stereo, swap L & R.
+
+Description
+~~~~~~~~~~~
+
+The audio channel selected via `AUDIO_CHANNEL_SELECT`_ is determined by
+this values.
+
+
+-----
+
+
+audio_mixer_t
+-------------
+
+Synopsis
+~~~~~~~~
+
+.. c:struct:: audio_mixer
+
+.. code-block:: c
+
+    typedef struct audio_mixer {
+	unsigned int volume_left;
+	unsigned int volume_right;
+    } audio_mixer_t;
+
+Variables
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``unsigned int volume_left``
+
+       -  Volume left channel.
+          Valid range: 0 ... 255
+
+    -  ..
+
+       -  ``unsigned int volume_right``
+
+       -  Volume right channel.
+          Valid range: 0 ... 255
+
+Description
+~~~~~~~~~~~
+
+This structure is used by the `AUDIO_SET_MIXER`_ call to set the
+audio volume.
+
+
+-----
+
+
+audio_status
+------------
+
+Synopsis
+~~~~~~~~
+
+.. c:struct:: audio_status
+
+.. code-block:: c
+
+    typedef struct audio_status {
+	int AV_sync_state;
+	int mute_state;
+	audio_play_state_t play_state;
+	audio_stream_source_t stream_source;
+	audio_channel_select_t channel_select;
+	int bypass_mode;
+	audio_mixer_t mixer_state;
+    } audio_status_t;
+
+Variables
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  :rspan:`2` ``int AV_sync_state``
+
+       -  :cspan:`1` Shows if A/V synchronization is ON or OFF.
+
+    -  ..
+
+       -  TRUE  ( != 0 )
+
+       -  AV-sync ON.
+
+    -  ..
+
+       -  FALSE ( == 0 )
+
+       -  AV-sync OFF.
+
+    -  ..
+
+       -  :rspan:`2` ``int mute_state``
+
+       -  :cspan:`1` Indicates if audio is muted or not.
+
+    -  ..
+
+       -  TRUE  ( != 0 )
+
+       -  mute audio
+
+    -  ..
+
+       -  FALSE ( == 0 )
+
+       -  unmute audio
+
+    -  ..
+
+       -  `audio_play_state_t`_ ``play_state``
+
+       -  Current playback state.
+
+    -  ..
+
+       -  `audio_stream_source_t`_ ``stream_source``
+
+       -  Current source of the data.
+
+    -  ..
+
+       -  :rspan:`2` ``int bypass_mode``
+
+       -  :cspan:`1` Is the decoding of the current Audio stream in
+          the DVB subsystem enabled or disabled.
+
+    -  ..
+
+       -  TRUE  ( != 0 )
+
+       -  Bypass disabled.
+
+    -  ..
+
+       -  FALSE ( == 0 )
+
+       -  Bypass enabled.
+
+    -  ..
+
+       -  `audio_mixer_t`_ ``mixer_state``
+
+       -  Current volume settings.
+
+Description
+~~~~~~~~~~~
+
+The `AUDIO_GET_STATUS`_ call returns this structure as information
+about various states of the playback operation.
+
+
+-----
+
+
+audio encodings
+---------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+     #define AUDIO_CAP_DTS    1
+     #define AUDIO_CAP_LPCM   2
+     #define AUDIO_CAP_MP1    4
+     #define AUDIO_CAP_MP2    8
+     #define AUDIO_CAP_MP3   16
+     #define AUDIO_CAP_AAC   32
+     #define AUDIO_CAP_OGG   64
+     #define AUDIO_CAP_SDDS 128
+     #define AUDIO_CAP_AC3  256
+
+Constants
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``AUDIO_CAP_DTS``
+
+       -  :cspan:`1` The hardware accepts DTS audio tracks.
+
+    -  ..
+
+       -  ``AUDIO_CAP_LPCM``
+
+       -   The hardware accepts uncompressed audio with
+           Linear Pulse-Code Modulation (LPCM)
+
+    -  ..
+
+       -  ``AUDIO_CAP_MP1``
+
+       -  The hardware accepts MPEG-1 Audio Layer 1.
+
+    -  ..
+
+       -  ``AUDIO_CAP_MP2``
+
+       -  The hardware accepts MPEG-1 Audio Layer 2.
+          Also known as MUSICAM.
+
+    -  ..
+
+       -  ``AUDIO_CAP_MP3``
+
+       -  The hardware accepts MPEG-1 Audio Layer III.
+          Commomly known as .mp3.
+
+    -  ..
+
+       -  ``AUDIO_CAP_AAC``
+
+       -  The hardware accepts AAC (Advanced Audio Coding).
+
+    -  ..
+
+       -  ``AUDIO_CAP_OGG``
+
+       -  The hardware accepts Vorbis audio tracks.
+
+    -  ..
+
+       -  ``AUDIO_CAP_SDDS``
+
+       -  The hardware accepts Sony Dynamic Digital Sound (SDDS).
+
+    -  ..
+
+       -  ``AUDIO_CAP_AC3``
+
+       -  The hardware accepts Dolby Digital ATSC A/52 audio.
+          Also known as AC-3.
+
+Description
+~~~~~~~~~~~
+
+A call to `AUDIO_GET_CAPABILITIES`_ returns an unsigned integer with the
+following bits set according to the hardwares capabilities.
--
2.34.0

[PATCH v3 4/6] Add documentation for audio.h (function calls)

[Stefan Herdler]

Step 2: Add documentation for function calls.

Signed-off-by: Stefan Herdler <herdler@nurfuerspam.de>
---

Possibly unused:
AUDIO_SET_ID
AUDIO_SET_STREAMTYPE
AUDIO_BILINGUAL_CHANNEL_SELECT



> +
> +AUDIO_SET_ID
> +------------
> +
> +AUDIO_SET_STREAMTYPE
> +--------------------
This ioctls are dealing with stream types and IDs defined in
ITU-T H.222.0. The intention is pretty clear when reading the introduction
of Annex Q there.
However this ioctls doesn't seem to be used anywhere.



>> +
>> +AUDIO_BILINGUAL_CHANNEL_SELECT
>> +------------------------------
>> +
>
[...]
>
> IMO, this is also another problematic API. Its name seems to be related
> to language selection. However, multi-language usually uses different
> PIDs. Maybe in the past they used to place two languages at the same
> PID, one at the left channel and the other at the right one?

It seems to be intended this way.
This kind multi-language was popular in the beginning of DVB, but it has
been mostly replaced by multiple PIDs.

The AV7110 uses AUDIO_CHANNEL_SELECT for the same purpose.
This 2 ioctls look redundant to me and AUDIO_BILINGUAL_CHANNEL_SELECT
doesn't seem to be used at all.



 .../media/dvb/legacy_dvb_audio.rst            | 1195 +++++++++++++++++
 1 file changed, 1195 insertions(+)

diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst
index 4c994f8c97e5..45d330c33caf 100644
--- a/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst
+++ b/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst
@@ -445,3 +445,1198 @@ Description

 A call to `AUDIO_GET_CAPABILITIES`_ returns an unsigned integer with the
 following bits set according to the hardwares capabilities.
+
+
+-----
+
+
+Audio Function Calls
+====================
+
+
+AUDIO_STOP
+----------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_STOP
+
+.. code-block:: c
+
+	 int ioctl(int fd, int request = AUDIO_STOP)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  :cspan:`1` Equals ``AUDIO_STOP`` for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to stop playing the current
+stream.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_PLAY
+----------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_PLAY
+
+.. code-block:: c
+
+	 int  ioctl(int fd, int request = AUDIO_PLAY)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  :cspan:`1` Equals ``AUDIO_PLAY`` for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to start playing an audio stream
+from the selected source.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_PAUSE
+-----------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_PAUSE
+
+.. code-block:: c
+
+	 int  ioctl(int fd, int request = AUDIO_PAUSE)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``AUDIO_PAUSE`` for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call suspends the audio stream being played. Decoding and
+playing are paused. It is then possible to restart again decoding and
+playing process of the audio stream using `AUDIO_CONTINUE`_ command.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_CONTINUE
+--------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_CONTINUE
+
+.. code-block:: c
+
+	 int  ioctl(int fd, int request = AUDIO_CONTINUE)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``AUDIO_CONTINUE`` for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl restarts the decoding and playing process previously paused
+with `AUDIO_PAUSE`_ command.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_SELECT_SOURCE
+-------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_SELECT_SOURCE
+
+.. code-block:: c
+
+	 int ioctl(int fd, int request = AUDIO_SELECT_SOURCE,
+	 audio_stream_source_t source)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``AUDIO_SELECT_SOURCE`` for this command.
+
+    -  ..
+
+       -  `audio_stream_source_t`_ ``source``
+
+       -  Indicates the source that shall be used for the Audio stream.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call informs the audio device which source shall be used for
+the input data. The possible sources are demux or memory. If
+``AUDIO_SOURCE_MEMORY`` is selected, the data is fed to the Audio Device
+through the write command. If ``AUDIO_SOURCE_DEMUX`` is selected, the data
+is directly transferred from the onboard demux-device to the decoder.
+Note: This only supports DVB-devices with one demux and one decoder so far.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_SET_MUTE
+--------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_SET_MUTE
+
+.. code-block:: c
+
+	 int  ioctl(int fd, int request = AUDIO_SET_MUTE, int state)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  :cspan:`1` Equals ``AUDIO_SET_MUTE`` for this command.
+
+    -  ..
+
+       -  :rspan:`2` ``int state``
+
+       -  :cspan:`1` Indicates if audio device shall mute or not.
+
+    -  ..
+
+       -  TRUE  ( != 0 )
+
+       -  mute audio
+
+    -  ..
+
+       -  FALSE ( == 0 )
+
+       -  unmute audio
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for DVB devices only. To control a V4L2 decoder use the
+V4L2 :ref:`VIDIOC_DECODER_CMD` with the
+``V4L2_DEC_CMD_START_MUTE_AUDIO`` flag instead.
+
+This ioctl call asks the audio device to mute the stream that is
+currently being played.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_SET_AV_SYNC
+-----------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_SET_AV_SYNC
+
+.. code-block:: c
+
+	 int  ioctl(int fd, int request = AUDIO_SET_AV_SYNC, int state)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  :cspan:`1` Equals ``AUDIO_AV_SYNC`` for this command.
+
+    -  ..
+
+       -  :rspan:`2` ``int state``
+
+       -  :cspan:`1` Tells the DVB subsystem if A/V synchronization
+          shall be ON or OFF.
+
+    -  ..
+
+       -  TRUE  ( != 0 )
+
+       -  AV-sync ON.
+
+    -  ..
+
+       -  FALSE ( == 0 )
+
+       -  AV-sync OFF.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to turn ON or OFF A/V
+synchronization.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_SET_BYPASS_MODE
+---------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_SET_BYPASS_MODE
+
+.. code-block:: c
+
+	 int ioctl(int fd, int request = AUDIO_SET_BYPASS_MODE, int mode)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  :cspan:`1` Equals ``AUDIO_SET_BYPASS_MODE`` for this command.
+
+    -  ..
+
+       -  :rspan:`2` ``int mode``
+
+       -  :cspan:`1` Enables or disables the decoding of the current
+          Audio stream in the DVB subsystem.
+    -  ..
+
+       -  TRUE  ( != 0 )
+
+       -  Disable bypass
+
+    -  ..
+
+       -  FALSE ( == 0 )
+
+       -  Enable bypass
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to bypass the Audio decoder and
+forward the stream without decoding. This mode shall be used if streams
+that can’t be handled by the DVB system shall be decoded. Dolby
+DigitalTM streams are automatically forwarded by the DVB subsystem if
+the hardware can handle it.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_CHANNEL_SELECT
+--------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_CHANNEL_SELECT
+
+.. code-block:: c
+
+	 int ioctl(int fd, int request = AUDIO_CHANNEL_SELECT,
+	 audio_channel_select_t)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``AUDIO_CHANNEL_SELECT`` for this command.
+
+    -  ..
+
+       -  `audio_channel_select_t`_ ``ch``
+
+       -  Select the output format of the audio (mono left/right, stereo).
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for DVB devices only. To control a V4L2 decoder use the
+V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK`` control instead.
+
+This ioctl call asks the Audio Device to select the requested channel if
+possible.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_GET_STATUS
+----------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_GET_STATUS
+
+.. code-block:: c
+
+	 int ioctl(int fd, int request = AUDIO_GET_STATUS,
+	 struct audio_status *status)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals AUDIO_GET_STATUS for this command.
+
+    -  ..
+
+       -  ``struct`` `audio_status`_ ``*status``
+
+       -  Returns the current state of Audio Device.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to return the current state of the
+Audio Device.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_GET_CAPABILITIES
+----------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_GET_CAPABILITIES
+
+.. code-block:: c
+
+	 int ioctl(int fd, int request = AUDIO_GET_CAPABILITIES,
+	 unsigned int *cap)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``AUDIO_GET_CAPABILITIES`` for this command.
+
+    -  ..
+
+       -  ``unsigned int *cap``
+
+       -  Returns a bit array of supported sound formats.
+          Bits are defined in `audio encodings`_.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to tell us about the decoding
+capabilities of the audio hardware.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_CLEAR_BUFFER
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_CLEAR_BUFFER
+
+.. code-block:: c
+
+	 int  ioctl(int fd, int request = AUDIO_CLEAR_BUFFER)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``AUDIO_CLEAR_BUFFER`` for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to clear all software and hardware
+buffers of the audio decoder device.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_SET_ID
+------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_SET_ID
+
+.. code-block:: c
+
+	 int  ioctl(int fd, int request = AUDIO_SET_ID, int id)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``AUDIO_SET_ID`` for this command.
+
+    -  ..
+
+       -  ``int id``
+
+       -  Audio sub-stream id.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl selects which sub-stream is to be decoded if a program or
+system stream is sent to the video device.
+
+If no audio stream type is set the id has to be in range [0xC0,0xDF]
+for MPEG sound, in [0x80,0x87] for AC3 and in [0xA0,0xA7] for LPCM.
+See ITU-T H.222.0 | ISO/IEC 13818-1 for further description.
+
+If the stream type is set with `AUDIO_SET_STREAMTYPE`_, specifies the
+id just the sub-stream id of the audio stream and only the first 5 bits
+(& 0x1F) are recognized.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_SET_MIXER
+---------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_SET_MIXER
+
+.. code-block:: c
+
+	 int ioctl(int fd, int request = AUDIO_SET_MIXER, audio_mixer_t *mix)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``AUDIO_SET_MIXER`` for this command.
+
+    -  ..
+
+       -  ``audio_mixer_t *mix``
+
+       -  Mixer settings.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl lets you adjust the mixer settings of the audio decoder.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_SET_STREAMTYPE
+--------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_SET_STREAMTYPE
+
+.. code-block:: c
+
+	 int  ioctl(fd, int request = AUDIO_SET_STREAMTYPE, int type)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``AUDIO_SET_STREAMTYPE`` for this command.
+
+    -  ..
+
+       -  ``int type``
+
+       -  Stream type.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl tells the driver which kind of audio stream to expect. This
+is useful if the stream offers several audio sub-streams like LPCM and
+AC3.
+
+Stream types defined in ITU-T H.222.0 | ISO/IEC 13818-1 are used.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``EINVAL``
+
+       -  Type is not a valid or supported stream type.
+
+
+-----
+
+
+AUDIO_BILINGUAL_CHANNEL_SELECT
+------------------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_BILINGUAL_CHANNEL_SELECT
+
+.. code-block:: c
+
+	 int ioctl(int fd, int request = AUDIO_BILINGUAL_CHANNEL_SELECT,
+	 audio_channel_select_t)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``AUDIO_BILINGUAL_CHANNEL_SELECT`` for this command.
+
+    -  ..
+
+       -  ``audio_channel_select_t ch``
+
+       -  Select the output format of the audio (mono left/right, stereo).
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl has been replaced by the V4L2
+``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK`` control
+for MPEG decoders controlled through V4L2.
+
+This ioctl call asks the Audio Device to select the requested channel
+for bilingual streams if possible.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+open()
+------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    #include <fcntl.h>
+
+.. c:function:: int  open(const char *deviceName, int flags)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``const char *deviceName``
+
+       -  Name of specific audio device.
+
+    -  ..
+
+       -  :rspan:`3` ``int flags``
+
+       -  :cspan:`1` A bit-wise OR of the following flags:
+
+    -  ..
+
+       -  ``O_RDONLY``
+
+       -  read-only access
+
+    -  ..
+
+       -  ``O_RDWR``
+
+       -  read/write access
+
+    -  ..
+
+       -  ``O_NONBLOCK``
+       -  | Open in non-blocking mode
+          | (blocking mode is the default)
+
+Description
+~~~~~~~~~~~
+
+This system call opens a named audio device (e.g.
+``/dev/dvb/adapter0/audio0``) for subsequent use. When an open() call has
+succeeded, the device will be ready for use. The significance of
+blocking or non-blocking mode is described in the documentation for
+functions where there is a difference. It does not affect the semantics
+of the open() call itself. A device opened in blocking mode can later be
+put into non-blocking mode (and vice versa) using the F_SETFL command
+of the fcntl system call. This is a standard system call, documented in
+the Linux manual page for fcntl. Only one user can open the Audio Device
+in O_RDWR mode. All other attempts to open the device in this mode will
+fail, and an error code will be returned. If the Audio Device is opened
+in O_RDONLY mode, the only ioctl call that can be used is
+`AUDIO_GET_STATUS`_. All other call will return with an error code.
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``ENODEV``
+
+       -  Device driver not loaded/available.
+
+    -  ..
+
+       -  ``EBUSY``
+
+       -  Device or resource busy.
+
+    -  ..
+
+       -  ``EINVAL``
+
+       -  Invalid argument.
+
+
+-----
+
+
+close()
+-------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: 	int close(int fd)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+Description
+~~~~~~~~~~~
+
+This system call closes a previously opened audio device.
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``EBADF``
+
+       -  Fd is not a valid open file descriptor.
+
+-----
+
+
+write()
+-------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	 size_t write(int fd, const void *buf, size_t count)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``void *buf``
+
+       -  Pointer to the buffer containing the PES data.
+
+    -  ..
+
+       -  ``size_t count``
+
+       -  Size of buf.
+
+Description
+~~~~~~~~~~~
+
+This system call can only be used if ``AUDIO_SOURCE_MEMORY`` is selected
+in the ioctl call `AUDIO_SELECT_SOURCE`_. The data provided shall be in
+PES format. If ``O_NONBLOCK`` is not specified the function will block
+until buffer space is available. The amount of data to be transferred is
+implied by count.
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``EPERM``
+
+       -  :cspan:`1` Mode ``AUDIO_SOURCE_MEMORY`` not selected.
+
+    -  ..
+
+       -  ``ENOMEM``
+
+       -  Attempted to write more data than the internal buffer can hold.
+
+    -  ..
+
+       -  ``EBADF``
+
+       -  Fd is not a valid open file descriptor.
--
2.34.0

[PATCH v3 5/6] Add documentation for video.h (data types)

[Stefan Herdler]

Add new documentation file for video.h
Step 1: data types only

Signed-off-by: Stefan Herdler <herdler@nurfuerspam.de>
---

Possibly left overs from DVD-API ? :
video_attributes_t
VIDEO_CAP_SPU
VIDEO_CAP_NAVI
VIDEO_CAP_CSS



>> +
>> +video_stream_source_t
>> +---------------------
>> +
>> +The video stream source is set through the `VIDEO_SELECT_SOURCE`_ call
>> +and can take the following values, depending on whether we are replaying
>> +from an internal (demuxer) or external (user write) source.
>> +
>> +
>> +.. code-block:: c
>> +
>> +    typedef enum {
>> +	VIDEO_SOURCE_DEMUX, /* Select the demux as the main source */
>> +	VIDEO_SOURCE_MEMORY /* If this source is selected, the stream
>> +		       comes from the user through the write
>> +		       system call */
>> +    } video_stream_source_t;
>
> FYI, this carries the same problem as the audio one: this API is problematic
> for modern hardware that has multiple tuners and demuxers. Setting up
> pipelines for audio and video decoding on modern hardware require a lot
> more than just demux/memory.

This kind of limitations are pretty well known for a while now, even to
normal users.
I remember some DVB-cards, where, due to hardware limitations, only a
fraction of the tuners can be active simultaneously.
The user had to chose the active tuners while loading the driver. Which is
definitely not a ideal solution, because changing the reception path
without reloading the driver isn't possible.
A real solution would be widely appreciated, I think.
Well, but back to topic ...


In case of the decoder we are are maybe lucky. One decoder with multiple
demuxers should theoretically already be possible without any changes.
The data fed to the decoder can be controlled by the PID filter output
selection DMX_OUT_DECODER.

There are existing multi tuner systems with one decoder controlled by this
API, but I don't know whether they do it this way or not.
A quick search wasn't very successful and at least the AV7110 should have
a hardware PID filter. More detailed research has to be done there.
However this topic is not directly part of the decoder API and I'm running
out of time, so I had to stop at this point.



 .../media/dvb/legacy_dvb_video.rst            | 798 ++++++++++++++++++
 1 file changed, 798 insertions(+)
 create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_video.rst

diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst
new file mode 100644
index 000000000000..165fd6005a07
--- /dev/null
+++ b/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst
@@ -0,0 +1,798 @@
+.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0
+
+.. c:namespace:: dtv.legacy.video
+
+.. _dvb_video:
+
+================
+DVB Video Device
+================
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+The DVB video device controls the MPEG2 video decoder of the DVB
+hardware. It can be accessed through ``/dev/dvb/adapter0/video0``. Data
+types and ioctl definitions can be accessed by including
+``linux/dvb/video.h`` in your application.
+
+Note that the DVB video device only controls decoding of the MPEG video
+stream, not its presentation on the TV or computer screen. On PCs this
+is typically handled by an associated video4linux device, e.g.
+``/dev/video``, which allows scaling and defining output windows.
+
+Most DVB cards don’t have their own MPEG decoder, which results in the
+omission of the audio and video device as well as the video4linux
+device.
+
+These ioctls were also used by V4L2 to control MPEG decoders implemented
+in V4L2. The use of these ioctls for that purpose has been made obsolete
+and proper V4L2 ioctls or controls have been created to replace that
+functionality. Use :ref:`V4L2 ioctls<video>` for new drivers!
+
+
+Video Data Types
+================
+
+
+
+video_format_t
+--------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    typedef enum {
+	VIDEO_FORMAT_4_3,
+	VIDEO_FORMAT_16_9,
+	VIDEO_FORMAT_221_1
+    } video_format_t;
+
+Constants
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``VIDEO_FORMAT_4_3``
+
+       -  Select 4:3 format.
+
+    -  ..
+
+       -  ``VIDEO_FORMAT_16_9``
+
+       -  Select 16:9 format.
+
+    -  ..
+
+       -  ``VIDEO_FORMAT_221_1``
+
+       -  Select 2.21:1 format.
+
+Description
+~~~~~~~~~~~
+
+The ``video_format_t`` data type
+is used in the `VIDEO_SET_FORMAT`_ function to tell the driver which
+aspect ratio the output hardware (e.g. TV) has. It is also used in the
+data structures `video_status`_ returned by `VIDEO_GET_STATUS`_
+and `video_event`_ returned by `VIDEO_GET_EVENT`_ which report
+about the display format of the current video stream.
+
+
+-----
+
+
+video_displayformat_t
+---------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    typedef enum {
+	VIDEO_PAN_SCAN,
+	VIDEO_LETTER_BOX,
+	VIDEO_CENTER_CUT_OUT
+    } video_displayformat_t;
+
+Constants
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``VIDEO_PAN_SCAN``
+
+       -  Use pan and scan format.
+
+    -  ..
+
+       -  ``VIDEO_LETTER_BOX``
+
+       -  Use letterbox format.
+
+    -  ..
+
+       -  ``VIDEO_CENTER_CUT_OUT``
+
+       -  Use center cut out format.
+
+Description
+~~~~~~~~~~~
+
+In case the display format of the video stream and of the display
+hardware differ the application has to specify how to handle the
+cropping of the picture. This can be done using the
+`VIDEO_SET_DISPLAY_FORMAT`_ call which accepts this enum as argument.
+
+
+-----
+
+
+video_size_t
+------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    typedef struct {
+	int w;
+	int h;
+	video_format_t aspect_ratio;
+    } video_size_t;
+
+Variables
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int w``
+
+       -  Video width in pixels.
+
+    -  ..
+
+       -  ``int h``
+
+       -  Video height in pixels.
+
+    -  ..
+
+       -  `video_format_t`_ ``aspect_ratio``
+
+       -  Aspect ratio.
+
+Description
+~~~~~~~~~~~
+
+Used in the struct `video_event`_. It stores the resolution and
+aspect ratio of the video.
+
+
+-----
+
+
+video_stream_source_t
+---------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    typedef enum {
+	VIDEO_SOURCE_DEMUX,
+	VIDEO_SOURCE_MEMORY
+    } video_stream_source_t;
+
+Constants
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``VIDEO_SOURCE_DEMUX``
+
+       -  :cspan:`1` Select the demux as the main source.
+
+    -  ..
+
+       -  ``VIDEO_SOURCE_MEMORY``
+
+       -  If this source is selected, the stream
+          comes from the user through the write
+          system call.
+
+Description
+~~~~~~~~~~~
+
+The video stream source is set through the `VIDEO_SELECT_SOURCE`_ call
+and can take the following values, depending on whether we are replaying
+from an internal (demuxer) or external (user write) source.
+VIDEO_SOURCE_DEMUX selects the demultiplexer (fed either by the
+frontend or the DVR device) as the source of the video stream. If
+VIDEO_SOURCE_MEMORY is selected the stream comes from the application
+through the `write()`_ system call.
+
+
+-----
+
+
+video_play_state_t
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    typedef enum {
+	VIDEO_STOPPED,
+	VIDEO_PLAYING,
+	VIDEO_FREEZED
+    } video_play_state_t;
+
+Constants
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``VIDEO_STOPPED``
+
+       -  Video is stopped.
+
+    -  ..
+
+       -  ``VIDEO_PLAYING``
+
+       -  Video is currently playing.
+
+    -  ..
+
+       -  ``VIDEO_FREEZED``
+
+       -  Video is frozen.
+
+Description
+~~~~~~~~~~~
+
+This values can be returned by the `VIDEO_GET_STATUS`_ call
+representing the state of video playback.
+
+
+-----
+
+
+struct video_command
+--------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    struct video_command {
+	__u32 cmd;
+	__u32 flags;
+	union {
+	    struct {
+		__u64 pts;
+	    } stop;
+
+	    struct {
+		__s32 speed;
+		__u32 format;
+	    } play;
+
+	    struct {
+		__u32 data[16];
+	    } raw;
+	};
+    };
+
+
+Variables
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``__u32 cmd``
+
+       -  `Decoder command`_
+
+    -  ..
+
+       -  ``__u32 flags``
+
+       -  Flags for the `Decoder command`_.
+
+    -  ..
+
+       -  ``struct stop``
+
+       -  ``__u64 pts``
+
+       -  MPEG PTS
+
+    -  ..
+
+       -  :rspan:`5` ``stuct play``
+
+       -  :rspan:`4` ``__s32 speed``
+
+       -   0 or 1000 specifies normal speed,
+
+    -  ..
+
+       -   1:  specifies forward single stepping,
+
+    -  ..
+
+       -   -1: specifies backward single stepping,
+
+    -  ..
+
+       -   >1: playback at speed / 1000 of the normal speed
+
+    -  ..
+
+       -   <-1: reverse playback at ( -speed / 1000 ) of the normal speed.
+
+    -  ..
+
+       -  ``__u32 format``
+
+       -  `Play input formats`_
+
+    -  ..
+
+       -  ``__u32 data[16]``
+
+       -  Reserved
+
+Description
+~~~~~~~~~~~
+
+The structure must be zeroed before use by the application. This ensures
+it can be extended safely in the future.
+
+
+-----
+
+
+Predefined decoder commands and flags
+-------------------------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    #define VIDEO_CMD_PLAY                      (0)
+    #define VIDEO_CMD_STOP                      (1)
+    #define VIDEO_CMD_FREEZE                    (2)
+    #define VIDEO_CMD_CONTINUE                  (3)
+
+    #define VIDEO_CMD_FREEZE_TO_BLACK      (1 << 0)
+
+    #define VIDEO_CMD_STOP_TO_BLACK        (1 << 0)
+    #define VIDEO_CMD_STOP_IMMEDIATELY     (1 << 1)
+
+    #define VIDEO_PLAY_FMT_NONE                 (0)
+    #define VIDEO_PLAY_FMT_GOP                  (1)
+
+    #define VIDEO_VSYNC_FIELD_UNKNOWN           (0)
+    #define VIDEO_VSYNC_FIELD_ODD               (1)
+    #define VIDEO_VSYNC_FIELD_EVEN              (2)
+    #define VIDEO_VSYNC_FIELD_PROGRESSIVE       (3)
+
+Constants
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  :rspan:`3` _`Decoder command`
+
+       -  ``VIDEO_CMD_PLAY``
+
+       -  Start playback.
+
+    -  ..
+
+       -  ``VIDEO_CMD_STOP``
+
+       -  Stop playback.
+
+    -  ..
+
+       -  ``VIDEO_CMD_FREEZE``
+
+       -  Freeze playback.
+
+    -  ..
+
+       -  ``VIDEO_CMD_CONTINUE``
+
+       -  Continue playback after freeze.
+
+    -  ..
+
+       -  Flags for ``VIDEO_CMD_FREEZE``
+
+       -  ``VIDEO_CMD_FREEZE_TO_BLACK``
+
+       -  Show black picture on freeze.
+
+    -  ..
+
+       -  :rspan:`1` Flags for ``VIDEO_CMD_STOP``
+
+       -  ``VIDEO_CMD_STOP_TO_BLACK``
+
+       -  Show black picture on stop.
+
+    -  ..
+
+       -  ``VIDEO_CMD_STOP_IMMEDIATELY``
+
+       -  Stop immediately, without emptying buffers.
+
+    -  ..
+
+       -  :rspan:`1` _`Play input formats`
+
+       -  ``VIDEO_PLAY_FMT_NONE``
+
+       -  The decoder has no special format requirements
+
+    -  ..
+
+       -  ``VIDEO_PLAY_FMT_GOP``
+
+       -  The decoder requires full GOPs
+
+    -  ..
+
+       -  :rspan:`3` Field order
+
+       -  ``VIDEO_VSYNC_FIELD_UNKNOWN``
+
+       -  FIELD_UNKNOWN can be used if the hardware does not know
+          whether the Vsync is for an odd, even or progressive
+          (i.e. non-interlaced) field.
+
+    -  ..
+
+       -  ``VIDEO_VSYNC_FIELD_ODD``
+
+       -  Vsync is for an odd field.
+
+    -  ..
+
+       -  ``VIDEO_VSYNC_FIELD_EVEN``
+
+       -  Vsync is for an even field.
+
+    -  ..
+
+       -  ``VIDEO_VSYNC_FIELD_PROGRESSIVE``
+
+       -  progressive (i.e. non-interlaced)
+
+
+-----
+
+
+video_event
+-----------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    struct video_event {
+	__s32 type;
+    #define VIDEO_EVENT_SIZE_CHANGED        1
+    #define VIDEO_EVENT_FRAME_RATE_CHANGED  2
+    #define VIDEO_EVENT_DECODER_STOPPED     3
+    #define VIDEO_EVENT_VSYNC               4
+	long timestamp;
+	union {
+	    video_size_t size;
+	    unsigned int frame_rate;
+	    unsigned char vsync_field;
+	} u;
+    };
+
+Variables
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  :rspan:`4` ``__s32 type``
+
+       -  :cspan:`1` Event type.
+
+    -  ..
+
+       -  ``VIDEO_EVENT_SIZE_CHANGED``
+
+       -  Size changed.
+
+    -  ..
+
+       -  ``VIDEO_EVENT_FRAME_RATE_CHANGED``
+
+       -  Framerate changed.
+
+    -  ..
+
+       -  ``VIDEO_EVENT_DECODER_STOPPED``
+
+       -  Decoder stopped.
+
+    -  ..
+
+       -  ``VIDEO_EVENT_VSYNC``
+
+       -  Vsync occurred.
+
+    -  ..
+
+       -  ``long timestamp``
+
+       -  :cspan:`1` MPEG PTS at occurrence.
+
+    -  ..
+
+       -  :rspan:`2` ``union u``
+
+       -  `video_size_t`_ size
+
+       -  Resolution and aspect ratio of the video.
+
+    -  ..
+
+       -  ``unsigned int frame_rate``
+
+       -  in frames per 1000sec
+
+    -  ..
+
+       -  ``unsigned char vsync_field``
+
+       -  | unknown / odd / even / progressive
+          | See: `Predefined decoder commands and flags`_
+
+Description
+~~~~~~~~~~~
+
+This is the structure of a video event as it is returned by the
+`VIDEO_GET_EVENT`_ call. See there for more details.
+
+
+-----
+
+
+video_status
+------------
+
+Synopsis
+~~~~~~~~
+
+The `VIDEO_GET_STATUS`_ call returns the following structure informing
+about various states of the playback operation.
+
+.. code-block:: c
+
+    struct video_status {
+	int                    video_blank;
+	video_play_state_t     play_state;
+	video_stream_source_t  stream_source;
+	video_format_t         video_format;
+	video_displayformat_t  display_format;
+    };
+
+Variables
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  :rspan:`2` ``int video_blank``
+
+       -  :cspan:`1` Show blank video on freeze?
+
+    -  ..
+
+       -  TRUE  ( != 0 )
+
+       -  Blank screen when freeze.
+
+    -  ..
+
+       -  FALSE ( == 0 )
+
+       -  Show last decoded frame.
+
+    -  ..
+
+       -  `video_play_state_t`_ ``play_state``
+
+       -  Current state of playback.
+
+    -  ..
+
+       -  `video_stream_source_t`_ ``stream_source``
+
+       -  Current source (demux/memory).
+
+    -  ..
+
+       -  `video_format_t`_ ``video_format``
+
+       -  Current aspect ratio of stream.
+
+    -  ..
+
+       -  `video_displayformat_t`_ ``display_format``
+
+       -  Applied cropping mode.
+
+Description
+~~~~~~~~~~~
+
+If ``video_blank`` is set ``TRUE`` video will be blanked out if the
+channel is changed or if playback is stopped. Otherwise, the last picture
+will be displayed. ``play_state`` indicates if the video is currently
+frozen, stopped, or being played back. The ``stream_source`` corresponds
+to the selected source for the video stream. It can come either from the
+demultiplexer or from memory. The ``video_format`` indicates the aspect
+ratio (one of 4:3 or 16:9) of the currently played video stream.
+Finally, ``display_format`` corresponds to the applied cropping mode in
+case the source video format is not the same as the format of the output
+device.
+
+
+-----
+
+
+video_still_picture
+-------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    struct video_still_picture {
+    char *iFrame;
+    int32_t size;
+    };
+
+Variables
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``char *iFrame``
+
+       -  Pointer to a single iframe in memory.
+
+    -  ..
+
+       -  ``int32_t size``
+
+       -  Size of the iframe.
+
+
+Description
+~~~~~~~~~~~
+
+An I-frame displayed via the `VIDEO_STILLPICTURE`_ call is passed on
+within this structure.
+
+
+-----
+
+
+video capabilities
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    #define VIDEO_CAP_MPEG1   1
+    #define VIDEO_CAP_MPEG2   2
+    #define VIDEO_CAP_SYS     4
+    #define VIDEO_CAP_PROG    8
+
+Constants
+~~~~~~~~~
+Bit definitions for capabilities:
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``VIDEO_CAP_MPEG1``
+
+       -  :cspan:`1` The hardware can decode MPEG1.
+
+    -  ..
+
+       -  ``VIDEO_CAP_MPEG2``
+
+       -  The hardware can decode MPEG2.
+
+    -  ..
+
+       -  ``VIDEO_CAP_SYS``
+
+       -  The video device accepts system stream.
+
+          You still have to open the video and the audio device
+          but only send the stream to the video device.
+
+    -  ..
+
+       -  ``VIDEO_CAP_PROG``
+
+       -  The video device accepts program stream.
+
+          You still have to open the video and the audio device
+          but only send the stream to the video device.
+
+Description
+~~~~~~~~~~~
+
+A call to `VIDEO_GET_CAPABILITIES`_ returns an unsigned integer with the
+following bits set according to the hardware's capabilities.
--
2.34.0

[PATCH v3 6/6] Add documentation for video.h (function calls)

[Stefan Herdler]

Step 2: Add documentation for function calls.

Signed-off-by: Stefan Herdler <herdler@nurfuerspam.de>
---

Possibly unused:
struct video_command
ioctl VIDEO_COMMAND
ioctl VIDEO_TRY_COMMAND
ioctl VIDEO_GET_FRAME_COUNT

Out of tree only usage:
VIDEO_SET_STREAMTYPE



VIDEO_COMMAND:
False positive on AV7110 driver. The driver uses identical symbol names.

The ioctl VIDEO_COMMAND has been introduced 2007 way after the AV7110
driver.
The log says it has been added to support the cx23415 decoder and has
probably never used for enything else.
And AFAIK has the cx23415 decoder been switched to V4L2-API some time ago.



VIDEO_SET_STREAMTYPE:
Used by the "Enigma2" set top boxes only.
Stream type definitions are from there.



>> +VIDEO_GET_EVENT
>> +---------------
[...]
> Same comments as I did for demux event applies here: what happens if
> userspace misses the event?
>
> Btw, this explanation is a lot better than the one at demux. You
> should probably place something like that there too... there is
> block/nonblock mode for the demux event? Do they behave the same?

I'm a little confused here, a demux event doesn't seem to exist any more.
Are you referring to the legacy "dvb_frontend_event"?

I could place some documentation there, but I'm not sure, if it really
applies there too.
Anyway, I have to take a closer look before, but I would like to finish
this files first ;-).



 .../media/dvb/legacy_dvb_video.rst            | 1632 +++++++++++++++++
 1 file changed, 1632 insertions(+)

diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst
index 165fd6005a07..918ef3f84f72 100644
--- a/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst
+++ b/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst
@@ -796,3 +796,1635 @@ Description

 A call to `VIDEO_GET_CAPABILITIES`_ returns an unsigned integer with the
 following bits set according to the hardware's capabilities.
+
+
+-----
+
+
+Video Function Calls
+====================
+
+
+VIDEO_STOP
+----------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_STOP
+
+.. code-block:: c
+
+	int ioctl(fd, VIDEO_STOP, int mode)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  :cspan:`1` Equals ``VIDEO_STOP`` for this command.
+
+    -  ..
+
+       -  :rspan:`2` ``int mode``
+
+       -  :cspan:`1` Indicates how the screen shall be handled.
+
+    -  ..
+
+       -  TRUE  ( != 0 )
+
+       -  Blank screen when stop.
+
+    -  ..
+
+       -  FALSE ( == 0 )
+
+       -  Show last decoded frame.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for Digital TV devices only. To control a V4L2 decoder use
+the V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
+
+This ioctl call asks the Video Device to stop playing the current
+stream. Depending on the input parameter, the screen can be blanked out
+or displaying the last decoded frame.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_PLAY
+----------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_PLAY
+
+.. code-block:: c
+
+	int ioctl(fd, VIDEO_PLAY)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_PLAY`` for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for Digital TV devices only. To control a V4L2 decoder use
+the V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
+
+This ioctl call asks the Video Device to start playing a video stream
+from the selected source.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_FREEZE
+------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_FREEZE
+
+.. code-block:: c
+
+	int ioctl(fd, VIDEO_FREEZE)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_FREEZE`` for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for Digital TV devices only. To control a V4L2 decoder use
+the V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
+
+This ioctl call suspends the live video stream being played, if
+VIDEO_SOURCE_DEMUX is selected. Decoding and playing are frozen.
+It is then possible to restart the decoding and playing process of the
+video stream using the `VIDEO_CONTINUE`_ command.
+If VIDEO_SOURCE_MEMORY is selected in the ioctl call
+`VIDEO_SELECT_SOURCE`_, the Digital TV subsystem will not decode any more
+data until the ioctl call `VIDEO_CONTINUE`_ or `VIDEO_PLAY`_ is performed.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_CONTINUE
+--------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_CONTINUE
+
+.. code-block:: c
+
+	int ioctl(fd, VIDEO_CONTINUE)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_CONTINUE`` for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for Digital TV devices only. To control a V4L2 decoder use
+the V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
+
+This ioctl call restarts decoding and playing processes of the video
+stream which was played before a call to `VIDEO_FREEZE`_ was made.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_SELECT_SOURCE
+-------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_SELECT_SOURCE
+
+.. code-block:: c
+
+	int ioctl(fd, VIDEO_SELECT_SOURCE, video_stream_source_t source)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_SELECT_SOURCE`` for this command.
+
+    -  ..
+
+       -  `video_stream_source_t`_ ``source``
+
+       -  Indicates which source shall be used for the Video stream.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for Digital TV devices only. This ioctl was also supported
+by the V4L2 ivtv driver, but that has been replaced by the ivtv-specific
+``IVTV_IOC_PASSTHROUGH_MODE`` ioctl.
+
+This ioctl call informs the video device which source shall be used for
+the input data. The possible sources are demux or memory. If memory is
+selected, the data is fed to the video device through the write command
+using the struct `video_stream_source_t`_. If demux is selected, the data
+is directly transferred from the onboard demux-device to the decoder.
+
+The data fed to the decoder is also controlled by the PID-filter.
+Output selection: :c:enum:`dmx_output` ``DMX_OUT_DECODER``.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_SET_BLANK
+---------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_SET_BLANK
+
+.. code-block:: c
+
+	int ioctl(fd, VIDEO_SET_BLANK, int mode)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  :cspan:`1` Equals ``VIDEO_SET_BLANK`` for this command.
+
+    -  ..
+
+       -  :rspan:`2` ``int mode``
+
+       -  :cspan:`1` Indicates if the screen shall be blanked.
+
+    -  ..
+
+       -  TRUE  ( != 0 )
+
+       -  Blank screen when stop.
+
+    -  ..
+
+       -  FALSE ( == 0 )
+
+       -  Show last decoded frame.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Video Device to blank out the picture.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_GET_STATUS
+----------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_GET_STATUS
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_GET_STATUS,
+	struct video_status *status)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_GET_STATUS`` for this command.
+
+    -  ..
+
+       -  ``struct`` `video_status`_ ``*status``
+
+       -  Returns the current status of the Video Device.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Video Device to return the current status of
+the device.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_GET_EVENT
+---------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_GET_EVENT
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_GET_EVENT,
+	struct video_event *ev)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_GET_EVENT`` for this command.
+
+    -  ..
+
+       -  ``struct`` `video_event`_ ``*ev``
+
+       -  Points to the location where the event, if any, is to be stored.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for DVB devices only. To get events from a V4L2 decoder
+use the V4L2 :ref:`VIDIOC_DQEVENT` ioctl instead.
+
+This ioctl call returns an event of type `video_event`_ if available. A
+certain number of the latest events will be cued and returned in order of
+occurrence. Older events may be discarded if not fetched in time. If
+an event is not available, the behavior depends on whether the device is
+in blocking or non-blocking mode. In the latter case, the call fails
+immediately with errno set to ``EWOULDBLOCK``. In the former case, the
+call blocks until an event becomes available. The standard Linux poll()
+and/or select() system calls can be used with the device file descriptor
+to watch for new events. For select(), the file descriptor should be
+included in the exceptfds argument, and for poll(), POLLPRI should be
+specified as the wake-up condition. Read-only permissions are sufficient
+for this ioctl call.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``EWOULDBLOCK``
+
+       -  :cspan:`1` There is no event pending, and the device is in
+          non-blocking mode.
+
+    -  ..
+
+       -  ``EOVERFLOW``
+
+       -  Overflow in event queue - one or more events were lost.
+
+
+-----
+
+
+VIDEO_SET_DISPLAY_FORMAT
+------------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_SET_DISPLAY_FORMAT
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_SET_DISPLAY_FORMAT,
+	video_display_format_t format)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_SET_DISPLAY_FORMAT`` for this command.
+
+    -  ..
+
+       -  `video_displayformat_t`_ ``format``
+
+       -  Selects the video format to be used.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Video Device to select the video format to be
+applied by the MPEG chip on the video.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_STILLPICTURE
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_STILLPICTURE
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_STILLPICTURE,
+	struct video_still_picture *sp)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_STILLPICTURE`` for this command.
+
+    -  ..
+
+       -  ``struct`` `video_still_picture`_ ``*sp``
+
+       -  Pointer to the location where the struct with the I-frame
+          and size is stored.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Video Device to display a still picture
+(I-frame). The input data shall be the section of an elementary video
+stream containing an I-frame. Typically this section is extracted from a
+TS or PES recording. Resolution and codec (see `video capabilities`_) must
+be supported by the device. If the pointer is NULL, then the current
+displayed still picture is blanked.
+
+e.g. The AV7110 supports MPEG1 and MPEG2 with the common PAL-SD
+resolutions.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_FAST_FORWARD
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_FAST_FORWARD
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_FAST_FORWARD, int nFrames)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_FAST_FORWARD`` for this command.
+
+    -  ..
+
+       -  ``int nFrames``
+
+       -  The number of frames to skip.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Video Device to skip decoding of N number of
+I-frames. This call can only be used if ``VIDEO_SOURCE_MEMORY`` is
+selected.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``EPERM``
+
+       -  Mode ``VIDEO_SOURCE_MEMORY`` not selected.
+
+
+-----
+
+
+VIDEO_SLOWMOTION
+----------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_SLOWMOTION
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_SLOWMOTION, int nFrames)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_SLOWMOTION`` for this command.
+
+    -  ..
+
+       -  ``int nFrames``
+
+       -  The number of times to repeat each frame.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the video device to repeat decoding frames N number
+of times. This call can only be used if ``VIDEO_SOURCE_MEMORY`` is
+selected.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``EPERM``
+
+       -  Mode ``VIDEO_SOURCE_MEMORY`` not selected.
+
+
+-----
+
+
+VIDEO_GET_CAPABILITIES
+----------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_GET_CAPABILITIES
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_GET_CAPABILITIES, unsigned int *cap)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_GET_CAPABILITIES`` for this command.
+
+    -  ..
+
+       -  ``unsigned int *cap``
+
+       -  Pointer to a location where to store the capability information.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the video device about its decoding capabilities.
+On success it returns an integer which has bits set according to the
+defines in `video capabilities`_.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_CLEAR_BUFFER
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_CLEAR_BUFFER
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_CLEAR_BUFFER)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_CLEAR_BUFFER`` for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call clears all video buffers in the driver and in the
+decoder hardware.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_SET_STREAMTYPE
+--------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_SET_STREAMTYPE
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_SET_STREAMTYPE, int type)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_SET_STREAMTYPE`` for this command.
+
+    -  ..
+
+       -  ``int type``
+
+       -  Stream type.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl tells the driver which kind of stream to expect being written
+to it.
+Intelligent decoder might also not support or ignore (like the AV7110)
+this call and determine the stream type themselves.
+
+Currently used stream types:
+
+.. flat-table::
+    :header-rows:  1
+    :stub-columns: 0
+
+    -  ..
+
+       -  Codec
+
+       -  Stream type
+
+    -  ..
+
+       -  MPEG2
+
+       -  0
+
+    -  ..
+
+       -  MPEG4 h.264
+
+       -  1
+
+    -  ..
+
+       -  VC1
+
+       -  3
+
+    -  ..
+
+       -  MPEG4 Part2
+
+       -  4
+
+    -  ..
+
+       -  VC1 SM
+
+       -  5
+
+    -  ..
+
+       -  MPEG1
+
+       -  6
+
+    -  ..
+
+       -  HEVC h.265
+
+       -  | 7
+          | DREAMBOX: 22
+
+    -  ..
+
+       -  AVS
+
+       -  16
+
+    -  ..
+
+       -  AVS2
+
+       -  40
+
+Not every decoder supports all stream types.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_SET_FORMAT
+----------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_SET_FORMAT
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_SET_FORMAT, video_format_t format)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_SET_FORMAT`` for this command.
+
+    -  ..
+
+       -  `video_format_t`_ ``format``
+
+       -  Video format of TV as defined in section `video_format_t`_.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl sets the screen format (aspect ratio) of the connected output
+device (TV) so that the output of the decoder can be adjusted
+accordingly.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_GET_SIZE
+--------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_GET_SIZE
+
+.. code-block:: c
+
+	int ioctl(int fd, int request = VIDEO_GET_SIZE, video_size_t *size)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call,
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_GET_SIZE`` for this command.
+
+    -  ..
+
+       -  `video_size_t`_ ``*size``
+
+       -  Returns the size and aspect ratio.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl returns the size and aspect ratio.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_GET_PTS
+-------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_GET_PTS
+
+.. code-block:: c
+
+	int ioctl(int fd, int request = VIDEO_GET_PTS, __u64 *pts)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_GET_PTS`` for this command.
+
+    -  ..
+
+       -  ``__u64 *pts``
+
+       -  Returns the 33-bit timestamp as defined in ITU T-REC-H.222.0 /
+          ISO/IEC 13818-1.
+
+          The PTS should belong to the currently played frame if possible,
+          but may also be a value close to it like the PTS of the last
+          decoded frame or the last PTS extracted by the PES parser.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+For V4L2 decoders this ioctl has been replaced by the
+``V4L2_CID_MPEG_VIDEO_DEC_PTS`` control.
+
+This ioctl call asks the Video Device to return the current PTS
+timestamp.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_GET_FRAME_COUNT
+---------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_GET_FRAME_COUNT
+
+.. code-block:: c
+
+	int ioctl(int fd, VIDEO_GET_FRAME_COUNT, __u64 *pts)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_GET_FRAME_COUNT`` for this command.
+
+    -  ..
+
+       -  ``__u64 *pts``
+
+       -  Returns the number of frames displayed since the decoder was
+          started.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+For V4L2 decoders this ioctl has been replaced by the
+``V4L2_CID_MPEG_VIDEO_DEC_FRAME`` control.
+
+This ioctl call asks the Video Device to return the number of displayed
+frames since the decoder was started.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_COMMAND
+-------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_COMMAND
+
+.. code-block:: c
+
+	int ioctl(int fd, int request = VIDEO_COMMAND,
+	struct video_command *cmd)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_COMMAND`` for this command.
+
+    -  ..
+
+       -  `struct video_command`_ ``*cmd``
+
+       -  Commands the decoder.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+For V4L2 decoders this ioctl has been replaced by the
+:ref:`VIDIOC_DECODER_CMD` ioctl.
+
+This ioctl commands the decoder. The `struct video_command`_ is a
+subset of the ``v4l2_decoder_cmd`` struct, so refer to the
+:ref:`VIDIOC_DECODER_CMD` documentation for
+more information.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_TRY_COMMAND
+-----------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_TRY_COMMAND
+
+.. code-block:: c
+
+	int ioctl(int fd, int request = VIDEO_TRY_COMMAND,
+	struct video_command *cmd)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_TRY_COMMAND`` for this command.
+
+    -  ..
+
+       -  `struct video_command`_ ``*cmd``
+
+       -  Try a decoder command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+For V4L2 decoders this ioctl has been replaced by the
+:ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` ioctl.
+
+This ioctl tries a decoder command. The `struct video_command`_ is a
+subset of the ``v4l2_decoder_cmd`` struct, so refer to the
+:ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` documentation
+for more information.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+open()
+------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    #include <fcntl.h>
+
+.. c:function:: 	int open(const char *deviceName, int flags)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``const char *deviceName``
+
+       -  Name of specific video device.
+
+    -  ..
+
+       -  :rspan:`3` ``int flags``
+
+       -  :cspan:`1` A bit-wise OR of the following flags:
+
+    -  ..
+
+       -  ``O_RDONLY``
+
+       -  read-only access
+
+    -  ..
+
+       -  ``O_RDWR``
+
+       -  read/write access
+
+    -  ..
+
+       -  ``O_NONBLOCK``
+       -  | Open in non-blocking mode
+          | (blocking mode is the default)
+
+Description
+~~~~~~~~~~~
+
+This system call opens a named video device (e.g.
+/dev/dvb/adapter?/video?) for subsequent use.
+
+When an open() call has succeeded, the device will be ready for use. The
+significance of blocking or non-blocking mode is described in the
+documentation for functions where there is a difference. It does not
+affect the semantics of the open() call itself. A device opened in
+blocking mode can later be put into non-blocking mode (and vice versa)
+using the F_SETFL command of the fcntl system call. This is a standard
+system call, documented in the Linux manual page for fcntl. Only one
+user can open the Video Device in O_RDWR mode. All other attempts to
+open the device in this mode will fail, and an error-code will be
+returned. If the Video Device is opened in O_RDONLY mode, the only
+ioctl call that can be used is `VIDEO_GET_STATUS`_. All other call will
+return an error code.
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``ENODEV``
+
+       -  :cspan:`1` Device driver not loaded/available.
+
+    -  ..
+
+       -  ``EINTERNAL``
+
+       -  Internal error.
+
+    -  ..
+
+       -  ``EBUSY``
+
+       -  Device or resource busy.
+
+    -  ..
+
+       -  ``EINVAL``
+
+       -  Invalid argument.
+
+
+-----
+
+
+close()
+-------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: 	int close(int fd)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+Description
+~~~~~~~~~~~
+
+This system call closes a previously opened video device.
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``EBADF``
+
+       -  fd is not a valid open file descriptor.
+
+
+-----
+
+
+write()
+-------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: size_t write(int fd, const void *buf, size_t count)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``void *buf``
+
+       -  Pointer to the buffer containing the PES data.
+
+    -  ..
+
+       -  ``size_t count``
+
+       -  Size of buf.
+
+Description
+~~~~~~~~~~~
+
+This system call can only be used if VIDEO_SOURCE_MEMORY is selected
+in the ioctl call `VIDEO_SELECT_SOURCE`_. The data provided shall be in
+PES format, unless the capability allows other formats. TS is the
+most common format for storing DVB-data, it is usually supported too.
+If O_NONBLOCK is not specified the function will block until buffer space
+is available. The amount of data to be transferred is implied by count.
+
+.. note:: See: :ref:`DVB Data Formats <legacy_dvb_decoder_formats>`
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``EPERM``
+
+       -  :cspan:`1` Mode ``VIDEO_SOURCE_MEMORY`` not selected.
+
+    -  ..
+
+       -  ``ENOMEM``
+
+       -  Attempted to write more data than the internal buffer can hold.
+
+    -  ..
+
+       -  ``EBADF``
+
+       -  fd is not a valid open file descriptor.
--
2.34.0

Re: [PATCH v3 3/6] Add documentation for audio.h (data types)

[kernel test robot]

Hi Stefan,

kernel test robot noticed the following build warnings:

[auto build test WARNING on media-tree/master]
[also build test WARNING on linus/master v6.5-rc2 next-20230719]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]

url:    https://github.com/intel-lab-lkp/linux/commits/Stefan-Herdler/Add-documentation-for-legacy-DVB-decoder-API/20230718-174209
base:   git://linuxtv.org/media_tree.git master
patch link:    https://lore.kernel.org/r/20230717020446.28877-4-herdler%40nurfuerspam.de
patch subject: [PATCH v3 3/6] Add documentation for audio.h (data types)
reproduce: (https://download.01.org/0day-ci/archive/20230719/202307191616.jdo5lLxc-lkp@intel.com/reproduce)

If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/oe-kbuild-all/202307191616.jdo5lLxc-lkp@intel.com/

All warnings (new ones prefixed by >>):

>> Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst:80: WARNING: Unknown interpreted text role "c:enum".

vim +80 Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst

  > 80	

-- 
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki

[PATCH v4 0/6] media: docs: uAPI: dvb/decoder: completing the documentation

[Stefan Herdler]

This is basically a resend of v3 after 6 month, with some minor updates.
Changes since v3:
* Adjust title and description to better match existing documentation.
* Fix warnings from kernel test robot.
  (At least I hope it is fixed now, I couldn't reproduce this warning.)

No changes to the text it self.
The layout is still identical since v1, just split into multiple patches.
My comments of v3 attached below, they refer to Mauros comments[3] to
v2 and still fully apply.

[3: https://patchwork.kernel.org/project/linux-media/patch/decd5d71-f06e-5873-5ebf-7028107f65ee@nurfuerspam.de/]


[PATCH v3] (July '23) ---------------------------------------------------

Changes since v2:
* Split the patch into a patch series.
* Incorporate the changes requested.
* Style updates to better match the existing documentation.
* And a lot of small fixes.


Hi Mauro,

it took a little longer then expected, but I didn't had much time in spare
for this. I'm pretty much occupied by other things at the moment.
The winter season would be better for things like this, but I try to
finish it as quick as possible.

I went through your mail point by point and I'm confident, that I was able
to sort out your questions now. At least I don't see anything that need to
be improved anymore.
The work has been done in a lot of small blocks over a pretty long period
after my daily work, mostly late at night. Despite double checking
everything, I maybe still have missed something. I hope it is not too
much.

For usage it has been checked against the known projects using the DVB
decoder APIs:
* The AV7110 kernel driver.
* The out of tree driver for the HD full featured cards.[1]
* The "Enigma2" sources from openatv team.[2]
  (The drivers of the boxes are binary only.)

Possibly unused items have been listed in the comment of the patches.
Please take this lists with a pinch of salt. With the number of items
checked, it is pretty easy to miss an occurrence or have a false positive.
Although I've done my best, there is still the chance that I've missed an
use case.

I tried to complete the documentation of this unused definition too.
Most information had been collect anyway and writing it down wasn't that
much of effort.

Removing the definition and documentation later at once is always an
option.
I would prefer to do it this way, if something has to be removed.
It is easier to revert the change in case of a regression.
If necessary I can provide the patches too.

Regards
Stefan

[1: https://github.com/s-moch/linux-saa716x]
[2: https://github.com/openatv/enigma2/tree/master]



Stefan Herdler (6):
  Add documentation for legacy DVB decoder API
  Add documentation for osd.h
  Add documentation for audio.h (data types)
  Add documentation for audio.h (function calls)
  Add documentation for video.h (data types)
  Add documentation for video.h (function calls)

 .../media/dvb/legacy_dvb_apis.rst             |    1 +
 .../media/dvb/legacy_dvb_audio.rst            | 1642 +++++++++++
 .../media/dvb/legacy_dvb_decoder_api.rst      |   61 +
 .../media/dvb/legacy_dvb_osd.rst              |  883 ++++++
 .../media/dvb/legacy_dvb_video.rst            | 2430 +++++++++++++++++
 5 files changed, 5017 insertions(+)
 create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst
 create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst
 create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst
 create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_video.rst

--
2.34.0

[PATCH v4 1/6] media: docs: uAPI: dvb/decoder: completing the documentation

[Stefan Herdler]

The existing documentation of the legacy DVB Decoder API was incomplete.

Revising the documentation, adding missing parts and arranging the
documentation files new.

This patch contains the new index file and links to it.

Signed-off-by: Stefan Herdler <herdler@nurfuerspam.de>
---

Changes since v3:
* Adjust title and description to better match existing documentation.


[PATCH v3] ------------------------------------------------------------


>> +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
>
> Please place it dual licensed with GFDL and GPL 2.0.

Changed to GFDL OR GPL-2.0 like in "media/glossary.rst".

GPL 2.0 is fine for me too, but the old documentation, my work is based on, was GFDL.
Can we just change the license?
That's not mine to judge.



 .../media/dvb/legacy_dvb_apis.rst             |  1 +
 .../media/dvb/legacy_dvb_decoder_api.rst      | 61 +++++++++++++++++++
 2 files changed, 62 insertions(+)
 create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst

diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst
index b97d56ee543c..ffe8325749e5 100644
--- a/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst
+++ b/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst
@@ -23,3 +23,4 @@ DVB-S2, DVB-T2, ISDB, etc.
     :maxdepth: 1

     frontend_legacy_dvbv3_api
+    legacy_dvb_decoder_api
diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst
new file mode 100644
index 000000000000..f6e2f28b1fcb
--- /dev/null
+++ b/Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst
@@ -0,0 +1,61 @@
+.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0
+
+.. _legacy_dvb_decoder_api:
+
+============================
+Legacy DVB MPEG Decoder APIs
+============================
+
+.. _legacy_dvb_decoder_notes:
+
+General Notes
+=============
+
+This API has originally been designed for DVB only and is therefore limited to
+the :ref:`legacy_dvb_decoder_formats` used in such digital TV-broadcastsystems.
+
+To circumvent this limitations the more versatile :ref:`V4L2 <v4l2spec>` API has
+been designed. Which replaces this part of the DVB API.
+
+Nevertheless there have been projects build around this API.
+To ensure compatibility this API is kept as it is.
+
+.. attention:: Do **not** use this API in new drivers!
+
+    For audio and video use the :ref:`V4L2 <v4l2spec>` and ALSA APIs.
+
+    Pipelines should be set up using the :ref:`Media Controller  API<media_controller>`.
+
+Practically the decoders seem to be treated differently. The application typically
+knows which decoder is in use or it is specially written for one decoder type.
+Querying capabilities are rarely used because they are already known.
+
+
+.. _legacy_dvb_decoder_formats:
+
+Data Formats
+============
+
+The API has been designed for DVB and compatible broadcastsystems.
+Because of that fact the only supported data formats are ISO/IEC 13818-1
+compatible MPEG streams. The supported payloads may vary depending on the
+used decoder.
+
+Timestamps are always MPEG PTS as defined in ITU T-REC-H.222.0 /
+ISO/IEC 13818-1, if not otherwise noted.
+
+For storing recordings typically TS streams are used, in lesser extent PES.
+Both variants are commonly accepted for playback, but it may be driver dependent.
+
+
+
+
+Table of Contents
+=================
+
+.. toctree::
+    :maxdepth: 2
+
+    legacy_dvb_video
+    legacy_dvb_audio
+    legacy_dvb_osd
--
2.34.0

[PATCH v4 2/6] media: docs: uAPI: dvb/osd: completing the documentation

[Stefan Herdler]

The existing documentation of the legacy DVB Decoder API was incomplete.

Revising the documentation, adding missing parts and arranging the
documentation files new.

This patch contains the documentation of osd.h.

Signed-off-by: Stefan Herdler <herdler@nurfuerspam.de>
---

Changes since v3:
* Adjust title and description to better match existing documentation.


[PATCH v3] ------------------------------------------------------------

Everything is used by the AV7110 driver, except 3 OSD_Commands.
Remarks have been placed there.

That's probably the best solution.
Removing would create a gap in the enumeration.
Omitting in the documentation would make header and documentation
inconsistent again.



 .../media/dvb/legacy_dvb_osd.rst              | 883 ++++++++++++++++++
 1 file changed, 883 insertions(+)
 create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst

diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst
new file mode 100644
index 000000000000..eb4754bb00d0
--- /dev/null
+++ b/Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst
@@ -0,0 +1,883 @@
+.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0
+
+.. c:namespace:: dtv.legacy.osd
+
+.. _dvb_osd:
+
+==============
+DVB OSD Device
+==============
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+The DVB OSD device controls the OnScreen-Display of the AV7110 based
+DVB-cards with hardware MPEG2 decoder. It can be accessed through
+``/dev/dvb/adapter?/osd0``.
+Data types and ioctl definitions can be accessed by including
+``linux/dvb/osd.h`` in your application.
+
+The OSD is not a frame-buffer like on many other cards.
+It is a kind of canvas one can draw on.
+The color-depth is limited depending on the memory size installed.
+An appropriate palette of colors has to be set up.
+The installed memory size can be identified with the `OSD_GET_CAPABILITY`_
+ioctl.
+
+OSD Data Types
+==============
+
+OSD_Command
+-----------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    typedef enum {
+	/* All functions return -2 on "not open" */
+	OSD_Close = 1,
+	OSD_Open,
+	OSD_Show,
+	OSD_Hide,
+	OSD_Clear,
+	OSD_Fill,
+	OSD_SetColor,
+	OSD_SetPalette,
+	OSD_SetTrans,
+	OSD_SetPixel,
+	OSD_GetPixel,
+	OSD_SetRow,
+	OSD_SetBlock,
+	OSD_FillRow,
+	OSD_FillBlock,
+	OSD_Line,
+	OSD_Query,
+	OSD_Test,
+	OSD_Text,
+	OSD_SetWindow,
+	OSD_MoveWindow,
+	OSD_OpenRaw,
+    } OSD_Command;
+
+Commands
+~~~~~~~~
+
+.. note::  All functions return -2 on "not open"
+
+.. flat-table::
+    :header-rows:  1
+    :stub-columns: 0
+
+    -  ..
+
+       -  Command
+
+       -  | Used variables of ``struct`` `osd_cmd_t`_.
+          | Usage{variable} if alternative use.
+
+       -  :cspan:`2` Description
+
+
+
+    -  ..
+
+       -  ``OSD_Close``
+
+       -  -
+
+       -  | Disables OSD and releases the buffers.
+          | Returns 0 on success.
+
+    -  ..
+
+       -  ``OSD_Open``
+
+       -  | x0,y0,x1,y1,
+          | BitPerPixel[2/4/8]{color&0x0F},
+          | mix[0..15]{color&0xF0}
+
+       -  | Opens OSD with this size and bit depth
+          | Returns 0 on success,
+          | -1 on DRAM allocation error,
+          | -2 on "already open".
+
+    -  ..
+
+       -  ``OSD_Show``
+
+       - -
+
+       -  | Enables OSD mode.
+          | Returns 0 on success.
+
+    -  ..
+
+       -  ``OSD_Hide``
+
+       - -
+
+       -  | Disables OSD mode.
+          | Returns 0 on success.
+
+    -  ..
+
+       -  ``OSD_Clear``
+
+       - -
+
+       -  | Sets all pixel to color 0.
+          | Returns 0 on success.
+
+    -  ..
+
+       -  ``OSD_Fill``
+
+       -  color
+
+       -  | Sets all pixel to color <color>.
+          | Returns 0 on success.
+
+    -  ..
+
+       -  ``OSD_SetColor``
+
+       -  | color,
+          | R{x0},G{y0},B{x1},
+          | opacity{y1}
+
+       -  | Set palette entry <num> to <r,g,b>, <mix> and <trans> apply
+          | R,G,B: 0..255
+          | R=Red, G=Green, B=Blue
+          | opacity=0:      pixel opacity 0% (only video pixel shows)
+          | opacity=1..254: pixel opacity as specified in header
+          | opacity=255:    pixel opacity 100% (only OSD pixel shows)
+          | Returns 0 on success, -1 on error.
+
+    -  ..
+
+       -  ``OSD_SetPalette``
+
+       -  | firstcolor{color},
+          | lastcolor{x0},data
+
+       -  | Set a number of entries in the palette.
+          | Sets the entries "firstcolor" through "lastcolor" from the
+            array "data".
+          | Data has 4 byte for each color:
+          | R,G,B, and a opacity value: 0->transparent, 1..254->mix,
+            255->pixel
+
+    -  ..
+
+       -  ``OSD_SetTrans``
+
+       -  transparency{color}
+
+       -  | Sets transparency of mixed pixel (0..15).
+          | Returns 0 on success.
+
+    -  ..
+
+       -  ``OSD_SetPixel``
+
+       -  x0,y0,color
+
+       -  | Sets pixel <x>,<y> to color number <color>.
+          | Returns 0 on success, -1 on error.
+
+    -  ..
+
+       -  ``OSD_GetPixel``
+
+       -  x0,y0
+
+       -  | Returns color number of pixel <x>,<y>,  or -1.
+          | Command currently not supported by the AV7110!
+
+    -  ..
+
+       -  ``OSD_SetRow``
+
+       -  x0,y0,x1,data
+
+       -  | Fills pixels x0,y through  x1,y with the content of data[].
+          | Returns 0 on success, -1 on clipping all pixel (no pixel
+            drawn).
+
+    -  ..
+
+       -  ``OSD_SetBlock``
+
+       -  | x0,y0,x1,y1,
+          | increment{color},
+          | data
+
+       -  | Fills pixels x0,y0 through  x1,y1 with the content of data[].
+          | Inc contains the width of one line in the data block,
+          | inc<=0 uses block width as line width.
+          | Returns 0 on success, -1 on clipping all pixel.
+
+    -  ..
+
+       -  ``OSD_FillRow``
+
+       -  x0,y0,x1,color
+
+       -  | Fills pixels x0,y through  x1,y with the color <color>.
+          | Returns 0 on success, -1 on clipping all pixel.
+
+    -  ..
+
+       -  ``OSD_FillBlock``
+
+       -  x0,y0,x1,y1,color
+
+       -  | Fills pixels x0,y0 through  x1,y1 with the color <color>.
+          | Returns 0 on success, -1 on clipping all pixel.
+
+    -  ..
+
+       -  ``OSD_Line``
+
+       -  x0,y0,x1,y1,color
+
+       -  | Draw a line from x0,y0 to x1,y1 with the color <color>.
+          | Returns 0 on success.
+
+    -  ..
+
+       -  ``OSD_Query``
+
+       -  | x0,y0,x1,y1,
+          | xasp{color}; yasp=11
+
+       -  | Fills parameters with the picture dimensions and the pixel
+            aspect ratio.
+          | Returns 0 on success.
+          | Command currently not supported by the AV7110!
+
+    -  ..
+
+       -  ``OSD_Test``
+
+       -  -
+
+       -  | Draws a test picture.
+          | For debugging purposes only.
+          | Returns 0 on success.
+    -  ..
+
+       -  ``OSD_Text``
+
+       -  x0,y0,size,color,text
+
+       -  Draws a text at position x0,y0 with the color <color>.
+
+    -  ..
+
+       -  ``OSD_SetWindow``
+
+       -  x0
+
+       -  Set window with number 0<x0<8 as current.
+
+    -  ..
+
+       -  ``OSD_MoveWindow``
+
+       -  x0,y0
+
+       -  Move current window to (x0, y0).
+
+    -  ..
+
+       -  ``OSD_OpenRaw``
+
+       -  | x0,y0,x1,y1,
+          | `osd_raw_window_t`_ {color}
+
+       -  Open other types of OSD windows.
+
+Description
+~~~~~~~~~~~
+
+The ``OSD_Command`` data type is used with the `OSD_SEND_CMD`_ ioctl to
+tell the driver which OSD_Command to execute.
+
+
+-----
+
+osd_cmd_t
+---------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    typedef struct osd_cmd_s {
+	OSD_Command cmd;
+	int x0;
+	int y0;
+	int x1;
+	int y1;
+	int color;
+	void __user *data;
+    } osd_cmd_t;
+
+Variables
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``OSD_Command cmd``
+
+       -  `OSD_Command`_ to be executed.
+
+    -  ..
+
+       -  ``int x0``
+
+       -  First horizontal position.
+
+    -  ..
+
+       -  ``int y0``
+
+       -  First vertical position.
+
+    -  ..
+
+       -  ``int x1``
+
+       -  Second horizontal position.
+
+    -  ..
+
+       -  ``int y1``
+
+       -  Second vertical position.
+
+    -  ..
+
+       -  ``int color``
+
+       -  Number of the color in the palette.
+
+    -  ..
+
+       -  ``void __user *data``
+
+       -  Command specific Data.
+
+Description
+~~~~~~~~~~~
+
+The ``osd_cmd_t`` data type is used with the `OSD_SEND_CMD`_ ioctl.
+It contains the data for the OSD_Command and the `OSD_Command`_ itself.
+The structure has to be passed to the driver and the components may be
+modified by it.
+
+
+-----
+
+
+osd_raw_window_t
+----------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    typedef enum {
+	OSD_BITMAP1,
+	OSD_BITMAP2,
+	OSD_BITMAP4,
+	OSD_BITMAP8,
+	OSD_BITMAP1HR,
+	OSD_BITMAP2HR,
+	OSD_BITMAP4HR,
+	OSD_BITMAP8HR,
+	OSD_YCRCB422,
+	OSD_YCRCB444,
+	OSD_YCRCB444HR,
+	OSD_VIDEOTSIZE,
+	OSD_VIDEOHSIZE,
+	OSD_VIDEOQSIZE,
+	OSD_VIDEODSIZE,
+	OSD_VIDEOTHSIZE,
+	OSD_VIDEOTQSIZE,
+	OSD_VIDEOTDSIZE,
+	OSD_VIDEONSIZE,
+	OSD_CURSOR
+    } osd_raw_window_t;
+
+Constants
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``OSD_BITMAP1``
+
+       -  :cspan:`1` 1 bit bitmap
+
+    -  ..
+
+       -  ``OSD_BITMAP2``
+
+       -  2 bit bitmap
+
+    -  ..
+
+       -  ``OSD_BITMAP4``
+
+       -  4 bit bitmap
+
+    -  ..
+
+       -  ``OSD_BITMAP8``
+
+       -  8 bit bitmap
+
+    -  ..
+
+       -  ``OSD_BITMAP1HR``
+
+       -  1 Bit bitmap half resolution
+
+    -  ..
+
+       -  ``OSD_BITMAP2HR``
+
+       -  2 Bit bitmap half resolution
+
+    -  ..
+
+       -  ``OSD_BITMAP4HR``
+
+       -  4 Bit bitmap half resolution
+
+    -  ..
+
+       -  ``OSD_BITMAP8HR``
+
+       -  8 Bit bitmap half resolution
+
+    -  ..
+
+       -  ``OSD_YCRCB422``
+
+       -  4:2:2 YCRCB Graphic Display
+
+    -  ..
+
+       -  ``OSD_YCRCB444``
+
+       -  4:4:4 YCRCB Graphic Display
+
+    -  ..
+
+       -  ``OSD_YCRCB444HR``
+
+       -  4:4:4 YCRCB graphic half resolution
+
+    -  ..
+
+       -  ``OSD_VIDEOTSIZE``
+
+       -  True Size Normal MPEG Video Display
+
+    -  ..
+
+       -  ``OSD_VIDEOHSIZE``
+
+       -  MPEG Video Display Half Resolution
+
+    -  ..
+
+       -  ``OSD_VIDEOQSIZE``
+
+       -  MPEG Video Display Quarter Resolution
+
+    -  ..
+
+       -  ``OSD_VIDEODSIZE``
+
+       -  MPEG Video Display Double Resolution
+
+    -  ..
+
+       -  ``OSD_VIDEOTHSIZE``
+
+       -  True Size MPEG Video Display Half Resolution
+
+    -  ..
+
+       -  ``OSD_VIDEOTQSIZE``
+
+       -  True Size MPEG Video Display Quarter Resolution
+
+    -  ..
+
+       -  ``OSD_VIDEOTDSIZE``
+
+       -  True Size MPEG Video Display Double Resolution
+
+    -  ..
+
+       -  ``OSD_VIDEONSIZE``
+
+       -  Full Size MPEG Video Display
+
+    -  ..
+
+       -  ``OSD_CURSOR``
+
+       -  Cursor
+
+Description
+~~~~~~~~~~~
+
+The ``osd_raw_window_t`` data type is used with the `OSD_Command`_
+OSD_OpenRaw to tell the driver which type of OSD to open.
+
+
+-----
+
+
+osd_cap_t
+---------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    typedef struct osd_cap_s {
+	int  cmd;
+    #define OSD_CAP_MEMSIZE         1
+	long val;
+    } osd_cap_t;
+
+Variables
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int  cmd``
+
+       -  Capability to query.
+
+    -  ..
+
+       -  ``long val``
+
+       -  Used to store the Data.
+
+Supported capabilities
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``OSD_CAP_MEMSIZE``
+
+       -  Memory size installed on the card.
+
+Description
+~~~~~~~~~~~
+
+This structure of data used with the `OSD_GET_CAPABILITY`_ call.
+
+
+-----
+
+
+OSD Function Calls
+==================
+
+OSD_SEND_CMD
+------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: OSD_SEND_CMD
+
+.. code-block:: c
+
+    int ioctl(int fd, int request = OSD_SEND_CMD, enum osd_cmd_t *cmd)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Pointer to the location of the structure `osd_cmd_t`_ for this
+          command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl sends the `OSD_Command`_ to the card.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``EINVAL``
+
+       -  Command is out of range.
+
+
+-----
+
+
+OSD_GET_CAPABILITY
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: OSD_GET_CAPABILITY
+
+.. code-block:: c
+
+    int ioctl(int fd, int request = OSD_GET_CAPABILITY,
+    struct osd_cap_t *cap)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``OSD_GET_CAPABILITY`` for this command.
+
+    -  ..
+
+       -  ``unsigned int *cap``
+
+       -  Pointer to the location of the structure `osd_cap_t`_ for this
+          command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is used to get the capabilities of the OSD of the AV7110 based
+DVB-decoder-card in use.
+
+.. note::
+    The structure osd_cap_t has to be setup by the user and passed to the
+    driver.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+
+    -  ..
+
+       -  ``EINVAL``
+
+       -  Unsupported capability.
+
+
+-----
+
+
+open()
+------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    #include <fcntl.h>
+
+.. c:function:: int open(const char *deviceName, int flags)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``const char *deviceName``
+
+       -  Name of specific OSD device.
+
+    -  ..
+
+       -  :rspan:`3` ``int flags``
+
+       -  :cspan:`1` A bit-wise OR of the following flags:
+
+    -  ..
+
+       -  ``O_RDONLY``
+
+       -  read-only access
+
+    -  ..
+
+       -  ``O_RDWR``
+
+       -  read/write access
+
+    -  ..
+
+       -  ``O_NONBLOCK``
+       -  | Open in non-blocking mode
+          | (blocking mode is the default)
+
+Description
+~~~~~~~~~~~
+
+This system call opens a named OSD device (e.g.
+``/dev/dvb/adapter?/osd0``) for subsequent use.
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``ENODEV``
+
+       -  Device driver not loaded/available.
+
+    -  ..
+
+       -  ``EINTERNAL``
+
+       -  Internal error.
+
+    -  ..
+
+       -  ``EBUSY``
+
+       -  Device or resource busy.
+
+    -  ..
+
+       -  ``EINVAL``
+
+       -  Invalid argument.
+
+
+-----
+
+
+close()
+-------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int close(int fd)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_ .
+
+Description
+~~~~~~~~~~~
+
+This system call closes a previously opened OSD device.
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``EBADF``
+
+       -  fd is not a valid open file descriptor.
--
2.34.0

[PATCH v4 3/6] media: docs: uAPI: dvb/audio: completing the documentation (data types)

[Stefan Herdler]

The existing documentation of the legacy DVB Decoder API was incomplete.

Revising the documentation, adding missing parts and arranging the
documentation files new.

This patch contains the documentation of the data types defined in
audio.h.

Signed-off-by: Stefan Herdler <herdler@nurfuerspam.de>
---

Changes since v3:
* Adjust title and description to better match existing documentation.
* Change reference from :c:enum:`dmx_output` to :c:type: to silence the
  warning from the kernel test robot.


 .../media/dvb/legacy_dvb_audio.rst            | 447 ++++++++++++++++++
 1 file changed, 447 insertions(+)
 create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst

diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst
new file mode 100644
index 000000000000..4c994f8c97e5
--- /dev/null
+++ b/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst
@@ -0,0 +1,447 @@
+.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0
+
+.. c:namespace:: dtv.legacy.audio
+
+.. _dvb_audio:
+
+================
+DVB Audio Device
+================
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+The DVB audio device controls the MPEG2 audio decoder of the DVB
+hardware. It can be accessed through ``/dev/dvb/adapter?/audio?``. Data
+types and ioctl definitions can be accessed by including
+``linux/dvb/audio.h`` in your application.
+
+Please note that most DVB cards don’t have their own MPEG decoder, which
+results in the omission of the audio and video device.
+
+These ioctls were also used by V4L2 to control MPEG decoders implemented
+in V4L2. The use of these ioctls for that purpose has been made obsolete
+and proper V4L2 ioctls or controls have been created to replace that
+functionality. Use :ref:`V4L2 ioctls<audio>` for new drivers!
+
+
+Audio Data Types
+================
+
+This section describes the structures, data types and defines used when
+talking to the audio device.
+
+
+-----
+
+
+audio_stream_source_t
+---------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:enum:: audio_stream_source_t
+
+.. code-block:: c
+
+    typedef enum {
+    AUDIO_SOURCE_DEMUX,
+    AUDIO_SOURCE_MEMORY
+    } audio_stream_source_t;
+
+Constants
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``AUDIO_SOURCE_DEMUX``
+
+       -  :cspan:`1` Selects the demultiplexer (fed either by the frontend
+          or the DVR device) as the source of the video stream.
+
+    -  ..
+
+       -  ``AUDIO_SOURCE_MEMORY``
+
+       -  Selects the stream from the application that comes through
+          the `write()`_ system call.
+
+Description
+~~~~~~~~~~~
+
+The audio stream source is set through the `AUDIO_SELECT_SOURCE`_ call
+and can take the following values, depending on whether we are replaying
+from an internal (demux) or external (user write) source.
+
+The data fed to the decoder is also controlled by the PID-filter.
+Output selection: :c:type:`dmx_output` ``DMX_OUT_DECODER``.
+
+
+-----
+
+
+audio_play_state_t
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:enum:: audio_play_state_t
+
+.. code-block:: c
+
+    typedef enum {
+	AUDIO_STOPPED,
+	AUDIO_PLAYING,
+	AUDIO_PAUSED
+    } audio_play_state_t;
+
+Constants
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``AUDIO_STOPPED``
+
+       -  Audio is stopped.
+
+    -  ..
+
+       -  ``AUDIO_PLAYING``
+
+       -  Audio is currently playing.
+
+    -  ..
+
+       -  ``AUDIO_PAUSE``
+
+       -  Audio is frozen.
+
+Description
+~~~~~~~~~~~
+
+This values can be returned by the `AUDIO_GET_STATUS`_ call
+representing the state of audio playback.
+
+
+-----
+
+
+audio_channel_select_t
+----------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:enum:: audio_channel_select_t
+
+.. code-block:: c
+
+    typedef enum {
+	AUDIO_STEREO,
+	AUDIO_MONO_LEFT,
+	AUDIO_MONO_RIGHT,
+	AUDIO_MONO,
+	AUDIO_STEREO_SWAPPED
+    } audio_channel_select_t;
+
+Constants
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``AUDIO_STEREO``
+
+       -  Stereo.
+
+    -  ..
+
+       -  ``AUDIO_MONO_LEFT``
+
+       -  Mono, select left stereo channel as source.
+
+    -  ..
+
+       -  ``AUDIO_MONO_RIGHT``
+
+       -  Mono, select right stereo channel as source.
+
+    -  ..
+
+       -  ``AUDIO_MONO``
+
+       -  Mono source only.
+
+    -  ..
+
+       -  ``AUDIO_STEREO_SWAPPED``
+
+       -  Stereo, swap L & R.
+
+Description
+~~~~~~~~~~~
+
+The audio channel selected via `AUDIO_CHANNEL_SELECT`_ is determined by
+this values.
+
+
+-----
+
+
+audio_mixer_t
+-------------
+
+Synopsis
+~~~~~~~~
+
+.. c:struct:: audio_mixer
+
+.. code-block:: c
+
+    typedef struct audio_mixer {
+	unsigned int volume_left;
+	unsigned int volume_right;
+    } audio_mixer_t;
+
+Variables
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``unsigned int volume_left``
+
+       -  Volume left channel.
+          Valid range: 0 ... 255
+
+    -  ..
+
+       -  ``unsigned int volume_right``
+
+       -  Volume right channel.
+          Valid range: 0 ... 255
+
+Description
+~~~~~~~~~~~
+
+This structure is used by the `AUDIO_SET_MIXER`_ call to set the
+audio volume.
+
+
+-----
+
+
+audio_status
+------------
+
+Synopsis
+~~~~~~~~
+
+.. c:struct:: audio_status
+
+.. code-block:: c
+
+    typedef struct audio_status {
+	int AV_sync_state;
+	int mute_state;
+	audio_play_state_t play_state;
+	audio_stream_source_t stream_source;
+	audio_channel_select_t channel_select;
+	int bypass_mode;
+	audio_mixer_t mixer_state;
+    } audio_status_t;
+
+Variables
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  :rspan:`2` ``int AV_sync_state``
+
+       -  :cspan:`1` Shows if A/V synchronization is ON or OFF.
+
+    -  ..
+
+       -  TRUE  ( != 0 )
+
+       -  AV-sync ON.
+
+    -  ..
+
+       -  FALSE ( == 0 )
+
+       -  AV-sync OFF.
+
+    -  ..
+
+       -  :rspan:`2` ``int mute_state``
+
+       -  :cspan:`1` Indicates if audio is muted or not.
+
+    -  ..
+
+       -  TRUE  ( != 0 )
+
+       -  mute audio
+
+    -  ..
+
+       -  FALSE ( == 0 )
+
+       -  unmute audio
+
+    -  ..
+
+       -  `audio_play_state_t`_ ``play_state``
+
+       -  Current playback state.
+
+    -  ..
+
+       -  `audio_stream_source_t`_ ``stream_source``
+
+       -  Current source of the data.
+
+    -  ..
+
+       -  :rspan:`2` ``int bypass_mode``
+
+       -  :cspan:`1` Is the decoding of the current Audio stream in
+          the DVB subsystem enabled or disabled.
+
+    -  ..
+
+       -  TRUE  ( != 0 )
+
+       -  Bypass disabled.
+
+    -  ..
+
+       -  FALSE ( == 0 )
+
+       -  Bypass enabled.
+
+    -  ..
+
+       -  `audio_mixer_t`_ ``mixer_state``
+
+       -  Current volume settings.
+
+Description
+~~~~~~~~~~~
+
+The `AUDIO_GET_STATUS`_ call returns this structure as information
+about various states of the playback operation.
+
+
+-----
+
+
+audio encodings
+---------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+     #define AUDIO_CAP_DTS    1
+     #define AUDIO_CAP_LPCM   2
+     #define AUDIO_CAP_MP1    4
+     #define AUDIO_CAP_MP2    8
+     #define AUDIO_CAP_MP3   16
+     #define AUDIO_CAP_AAC   32
+     #define AUDIO_CAP_OGG   64
+     #define AUDIO_CAP_SDDS 128
+     #define AUDIO_CAP_AC3  256
+
+Constants
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``AUDIO_CAP_DTS``
+
+       -  :cspan:`1` The hardware accepts DTS audio tracks.
+
+    -  ..
+
+       -  ``AUDIO_CAP_LPCM``
+
+       -   The hardware accepts uncompressed audio with
+           Linear Pulse-Code Modulation (LPCM)
+
+    -  ..
+
+       -  ``AUDIO_CAP_MP1``
+
+       -  The hardware accepts MPEG-1 Audio Layer 1.
+
+    -  ..
+
+       -  ``AUDIO_CAP_MP2``
+
+       -  The hardware accepts MPEG-1 Audio Layer 2.
+          Also known as MUSICAM.
+
+    -  ..
+
+       -  ``AUDIO_CAP_MP3``
+
+       -  The hardware accepts MPEG-1 Audio Layer III.
+          Commomly known as .mp3.
+
+    -  ..
+
+       -  ``AUDIO_CAP_AAC``
+
+       -  The hardware accepts AAC (Advanced Audio Coding).
+
+    -  ..
+
+       -  ``AUDIO_CAP_OGG``
+
+       -  The hardware accepts Vorbis audio tracks.
+
+    -  ..
+
+       -  ``AUDIO_CAP_SDDS``
+
+       -  The hardware accepts Sony Dynamic Digital Sound (SDDS).
+
+    -  ..
+
+       -  ``AUDIO_CAP_AC3``
+
+       -  The hardware accepts Dolby Digital ATSC A/52 audio.
+          Also known as AC-3.
+
+Description
+~~~~~~~~~~~
+
+A call to `AUDIO_GET_CAPABILITIES`_ returns an unsigned integer with the
+following bits set according to the hardwares capabilities.
--
2.34.0

[PATCH v4 4/6] media: docs: uAPI: dvb/audio: completing the documentation (function calls)

[Stefan Herdler]

The existing documentation of the legacy DVB Decoder API was incomplete.

Revising the documentation, adding missing parts and arranging the
documentation files new.

This patch contains the documentation of the function calls defined in
audio.h.

Signed-off-by: Stefan Herdler <herdler@nurfuerspam.de>
---

Changes since v3:
* Adjust title and description to better match existing documentation.


[PATCH v3] ------------------------------------------------------------

Possibly unused:
AUDIO_SET_ID
AUDIO_SET_STREAMTYPE
AUDIO_BILINGUAL_CHANNEL_SELECT



> +
> +AUDIO_SET_ID
> +------------
> +
> +AUDIO_SET_STREAMTYPE
> +--------------------
This ioctls are dealing with stream types and IDs defined in
ITU-T H.222.0. The intention is pretty clear when reading the introduction
of Annex Q there.
However this ioctls doesn't seem to be used anywhere.



>> +
>> +AUDIO_BILINGUAL_CHANNEL_SELECT
>> +------------------------------
>> +
>
[...]
>
> IMO, this is also another problematic API. Its name seems to be related
> to language selection. However, multi-language usually uses different
> PIDs. Maybe in the past they used to place two languages at the same
> PID, one at the left channel and the other at the right one?

It seems to be intended this way.
This kind multi-language was popular in the beginning of DVB, but it has
been mostly replaced by multiple PIDs.

The AV7110 uses AUDIO_CHANNEL_SELECT for the same purpose.
This 2 ioctls look redundant to me and AUDIO_BILINGUAL_CHANNEL_SELECT
doesn't seem to be used at all.



 .../media/dvb/legacy_dvb_audio.rst            | 1195 +++++++++++++++++
 1 file changed, 1195 insertions(+)

diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst
index 4c994f8c97e5..45d330c33caf 100644
--- a/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst
+++ b/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst
@@ -445,3 +445,1198 @@ Description

 A call to `AUDIO_GET_CAPABILITIES`_ returns an unsigned integer with the
 following bits set according to the hardwares capabilities.
+
+
+-----
+
+
+Audio Function Calls
+====================
+
+
+AUDIO_STOP
+----------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_STOP
+
+.. code-block:: c
+
+	 int ioctl(int fd, int request = AUDIO_STOP)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  :cspan:`1` Equals ``AUDIO_STOP`` for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to stop playing the current
+stream.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_PLAY
+----------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_PLAY
+
+.. code-block:: c
+
+	 int  ioctl(int fd, int request = AUDIO_PLAY)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  File descriptor returned by a previous call to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  :cspan:`1` Equals ``AUDIO_PLAY`` for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to start playing an audio stream
+from the selected source.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_PAUSE
+-----------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_PAUSE
+
+.. code-block:: c
+
+	 int  ioctl(int fd, int request = AUDIO_PAUSE)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``AUDIO_PAUSE`` for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call suspends the audio stream being played. Decoding and
+playing are paused. It is then possible to restart again decoding and
+playing process of the audio stream using `AUDIO_CONTINUE`_ command.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_CONTINUE
+--------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_CONTINUE
+
+.. code-block:: c
+
+	 int  ioctl(int fd, int request = AUDIO_CONTINUE)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``AUDIO_CONTINUE`` for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl restarts the decoding and playing process previously paused
+with `AUDIO_PAUSE`_ command.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_SELECT_SOURCE
+-------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_SELECT_SOURCE
+
+.. code-block:: c
+
+	 int ioctl(int fd, int request = AUDIO_SELECT_SOURCE,
+	 audio_stream_source_t source)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``AUDIO_SELECT_SOURCE`` for this command.
+
+    -  ..
+
+       -  `audio_stream_source_t`_ ``source``
+
+       -  Indicates the source that shall be used for the Audio stream.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call informs the audio device which source shall be used for
+the input data. The possible sources are demux or memory. If
+``AUDIO_SOURCE_MEMORY`` is selected, the data is fed to the Audio Device
+through the write command. If ``AUDIO_SOURCE_DEMUX`` is selected, the data
+is directly transferred from the onboard demux-device to the decoder.
+Note: This only supports DVB-devices with one demux and one decoder so far.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_SET_MUTE
+--------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_SET_MUTE
+
+.. code-block:: c
+
+	 int  ioctl(int fd, int request = AUDIO_SET_MUTE, int state)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  :cspan:`1` Equals ``AUDIO_SET_MUTE`` for this command.
+
+    -  ..
+
+       -  :rspan:`2` ``int state``
+
+       -  :cspan:`1` Indicates if audio device shall mute or not.
+
+    -  ..
+
+       -  TRUE  ( != 0 )
+
+       -  mute audio
+
+    -  ..
+
+       -  FALSE ( == 0 )
+
+       -  unmute audio
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for DVB devices only. To control a V4L2 decoder use the
+V4L2 :ref:`VIDIOC_DECODER_CMD` with the
+``V4L2_DEC_CMD_START_MUTE_AUDIO`` flag instead.
+
+This ioctl call asks the audio device to mute the stream that is
+currently being played.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_SET_AV_SYNC
+-----------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_SET_AV_SYNC
+
+.. code-block:: c
+
+	 int  ioctl(int fd, int request = AUDIO_SET_AV_SYNC, int state)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  :cspan:`1` Equals ``AUDIO_AV_SYNC`` for this command.
+
+    -  ..
+
+       -  :rspan:`2` ``int state``
+
+       -  :cspan:`1` Tells the DVB subsystem if A/V synchronization
+          shall be ON or OFF.
+
+    -  ..
+
+       -  TRUE  ( != 0 )
+
+       -  AV-sync ON.
+
+    -  ..
+
+       -  FALSE ( == 0 )
+
+       -  AV-sync OFF.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to turn ON or OFF A/V
+synchronization.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_SET_BYPASS_MODE
+---------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_SET_BYPASS_MODE
+
+.. code-block:: c
+
+	 int ioctl(int fd, int request = AUDIO_SET_BYPASS_MODE, int mode)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  :cspan:`1` Equals ``AUDIO_SET_BYPASS_MODE`` for this command.
+
+    -  ..
+
+       -  :rspan:`2` ``int mode``
+
+       -  :cspan:`1` Enables or disables the decoding of the current
+          Audio stream in the DVB subsystem.
+    -  ..
+
+       -  TRUE  ( != 0 )
+
+       -  Disable bypass
+
+    -  ..
+
+       -  FALSE ( == 0 )
+
+       -  Enable bypass
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to bypass the Audio decoder and
+forward the stream without decoding. This mode shall be used if streams
+that can’t be handled by the DVB system shall be decoded. Dolby
+DigitalTM streams are automatically forwarded by the DVB subsystem if
+the hardware can handle it.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_CHANNEL_SELECT
+--------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_CHANNEL_SELECT
+
+.. code-block:: c
+
+	 int ioctl(int fd, int request = AUDIO_CHANNEL_SELECT,
+	 audio_channel_select_t)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``AUDIO_CHANNEL_SELECT`` for this command.
+
+    -  ..
+
+       -  `audio_channel_select_t`_ ``ch``
+
+       -  Select the output format of the audio (mono left/right, stereo).
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for DVB devices only. To control a V4L2 decoder use the
+V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK`` control instead.
+
+This ioctl call asks the Audio Device to select the requested channel if
+possible.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_GET_STATUS
+----------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_GET_STATUS
+
+.. code-block:: c
+
+	 int ioctl(int fd, int request = AUDIO_GET_STATUS,
+	 struct audio_status *status)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals AUDIO_GET_STATUS for this command.
+
+    -  ..
+
+       -  ``struct`` `audio_status`_ ``*status``
+
+       -  Returns the current state of Audio Device.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to return the current state of the
+Audio Device.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_GET_CAPABILITIES
+----------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_GET_CAPABILITIES
+
+.. code-block:: c
+
+	 int ioctl(int fd, int request = AUDIO_GET_CAPABILITIES,
+	 unsigned int *cap)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``AUDIO_GET_CAPABILITIES`` for this command.
+
+    -  ..
+
+       -  ``unsigned int *cap``
+
+       -  Returns a bit array of supported sound formats.
+          Bits are defined in `audio encodings`_.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to tell us about the decoding
+capabilities of the audio hardware.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_CLEAR_BUFFER
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_CLEAR_BUFFER
+
+.. code-block:: c
+
+	 int  ioctl(int fd, int request = AUDIO_CLEAR_BUFFER)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``AUDIO_CLEAR_BUFFER`` for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Audio Device to clear all software and hardware
+buffers of the audio decoder device.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_SET_ID
+------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_SET_ID
+
+.. code-block:: c
+
+	 int  ioctl(int fd, int request = AUDIO_SET_ID, int id)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``AUDIO_SET_ID`` for this command.
+
+    -  ..
+
+       -  ``int id``
+
+       -  Audio sub-stream id.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl selects which sub-stream is to be decoded if a program or
+system stream is sent to the video device.
+
+If no audio stream type is set the id has to be in range [0xC0,0xDF]
+for MPEG sound, in [0x80,0x87] for AC3 and in [0xA0,0xA7] for LPCM.
+See ITU-T H.222.0 | ISO/IEC 13818-1 for further description.
+
+If the stream type is set with `AUDIO_SET_STREAMTYPE`_, specifies the
+id just the sub-stream id of the audio stream and only the first 5 bits
+(& 0x1F) are recognized.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_SET_MIXER
+---------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_SET_MIXER
+
+.. code-block:: c
+
+	 int ioctl(int fd, int request = AUDIO_SET_MIXER, audio_mixer_t *mix)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``AUDIO_SET_MIXER`` for this command.
+
+    -  ..
+
+       -  ``audio_mixer_t *mix``
+
+       -  Mixer settings.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl lets you adjust the mixer settings of the audio decoder.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+AUDIO_SET_STREAMTYPE
+--------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_SET_STREAMTYPE
+
+.. code-block:: c
+
+	 int  ioctl(fd, int request = AUDIO_SET_STREAMTYPE, int type)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``AUDIO_SET_STREAMTYPE`` for this command.
+
+    -  ..
+
+       -  ``int type``
+
+       -  Stream type.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl tells the driver which kind of audio stream to expect. This
+is useful if the stream offers several audio sub-streams like LPCM and
+AC3.
+
+Stream types defined in ITU-T H.222.0 | ISO/IEC 13818-1 are used.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``EINVAL``
+
+       -  Type is not a valid or supported stream type.
+
+
+-----
+
+
+AUDIO_BILINGUAL_CHANNEL_SELECT
+------------------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: AUDIO_BILINGUAL_CHANNEL_SELECT
+
+.. code-block:: c
+
+	 int ioctl(int fd, int request = AUDIO_BILINGUAL_CHANNEL_SELECT,
+	 audio_channel_select_t)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``AUDIO_BILINGUAL_CHANNEL_SELECT`` for this command.
+
+    -  ..
+
+       -  ``audio_channel_select_t ch``
+
+       -  Select the output format of the audio (mono left/right, stereo).
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl has been replaced by the V4L2
+``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK`` control
+for MPEG decoders controlled through V4L2.
+
+This ioctl call asks the Audio Device to select the requested channel
+for bilingual streams if possible.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+open()
+------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    #include <fcntl.h>
+
+.. c:function:: int  open(const char *deviceName, int flags)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``const char *deviceName``
+
+       -  Name of specific audio device.
+
+    -  ..
+
+       -  :rspan:`3` ``int flags``
+
+       -  :cspan:`1` A bit-wise OR of the following flags:
+
+    -  ..
+
+       -  ``O_RDONLY``
+
+       -  read-only access
+
+    -  ..
+
+       -  ``O_RDWR``
+
+       -  read/write access
+
+    -  ..
+
+       -  ``O_NONBLOCK``
+       -  | Open in non-blocking mode
+          | (blocking mode is the default)
+
+Description
+~~~~~~~~~~~
+
+This system call opens a named audio device (e.g.
+``/dev/dvb/adapter0/audio0``) for subsequent use. When an open() call has
+succeeded, the device will be ready for use. The significance of
+blocking or non-blocking mode is described in the documentation for
+functions where there is a difference. It does not affect the semantics
+of the open() call itself. A device opened in blocking mode can later be
+put into non-blocking mode (and vice versa) using the F_SETFL command
+of the fcntl system call. This is a standard system call, documented in
+the Linux manual page for fcntl. Only one user can open the Audio Device
+in O_RDWR mode. All other attempts to open the device in this mode will
+fail, and an error code will be returned. If the Audio Device is opened
+in O_RDONLY mode, the only ioctl call that can be used is
+`AUDIO_GET_STATUS`_. All other call will return with an error code.
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``ENODEV``
+
+       -  Device driver not loaded/available.
+
+    -  ..
+
+       -  ``EBUSY``
+
+       -  Device or resource busy.
+
+    -  ..
+
+       -  ``EINVAL``
+
+       -  Invalid argument.
+
+
+-----
+
+
+close()
+-------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: 	int close(int fd)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+Description
+~~~~~~~~~~~
+
+This system call closes a previously opened audio device.
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``EBADF``
+
+       -  Fd is not a valid open file descriptor.
+
+-----
+
+
+write()
+-------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+	 size_t write(int fd, const void *buf, size_t count)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``void *buf``
+
+       -  Pointer to the buffer containing the PES data.
+
+    -  ..
+
+       -  ``size_t count``
+
+       -  Size of buf.
+
+Description
+~~~~~~~~~~~
+
+This system call can only be used if ``AUDIO_SOURCE_MEMORY`` is selected
+in the ioctl call `AUDIO_SELECT_SOURCE`_. The data provided shall be in
+PES format. If ``O_NONBLOCK`` is not specified the function will block
+until buffer space is available. The amount of data to be transferred is
+implied by count.
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``EPERM``
+
+       -  :cspan:`1` Mode ``AUDIO_SOURCE_MEMORY`` not selected.
+
+    -  ..
+
+       -  ``ENOMEM``
+
+       -  Attempted to write more data than the internal buffer can hold.
+
+    -  ..
+
+       -  ``EBADF``
+
+       -  Fd is not a valid open file descriptor.
--
2.34.0

[PATCH v4 5/6] media: docs: uAPI: dvb/video: completing the documentation (data types)

[Stefan Herdler]

The existing documentation of the legacy DVB Decoder API was incomplete.

Revising the documentation, adding missing parts and arranging the
documentation files new.

This patch contains the documentation of the data types defined in
video.h.

Signed-off-by: Stefan Herdler <herdler@nurfuerspam.de>
---

Changes since v3:
* Adjust title and description to better match existing documentation.


[PATCH v3] ------------------------------------------------------------

Possibly left overs from DVD-API ? :
 video_attributes_t
 VIDEO_CAP_SPU
 VIDEO_CAP_NAVI
 VIDEO_CAP_CSS
The only thing which is not in the documentation yet!
Can probably removed from header file too.

>> +
>> +video_stream_source_t
>> +---------------------
>> +
>> +The video stream source is set through the `VIDEO_SELECT_SOURCE`_ call
>> +and can take the following values, depending on whether we are replaying
>> +from an internal (demuxer) or external (user write) source.
>> +
>> +
>> +.. code-block:: c
>> +
>> +    typedef enum {
>> +	VIDEO_SOURCE_DEMUX, /* Select the demux as the main source */
>> +	VIDEO_SOURCE_MEMORY /* If this source is selected, the stream
>> +		       comes from the user through the write
>> +		       system call */
>> +    } video_stream_source_t;
>
> FYI, this carries the same problem as the audio one: this API is problematic
> for modern hardware that has multiple tuners and demuxers. Setting up
> pipelines for audio and video decoding on modern hardware require a lot
> more than just demux/memory.

This kind of limitations are pretty well known for a while now, even to
normal users.
A good solution would be widely appreciated, I think.
Well, but back to topic ...


In case of the decoder we are are maybe lucky. One decoder with multiple
demuxers should theoretically already be possible without any changes.
The data fed to the decoder can be controlled by the PID filter output
selection DMX_OUT_DECODER.

There are existing multi tuner systems with one decoder controlled by this
API, but I don't know whether they do it this way or not.
A quick search wasn't very successful and at least the AV7110 should have
a hardware PID filter. More detailed research has to be done there to
answer the question.
However this topic is not directly part of the decoder API and I'm running
out of time, so I had to stop at this point.



 .../media/dvb/legacy_dvb_video.rst            | 798 ++++++++++++++++++
 1 file changed, 798 insertions(+)
 create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_video.rst

diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst
new file mode 100644
index 000000000000..165fd6005a07
--- /dev/null
+++ b/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst
@@ -0,0 +1,798 @@
+.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0
+
+.. c:namespace:: dtv.legacy.video
+
+.. _dvb_video:
+
+================
+DVB Video Device
+================
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+The DVB video device controls the MPEG2 video decoder of the DVB
+hardware. It can be accessed through ``/dev/dvb/adapter0/video0``. Data
+types and ioctl definitions can be accessed by including
+``linux/dvb/video.h`` in your application.
+
+Note that the DVB video device only controls decoding of the MPEG video
+stream, not its presentation on the TV or computer screen. On PCs this
+is typically handled by an associated video4linux device, e.g.
+``/dev/video``, which allows scaling and defining output windows.
+
+Most DVB cards don’t have their own MPEG decoder, which results in the
+omission of the audio and video device as well as the video4linux
+device.
+
+These ioctls were also used by V4L2 to control MPEG decoders implemented
+in V4L2. The use of these ioctls for that purpose has been made obsolete
+and proper V4L2 ioctls or controls have been created to replace that
+functionality. Use :ref:`V4L2 ioctls<video>` for new drivers!
+
+
+Video Data Types
+================
+
+
+
+video_format_t
+--------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    typedef enum {
+	VIDEO_FORMAT_4_3,
+	VIDEO_FORMAT_16_9,
+	VIDEO_FORMAT_221_1
+    } video_format_t;
+
+Constants
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``VIDEO_FORMAT_4_3``
+
+       -  Select 4:3 format.
+
+    -  ..
+
+       -  ``VIDEO_FORMAT_16_9``
+
+       -  Select 16:9 format.
+
+    -  ..
+
+       -  ``VIDEO_FORMAT_221_1``
+
+       -  Select 2.21:1 format.
+
+Description
+~~~~~~~~~~~
+
+The ``video_format_t`` data type
+is used in the `VIDEO_SET_FORMAT`_ function to tell the driver which
+aspect ratio the output hardware (e.g. TV) has. It is also used in the
+data structures `video_status`_ returned by `VIDEO_GET_STATUS`_
+and `video_event`_ returned by `VIDEO_GET_EVENT`_ which report
+about the display format of the current video stream.
+
+
+-----
+
+
+video_displayformat_t
+---------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    typedef enum {
+	VIDEO_PAN_SCAN,
+	VIDEO_LETTER_BOX,
+	VIDEO_CENTER_CUT_OUT
+    } video_displayformat_t;
+
+Constants
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``VIDEO_PAN_SCAN``
+
+       -  Use pan and scan format.
+
+    -  ..
+
+       -  ``VIDEO_LETTER_BOX``
+
+       -  Use letterbox format.
+
+    -  ..
+
+       -  ``VIDEO_CENTER_CUT_OUT``
+
+       -  Use center cut out format.
+
+Description
+~~~~~~~~~~~
+
+In case the display format of the video stream and of the display
+hardware differ the application has to specify how to handle the
+cropping of the picture. This can be done using the
+`VIDEO_SET_DISPLAY_FORMAT`_ call which accepts this enum as argument.
+
+
+-----
+
+
+video_size_t
+------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    typedef struct {
+	int w;
+	int h;
+	video_format_t aspect_ratio;
+    } video_size_t;
+
+Variables
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int w``
+
+       -  Video width in pixels.
+
+    -  ..
+
+       -  ``int h``
+
+       -  Video height in pixels.
+
+    -  ..
+
+       -  `video_format_t`_ ``aspect_ratio``
+
+       -  Aspect ratio.
+
+Description
+~~~~~~~~~~~
+
+Used in the struct `video_event`_. It stores the resolution and
+aspect ratio of the video.
+
+
+-----
+
+
+video_stream_source_t
+---------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    typedef enum {
+	VIDEO_SOURCE_DEMUX,
+	VIDEO_SOURCE_MEMORY
+    } video_stream_source_t;
+
+Constants
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``VIDEO_SOURCE_DEMUX``
+
+       -  :cspan:`1` Select the demux as the main source.
+
+    -  ..
+
+       -  ``VIDEO_SOURCE_MEMORY``
+
+       -  If this source is selected, the stream
+          comes from the user through the write
+          system call.
+
+Description
+~~~~~~~~~~~
+
+The video stream source is set through the `VIDEO_SELECT_SOURCE`_ call
+and can take the following values, depending on whether we are replaying
+from an internal (demuxer) or external (user write) source.
+VIDEO_SOURCE_DEMUX selects the demultiplexer (fed either by the
+frontend or the DVR device) as the source of the video stream. If
+VIDEO_SOURCE_MEMORY is selected the stream comes from the application
+through the `write()`_ system call.
+
+
+-----
+
+
+video_play_state_t
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    typedef enum {
+	VIDEO_STOPPED,
+	VIDEO_PLAYING,
+	VIDEO_FREEZED
+    } video_play_state_t;
+
+Constants
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``VIDEO_STOPPED``
+
+       -  Video is stopped.
+
+    -  ..
+
+       -  ``VIDEO_PLAYING``
+
+       -  Video is currently playing.
+
+    -  ..
+
+       -  ``VIDEO_FREEZED``
+
+       -  Video is frozen.
+
+Description
+~~~~~~~~~~~
+
+This values can be returned by the `VIDEO_GET_STATUS`_ call
+representing the state of video playback.
+
+
+-----
+
+
+struct video_command
+--------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    struct video_command {
+	__u32 cmd;
+	__u32 flags;
+	union {
+	    struct {
+		__u64 pts;
+	    } stop;
+
+	    struct {
+		__s32 speed;
+		__u32 format;
+	    } play;
+
+	    struct {
+		__u32 data[16];
+	    } raw;
+	};
+    };
+
+
+Variables
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``__u32 cmd``
+
+       -  `Decoder command`_
+
+    -  ..
+
+       -  ``__u32 flags``
+
+       -  Flags for the `Decoder command`_.
+
+    -  ..
+
+       -  ``struct stop``
+
+       -  ``__u64 pts``
+
+       -  MPEG PTS
+
+    -  ..
+
+       -  :rspan:`5` ``stuct play``
+
+       -  :rspan:`4` ``__s32 speed``
+
+       -   0 or 1000 specifies normal speed,
+
+    -  ..
+
+       -   1:  specifies forward single stepping,
+
+    -  ..
+
+       -   -1: specifies backward single stepping,
+
+    -  ..
+
+       -   >1: playback at speed / 1000 of the normal speed
+
+    -  ..
+
+       -   <-1: reverse playback at ( -speed / 1000 ) of the normal speed.
+
+    -  ..
+
+       -  ``__u32 format``
+
+       -  `Play input formats`_
+
+    -  ..
+
+       -  ``__u32 data[16]``
+
+       -  Reserved
+
+Description
+~~~~~~~~~~~
+
+The structure must be zeroed before use by the application. This ensures
+it can be extended safely in the future.
+
+
+-----
+
+
+Predefined decoder commands and flags
+-------------------------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    #define VIDEO_CMD_PLAY                      (0)
+    #define VIDEO_CMD_STOP                      (1)
+    #define VIDEO_CMD_FREEZE                    (2)
+    #define VIDEO_CMD_CONTINUE                  (3)
+
+    #define VIDEO_CMD_FREEZE_TO_BLACK      (1 << 0)
+
+    #define VIDEO_CMD_STOP_TO_BLACK        (1 << 0)
+    #define VIDEO_CMD_STOP_IMMEDIATELY     (1 << 1)
+
+    #define VIDEO_PLAY_FMT_NONE                 (0)
+    #define VIDEO_PLAY_FMT_GOP                  (1)
+
+    #define VIDEO_VSYNC_FIELD_UNKNOWN           (0)
+    #define VIDEO_VSYNC_FIELD_ODD               (1)
+    #define VIDEO_VSYNC_FIELD_EVEN              (2)
+    #define VIDEO_VSYNC_FIELD_PROGRESSIVE       (3)
+
+Constants
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  :rspan:`3` _`Decoder command`
+
+       -  ``VIDEO_CMD_PLAY``
+
+       -  Start playback.
+
+    -  ..
+
+       -  ``VIDEO_CMD_STOP``
+
+       -  Stop playback.
+
+    -  ..
+
+       -  ``VIDEO_CMD_FREEZE``
+
+       -  Freeze playback.
+
+    -  ..
+
+       -  ``VIDEO_CMD_CONTINUE``
+
+       -  Continue playback after freeze.
+
+    -  ..
+
+       -  Flags for ``VIDEO_CMD_FREEZE``
+
+       -  ``VIDEO_CMD_FREEZE_TO_BLACK``
+
+       -  Show black picture on freeze.
+
+    -  ..
+
+       -  :rspan:`1` Flags for ``VIDEO_CMD_STOP``
+
+       -  ``VIDEO_CMD_STOP_TO_BLACK``
+
+       -  Show black picture on stop.
+
+    -  ..
+
+       -  ``VIDEO_CMD_STOP_IMMEDIATELY``
+
+       -  Stop immediately, without emptying buffers.
+
+    -  ..
+
+       -  :rspan:`1` _`Play input formats`
+
+       -  ``VIDEO_PLAY_FMT_NONE``
+
+       -  The decoder has no special format requirements
+
+    -  ..
+
+       -  ``VIDEO_PLAY_FMT_GOP``
+
+       -  The decoder requires full GOPs
+
+    -  ..
+
+       -  :rspan:`3` Field order
+
+       -  ``VIDEO_VSYNC_FIELD_UNKNOWN``
+
+       -  FIELD_UNKNOWN can be used if the hardware does not know
+          whether the Vsync is for an odd, even or progressive
+          (i.e. non-interlaced) field.
+
+    -  ..
+
+       -  ``VIDEO_VSYNC_FIELD_ODD``
+
+       -  Vsync is for an odd field.
+
+    -  ..
+
+       -  ``VIDEO_VSYNC_FIELD_EVEN``
+
+       -  Vsync is for an even field.
+
+    -  ..
+
+       -  ``VIDEO_VSYNC_FIELD_PROGRESSIVE``
+
+       -  progressive (i.e. non-interlaced)
+
+
+-----
+
+
+video_event
+-----------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    struct video_event {
+	__s32 type;
+    #define VIDEO_EVENT_SIZE_CHANGED        1
+    #define VIDEO_EVENT_FRAME_RATE_CHANGED  2
+    #define VIDEO_EVENT_DECODER_STOPPED     3
+    #define VIDEO_EVENT_VSYNC               4
+	long timestamp;
+	union {
+	    video_size_t size;
+	    unsigned int frame_rate;
+	    unsigned char vsync_field;
+	} u;
+    };
+
+Variables
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  :rspan:`4` ``__s32 type``
+
+       -  :cspan:`1` Event type.
+
+    -  ..
+
+       -  ``VIDEO_EVENT_SIZE_CHANGED``
+
+       -  Size changed.
+
+    -  ..
+
+       -  ``VIDEO_EVENT_FRAME_RATE_CHANGED``
+
+       -  Framerate changed.
+
+    -  ..
+
+       -  ``VIDEO_EVENT_DECODER_STOPPED``
+
+       -  Decoder stopped.
+
+    -  ..
+
+       -  ``VIDEO_EVENT_VSYNC``
+
+       -  Vsync occurred.
+
+    -  ..
+
+       -  ``long timestamp``
+
+       -  :cspan:`1` MPEG PTS at occurrence.
+
+    -  ..
+
+       -  :rspan:`2` ``union u``
+
+       -  `video_size_t`_ size
+
+       -  Resolution and aspect ratio of the video.
+
+    -  ..
+
+       -  ``unsigned int frame_rate``
+
+       -  in frames per 1000sec
+
+    -  ..
+
+       -  ``unsigned char vsync_field``
+
+       -  | unknown / odd / even / progressive
+          | See: `Predefined decoder commands and flags`_
+
+Description
+~~~~~~~~~~~
+
+This is the structure of a video event as it is returned by the
+`VIDEO_GET_EVENT`_ call. See there for more details.
+
+
+-----
+
+
+video_status
+------------
+
+Synopsis
+~~~~~~~~
+
+The `VIDEO_GET_STATUS`_ call returns the following structure informing
+about various states of the playback operation.
+
+.. code-block:: c
+
+    struct video_status {
+	int                    video_blank;
+	video_play_state_t     play_state;
+	video_stream_source_t  stream_source;
+	video_format_t         video_format;
+	video_displayformat_t  display_format;
+    };
+
+Variables
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  :rspan:`2` ``int video_blank``
+
+       -  :cspan:`1` Show blank video on freeze?
+
+    -  ..
+
+       -  TRUE  ( != 0 )
+
+       -  Blank screen when freeze.
+
+    -  ..
+
+       -  FALSE ( == 0 )
+
+       -  Show last decoded frame.
+
+    -  ..
+
+       -  `video_play_state_t`_ ``play_state``
+
+       -  Current state of playback.
+
+    -  ..
+
+       -  `video_stream_source_t`_ ``stream_source``
+
+       -  Current source (demux/memory).
+
+    -  ..
+
+       -  `video_format_t`_ ``video_format``
+
+       -  Current aspect ratio of stream.
+
+    -  ..
+
+       -  `video_displayformat_t`_ ``display_format``
+
+       -  Applied cropping mode.
+
+Description
+~~~~~~~~~~~
+
+If ``video_blank`` is set ``TRUE`` video will be blanked out if the
+channel is changed or if playback is stopped. Otherwise, the last picture
+will be displayed. ``play_state`` indicates if the video is currently
+frozen, stopped, or being played back. The ``stream_source`` corresponds
+to the selected source for the video stream. It can come either from the
+demultiplexer or from memory. The ``video_format`` indicates the aspect
+ratio (one of 4:3 or 16:9) of the currently played video stream.
+Finally, ``display_format`` corresponds to the applied cropping mode in
+case the source video format is not the same as the format of the output
+device.
+
+
+-----
+
+
+video_still_picture
+-------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    struct video_still_picture {
+    char *iFrame;
+    int32_t size;
+    };
+
+Variables
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``char *iFrame``
+
+       -  Pointer to a single iframe in memory.
+
+    -  ..
+
+       -  ``int32_t size``
+
+       -  Size of the iframe.
+
+
+Description
+~~~~~~~~~~~
+
+An I-frame displayed via the `VIDEO_STILLPICTURE`_ call is passed on
+within this structure.
+
+
+-----
+
+
+video capabilities
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    #define VIDEO_CAP_MPEG1   1
+    #define VIDEO_CAP_MPEG2   2
+    #define VIDEO_CAP_SYS     4
+    #define VIDEO_CAP_PROG    8
+
+Constants
+~~~~~~~~~
+Bit definitions for capabilities:
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``VIDEO_CAP_MPEG1``
+
+       -  :cspan:`1` The hardware can decode MPEG1.
+
+    -  ..
+
+       -  ``VIDEO_CAP_MPEG2``
+
+       -  The hardware can decode MPEG2.
+
+    -  ..
+
+       -  ``VIDEO_CAP_SYS``
+
+       -  The video device accepts system stream.
+
+          You still have to open the video and the audio device
+          but only send the stream to the video device.
+
+    -  ..
+
+       -  ``VIDEO_CAP_PROG``
+
+       -  The video device accepts program stream.
+
+          You still have to open the video and the audio device
+          but only send the stream to the video device.
+
+Description
+~~~~~~~~~~~
+
+A call to `VIDEO_GET_CAPABILITIES`_ returns an unsigned integer with the
+following bits set according to the hardware's capabilities.
--
2.34.0

[PATCH v4 6/6] media: docs: uAPI: dvb/video: completing the documentation (function calls)

[Stefan Herdler]

The existing documentation of the legacy DVB Decoder API was incomplete.

Revising the documentation, adding missing parts and arranging the
documentation files new.

This patch contains the documentation of the function calls defined in
video.h.

Signed-off-by: Stefan Herdler <herdler@nurfuerspam.de>
---

Changes since v3:
* Adjust title and description to better match existing documentation.
* Change reference from :c:enum:`dmx_output` to :c:type: to silence the
  warning from the kernel test robot.

[PATCH v3] ------------------------------------------------------------

Possibly unused:
 struct video_command
 ioctl VIDEO_COMMAND
 ioctl VIDEO_TRY_COMMAND
 ioctl VIDEO_GET_FRAME_COUNT

Out of tree only usage:
 VIDEO_SET_STREAMTYPE



VIDEO_COMMAND:
False positive on AV7110 driver. The driver uses identical symbol names.

The ioctl VIDEO_COMMAND has been introduced 2007 way after the AV7110
driver.
The log says it has been added to support the cx23415 decoder and has
probably never used for enything else.
And AFAIK has the cx23415 decoder been switched to V4L2-API some time ago.



VIDEO_SET_STREAMTYPE:
Used by the "Enigma2" set top boxes only.
Stream type definitions are from there.



>> +VIDEO_GET_EVENT
>> +---------------
[...]
> Same comments as I did for demux event applies here: what happens if
> userspace misses the event?
>
> Btw, this explanation is a lot better than the one at demux. You
> should probably place something like that there too... there is
> block/nonblock mode for the demux event? Do they behave the same?

I'm a little confused here, a demux event doesn't seem to exist any more.
Are you referring to the legacy "dvb_frontend_event"?

I could place some documentation there, but I'm not sure, if it really
applies there too.
Anyway, I have to take a closer look before, but I would like to finish
this files first ;-).



 .../media/dvb/legacy_dvb_video.rst            | 1632 +++++++++++++++++
 1 file changed, 1632 insertions(+)

diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst
index 165fd6005a07..918ef3f84f72 100644
--- a/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst
+++ b/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst
@@ -796,3 +796,1635 @@ Description

 A call to `VIDEO_GET_CAPABILITIES`_ returns an unsigned integer with the
 following bits set according to the hardware's capabilities.
+
+
+-----
+
+
+Video Function Calls
+====================
+
+
+VIDEO_STOP
+----------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_STOP
+
+.. code-block:: c
+
+	int ioctl(fd, VIDEO_STOP, int mode)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  :cspan:`1` Equals ``VIDEO_STOP`` for this command.
+
+    -  ..
+
+       -  :rspan:`2` ``int mode``
+
+       -  :cspan:`1` Indicates how the screen shall be handled.
+
+    -  ..
+
+       -  TRUE  ( != 0 )
+
+       -  Blank screen when stop.
+
+    -  ..
+
+       -  FALSE ( == 0 )
+
+       -  Show last decoded frame.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for Digital TV devices only. To control a V4L2 decoder use
+the V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
+
+This ioctl call asks the Video Device to stop playing the current
+stream. Depending on the input parameter, the screen can be blanked out
+or displaying the last decoded frame.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_PLAY
+----------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_PLAY
+
+.. code-block:: c
+
+	int ioctl(fd, VIDEO_PLAY)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_PLAY`` for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for Digital TV devices only. To control a V4L2 decoder use
+the V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
+
+This ioctl call asks the Video Device to start playing a video stream
+from the selected source.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_FREEZE
+------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_FREEZE
+
+.. code-block:: c
+
+	int ioctl(fd, VIDEO_FREEZE)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_FREEZE`` for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for Digital TV devices only. To control a V4L2 decoder use
+the V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
+
+This ioctl call suspends the live video stream being played, if
+VIDEO_SOURCE_DEMUX is selected. Decoding and playing are frozen.
+It is then possible to restart the decoding and playing process of the
+video stream using the `VIDEO_CONTINUE`_ command.
+If VIDEO_SOURCE_MEMORY is selected in the ioctl call
+`VIDEO_SELECT_SOURCE`_, the Digital TV subsystem will not decode any more
+data until the ioctl call `VIDEO_CONTINUE`_ or `VIDEO_PLAY`_ is performed.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_CONTINUE
+--------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_CONTINUE
+
+.. code-block:: c
+
+	int ioctl(fd, VIDEO_CONTINUE)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_CONTINUE`` for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for Digital TV devices only. To control a V4L2 decoder use
+the V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
+
+This ioctl call restarts decoding and playing processes of the video
+stream which was played before a call to `VIDEO_FREEZE`_ was made.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_SELECT_SOURCE
+-------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_SELECT_SOURCE
+
+.. code-block:: c
+
+	int ioctl(fd, VIDEO_SELECT_SOURCE, video_stream_source_t source)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_SELECT_SOURCE`` for this command.
+
+    -  ..
+
+       -  `video_stream_source_t`_ ``source``
+
+       -  Indicates which source shall be used for the Video stream.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for Digital TV devices only. This ioctl was also supported
+by the V4L2 ivtv driver, but that has been replaced by the ivtv-specific
+``IVTV_IOC_PASSTHROUGH_MODE`` ioctl.
+
+This ioctl call informs the video device which source shall be used for
+the input data. The possible sources are demux or memory. If memory is
+selected, the data is fed to the video device through the write command
+using the struct `video_stream_source_t`_. If demux is selected, the data
+is directly transferred from the onboard demux-device to the decoder.
+
+The data fed to the decoder is also controlled by the PID-filter.
+Output selection: :c:type:`dmx_output` ``DMX_OUT_DECODER``.
+
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_SET_BLANK
+---------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_SET_BLANK
+
+.. code-block:: c
+
+	int ioctl(fd, VIDEO_SET_BLANK, int mode)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  :cspan:`1` Equals ``VIDEO_SET_BLANK`` for this command.
+
+    -  ..
+
+       -  :rspan:`2` ``int mode``
+
+       -  :cspan:`1` Indicates if the screen shall be blanked.
+
+    -  ..
+
+       -  TRUE  ( != 0 )
+
+       -  Blank screen when stop.
+
+    -  ..
+
+       -  FALSE ( == 0 )
+
+       -  Show last decoded frame.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Video Device to blank out the picture.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_GET_STATUS
+----------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_GET_STATUS
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_GET_STATUS,
+	struct video_status *status)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_GET_STATUS`` for this command.
+
+    -  ..
+
+       -  ``struct`` `video_status`_ ``*status``
+
+       -  Returns the current status of the Video Device.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Video Device to return the current status of
+the device.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_GET_EVENT
+---------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_GET_EVENT
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_GET_EVENT,
+	struct video_event *ev)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_GET_EVENT`` for this command.
+
+    -  ..
+
+       -  ``struct`` `video_event`_ ``*ev``
+
+       -  Points to the location where the event, if any, is to be stored.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is for DVB devices only. To get events from a V4L2 decoder
+use the V4L2 :ref:`VIDIOC_DQEVENT` ioctl instead.
+
+This ioctl call returns an event of type `video_event`_ if available. A
+certain number of the latest events will be cued and returned in order of
+occurrence. Older events may be discarded if not fetched in time. If
+an event is not available, the behavior depends on whether the device is
+in blocking or non-blocking mode. In the latter case, the call fails
+immediately with errno set to ``EWOULDBLOCK``. In the former case, the
+call blocks until an event becomes available. The standard Linux poll()
+and/or select() system calls can be used with the device file descriptor
+to watch for new events. For select(), the file descriptor should be
+included in the exceptfds argument, and for poll(), POLLPRI should be
+specified as the wake-up condition. Read-only permissions are sufficient
+for this ioctl call.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``EWOULDBLOCK``
+
+       -  :cspan:`1` There is no event pending, and the device is in
+          non-blocking mode.
+
+    -  ..
+
+       -  ``EOVERFLOW``
+
+       -  Overflow in event queue - one or more events were lost.
+
+
+-----
+
+
+VIDEO_SET_DISPLAY_FORMAT
+------------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_SET_DISPLAY_FORMAT
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_SET_DISPLAY_FORMAT,
+	video_display_format_t format)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_SET_DISPLAY_FORMAT`` for this command.
+
+    -  ..
+
+       -  `video_displayformat_t`_ ``format``
+
+       -  Selects the video format to be used.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Video Device to select the video format to be
+applied by the MPEG chip on the video.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_STILLPICTURE
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_STILLPICTURE
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_STILLPICTURE,
+	struct video_still_picture *sp)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_STILLPICTURE`` for this command.
+
+    -  ..
+
+       -  ``struct`` `video_still_picture`_ ``*sp``
+
+       -  Pointer to the location where the struct with the I-frame
+          and size is stored.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Video Device to display a still picture
+(I-frame). The input data shall be the section of an elementary video
+stream containing an I-frame. Typically this section is extracted from a
+TS or PES recording. Resolution and codec (see `video capabilities`_) must
+be supported by the device. If the pointer is NULL, then the current
+displayed still picture is blanked.
+
+e.g. The AV7110 supports MPEG1 and MPEG2 with the common PAL-SD
+resolutions.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_FAST_FORWARD
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_FAST_FORWARD
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_FAST_FORWARD, int nFrames)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_FAST_FORWARD`` for this command.
+
+    -  ..
+
+       -  ``int nFrames``
+
+       -  The number of frames to skip.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the Video Device to skip decoding of N number of
+I-frames. This call can only be used if ``VIDEO_SOURCE_MEMORY`` is
+selected.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``EPERM``
+
+       -  Mode ``VIDEO_SOURCE_MEMORY`` not selected.
+
+
+-----
+
+
+VIDEO_SLOWMOTION
+----------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_SLOWMOTION
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_SLOWMOTION, int nFrames)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_SLOWMOTION`` for this command.
+
+    -  ..
+
+       -  ``int nFrames``
+
+       -  The number of times to repeat each frame.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the video device to repeat decoding frames N number
+of times. This call can only be used if ``VIDEO_SOURCE_MEMORY`` is
+selected.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``EPERM``
+
+       -  Mode ``VIDEO_SOURCE_MEMORY`` not selected.
+
+
+-----
+
+
+VIDEO_GET_CAPABILITIES
+----------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_GET_CAPABILITIES
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_GET_CAPABILITIES, unsigned int *cap)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_GET_CAPABILITIES`` for this command.
+
+    -  ..
+
+       -  ``unsigned int *cap``
+
+       -  Pointer to a location where to store the capability information.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call asks the video device about its decoding capabilities.
+On success it returns an integer which has bits set according to the
+defines in `video capabilities`_.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_CLEAR_BUFFER
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_CLEAR_BUFFER
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_CLEAR_BUFFER)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_CLEAR_BUFFER`` for this command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl call clears all video buffers in the driver and in the
+decoder hardware.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_SET_STREAMTYPE
+--------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_SET_STREAMTYPE
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_SET_STREAMTYPE, int type)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_SET_STREAMTYPE`` for this command.
+
+    -  ..
+
+       -  ``int type``
+
+       -  Stream type.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl tells the driver which kind of stream to expect being written
+to it.
+Intelligent decoder might also not support or ignore (like the AV7110)
+this call and determine the stream type themselves.
+
+Currently used stream types:
+
+.. flat-table::
+    :header-rows:  1
+    :stub-columns: 0
+
+    -  ..
+
+       -  Codec
+
+       -  Stream type
+
+    -  ..
+
+       -  MPEG2
+
+       -  0
+
+    -  ..
+
+       -  MPEG4 h.264
+
+       -  1
+
+    -  ..
+
+       -  VC1
+
+       -  3
+
+    -  ..
+
+       -  MPEG4 Part2
+
+       -  4
+
+    -  ..
+
+       -  VC1 SM
+
+       -  5
+
+    -  ..
+
+       -  MPEG1
+
+       -  6
+
+    -  ..
+
+       -  HEVC h.265
+
+       -  | 7
+          | DREAMBOX: 22
+
+    -  ..
+
+       -  AVS
+
+       -  16
+
+    -  ..
+
+       -  AVS2
+
+       -  40
+
+Not every decoder supports all stream types.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_SET_FORMAT
+----------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_SET_FORMAT
+
+.. code-block:: c
+
+	int ioctl(fd, int request = VIDEO_SET_FORMAT, video_format_t format)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_SET_FORMAT`` for this command.
+
+    -  ..
+
+       -  `video_format_t`_ ``format``
+
+       -  Video format of TV as defined in section `video_format_t`_.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl sets the screen format (aspect ratio) of the connected output
+device (TV) so that the output of the decoder can be adjusted
+accordingly.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_GET_SIZE
+--------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_GET_SIZE
+
+.. code-block:: c
+
+	int ioctl(int fd, int request = VIDEO_GET_SIZE, video_size_t *size)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call,
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_GET_SIZE`` for this command.
+
+    -  ..
+
+       -  `video_size_t`_ ``*size``
+
+       -  Returns the size and aspect ratio.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl returns the size and aspect ratio.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_GET_PTS
+-------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_GET_PTS
+
+.. code-block:: c
+
+	int ioctl(int fd, int request = VIDEO_GET_PTS, __u64 *pts)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_GET_PTS`` for this command.
+
+    -  ..
+
+       -  ``__u64 *pts``
+
+       -  Returns the 33-bit timestamp as defined in ITU T-REC-H.222.0 /
+          ISO/IEC 13818-1.
+
+          The PTS should belong to the currently played frame if possible,
+          but may also be a value close to it like the PTS of the last
+          decoded frame or the last PTS extracted by the PES parser.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+For V4L2 decoders this ioctl has been replaced by the
+``V4L2_CID_MPEG_VIDEO_DEC_PTS`` control.
+
+This ioctl call asks the Video Device to return the current PTS
+timestamp.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_GET_FRAME_COUNT
+---------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_GET_FRAME_COUNT
+
+.. code-block:: c
+
+	int ioctl(int fd, VIDEO_GET_FRAME_COUNT, __u64 *pts)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_GET_FRAME_COUNT`` for this command.
+
+    -  ..
+
+       -  ``__u64 *pts``
+
+       -  Returns the number of frames displayed since the decoder was
+          started.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+For V4L2 decoders this ioctl has been replaced by the
+``V4L2_CID_MPEG_VIDEO_DEC_FRAME`` control.
+
+This ioctl call asks the Video Device to return the number of displayed
+frames since the decoder was started.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_COMMAND
+-------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_COMMAND
+
+.. code-block:: c
+
+	int ioctl(int fd, int request = VIDEO_COMMAND,
+	struct video_command *cmd)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_COMMAND`` for this command.
+
+    -  ..
+
+       -  `struct video_command`_ ``*cmd``
+
+       -  Commands the decoder.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+For V4L2 decoders this ioctl has been replaced by the
+:ref:`VIDIOC_DECODER_CMD` ioctl.
+
+This ioctl commands the decoder. The `struct video_command`_ is a
+subset of the ``v4l2_decoder_cmd`` struct, so refer to the
+:ref:`VIDIOC_DECODER_CMD` documentation for
+more information.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+VIDEO_TRY_COMMAND
+-----------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: VIDEO_TRY_COMMAND
+
+.. code-block:: c
+
+	int ioctl(int fd, int request = VIDEO_TRY_COMMAND,
+	struct video_command *cmd)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``int request``
+
+       -  Equals ``VIDEO_TRY_COMMAND`` for this command.
+
+    -  ..
+
+       -  `struct video_command`_ ``*cmd``
+
+       -  Try a decoder command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+             See: :ref:`legacy_dvb_decoder_notes`
+
+For V4L2 decoders this ioctl has been replaced by the
+:ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` ioctl.
+
+This ioctl tries a decoder command. The `struct video_command`_ is a
+subset of the ``v4l2_decoder_cmd`` struct, so refer to the
+:ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` documentation
+for more information.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+-----
+
+
+open()
+------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+    #include <fcntl.h>
+
+.. c:function:: 	int open(const char *deviceName, int flags)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``const char *deviceName``
+
+       -  Name of specific video device.
+
+    -  ..
+
+       -  :rspan:`3` ``int flags``
+
+       -  :cspan:`1` A bit-wise OR of the following flags:
+
+    -  ..
+
+       -  ``O_RDONLY``
+
+       -  read-only access
+
+    -  ..
+
+       -  ``O_RDWR``
+
+       -  read/write access
+
+    -  ..
+
+       -  ``O_NONBLOCK``
+       -  | Open in non-blocking mode
+          | (blocking mode is the default)
+
+Description
+~~~~~~~~~~~
+
+This system call opens a named video device (e.g.
+/dev/dvb/adapter?/video?) for subsequent use.
+
+When an open() call has succeeded, the device will be ready for use. The
+significance of blocking or non-blocking mode is described in the
+documentation for functions where there is a difference. It does not
+affect the semantics of the open() call itself. A device opened in
+blocking mode can later be put into non-blocking mode (and vice versa)
+using the F_SETFL command of the fcntl system call. This is a standard
+system call, documented in the Linux manual page for fcntl. Only one
+user can open the Video Device in O_RDWR mode. All other attempts to
+open the device in this mode will fail, and an error-code will be
+returned. If the Video Device is opened in O_RDONLY mode, the only
+ioctl call that can be used is `VIDEO_GET_STATUS`_. All other call will
+return an error code.
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``ENODEV``
+
+       -  :cspan:`1` Device driver not loaded/available.
+
+    -  ..
+
+       -  ``EINTERNAL``
+
+       -  Internal error.
+
+    -  ..
+
+       -  ``EBUSY``
+
+       -  Device or resource busy.
+
+    -  ..
+
+       -  ``EINVAL``
+
+       -  Invalid argument.
+
+
+-----
+
+
+close()
+-------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: 	int close(int fd)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+Description
+~~~~~~~~~~~
+
+This system call closes a previously opened video device.
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``EBADF``
+
+       -  fd is not a valid open file descriptor.
+
+
+-----
+
+
+write()
+-------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: size_t write(int fd, const void *buf, size_t count)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``int fd``
+
+       -  :cspan:`1` File descriptor returned by a previous call
+          to `open()`_.
+
+    -  ..
+
+       -  ``void *buf``
+
+       -  Pointer to the buffer containing the PES data.
+
+    -  ..
+
+       -  ``size_t count``
+
+       -  Size of buf.
+
+Description
+~~~~~~~~~~~
+
+This system call can only be used if VIDEO_SOURCE_MEMORY is selected
+in the ioctl call `VIDEO_SELECT_SOURCE`_. The data provided shall be in
+PES format, unless the capability allows other formats. TS is the
+most common format for storing DVB-data, it is usually supported too.
+If O_NONBLOCK is not specified the function will block until buffer space
+is available. The amount of data to be transferred is implied by count.
+
+.. note:: See: :ref:`DVB Data Formats <legacy_dvb_decoder_formats>`
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  ..
+
+       -  ``EPERM``
+
+       -  :cspan:`1` Mode ``VIDEO_SOURCE_MEMORY`` not selected.
+
+    -  ..
+
+       -  ``ENOMEM``
+
+       -  Attempted to write more data than the internal buffer can hold.
+
+    -  ..
+
+       -  ``EBADF``
+
+       -  fd is not a valid open file descriptor.
--
2.34.0

Re: [PATCH v4 0/6] media: docs: uAPI: dvb/decoder: completing the documentation

[Mauro Carvalho Chehab]

Hi Stefan,

Em Mon, 29 Jan 2024 00:32:43 +0100
Stefan Herdler <herdler@nurfuerspam.de> escreveu:

> This is basically a resend of v3 after 6 month, with some minor updates.
> Changes since v3:
> * Adjust title and description to better match existing documentation.
> * Fix warnings from kernel test robot.
>   (At least I hope it is fixed now, I couldn't reproduce this warning.)
> 
> No changes to the text it self.
> The layout is still identical since v1, just split into multiple patches.
> My comments of v3 attached below, they refer to Mauros comments[3] to
> v2 and still fully apply.

Patch series applied. I opted to reorder the series placing patch 1 at the
end, as otherwise it would cause bisect issues, as the index would be
trying to reference non-existing files.

Thank you for the series!

Regards,
Mauro


> 
> [3: https://patchwork.kernel.org/project/linux-media/patch/decd5d71-f06e-5873-5ebf-7028107f65ee@nurfuerspam.de/]
> 
> 
> [PATCH v3] (July '23) ---------------------------------------------------
> 
> Changes since v2:
> * Split the patch into a patch series.
> * Incorporate the changes requested.
> * Style updates to better match the existing documentation.
> * And a lot of small fixes.
> 
> 
> Hi Mauro,
> 
> it took a little longer then expected, but I didn't had much time in spare
> for this. I'm pretty much occupied by other things at the moment.
> The winter season would be better for things like this, but I try to
> finish it as quick as possible.
> 
> I went through your mail point by point and I'm confident, that I was able
> to sort out your questions now. At least I don't see anything that need to
> be improved anymore.
> The work has been done in a lot of small blocks over a pretty long period
> after my daily work, mostly late at night. Despite double checking
> everything, I maybe still have missed something. I hope it is not too
> much.
> 
> For usage it has been checked against the known projects using the DVB
> decoder APIs:
> * The AV7110 kernel driver.
> * The out of tree driver for the HD full featured cards.[1]
> * The "Enigma2" sources from openatv team.[2]
>   (The drivers of the boxes are binary only.)
> 
> Possibly unused items have been listed in the comment of the patches.
> Please take this lists with a pinch of salt. With the number of items
> checked, it is pretty easy to miss an occurrence or have a false positive.
> Although I've done my best, there is still the chance that I've missed an
> use case.
> 
> I tried to complete the documentation of this unused definition too.
> Most information had been collect anyway and writing it down wasn't that
> much of effort.
> 
> Removing the definition and documentation later at once is always an
> option.
> I would prefer to do it this way, if something has to be removed.
> It is easier to revert the change in case of a regression.
> If necessary I can provide the patches too.
> 
> Regards
> Stefan
> 
> [1: https://github.com/s-moch/linux-saa716x]
> [2: https://github.com/openatv/enigma2/tree/master]
> 
> 
> 
> Stefan Herdler (6):
>   Add documentation for legacy DVB decoder API
>   Add documentation for osd.h
>   Add documentation for audio.h (data types)
>   Add documentation for audio.h (function calls)
>   Add documentation for video.h (data types)
>   Add documentation for video.h (function calls)
> 
>  .../media/dvb/legacy_dvb_apis.rst             |    1 +
>  .../media/dvb/legacy_dvb_audio.rst            | 1642 +++++++++++
>  .../media/dvb/legacy_dvb_decoder_api.rst      |   61 +
>  .../media/dvb/legacy_dvb_osd.rst              |  883 ++++++
>  .../media/dvb/legacy_dvb_video.rst            | 2430 +++++++++++++++++
>  5 files changed, 5017 insertions(+)
>  create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst
>  create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst
>  create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst
>  create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_video.rst
> 
> --
> 2.34.0
> 
> 



Thanks,
Mauro

Re: [PATCH v4 0/6] media: docs: uAPI: dvb/decoder: completing the documentation

[Stefan Herdler]

Hi Mauro,

On 07/02/24 06:10 Mauro Carvalho Chehab wrote:
> Hi Stefan,
>
> Em Mon, 29 Jan 2024 00:32:43 +0100
> Stefan Herdler <herdler@nurfuerspam.de> escreveu:
>
>> This is basically a resend of v3 after 6 month, with some minor updates.
>> Changes since v3:
>> * Adjust title and description to better match existing documentation.
>> * Fix warnings from kernel test robot.
>>   (At least I hope it is fixed now, I couldn't reproduce this warning.)
>>
>> No changes to the text it self.
>> The layout is still identical since v1, just split into multiple patches.
>> My comments of v3 attached below, they refer to Mauros comments[3] to
>> v2 and still fully apply.
>
> Patch series applied. I opted to reorder the series placing patch 1 at the
> end, as otherwise it would cause bisect issues, as the index would be
> trying to reference non-existing files.

To reorder makes perfectly sense to me.
Somehow I overlooked it all the time.
Thanks for fixing :-).

I'm glad, that it was the only thing I messed up, I expected much more.
This hole process is still a learning experience for me.
Thank you again, for your feedback, hints and patience.


Regards,
Stefan

>
> Thank you for the series!
>
> Regards,
> Mauro
>
>
>>
>> [3: https://patchwork.kernel.org/project/linux-media/patch/decd5d71-f06e-5873-5ebf-7028107f65ee@nurfuerspam.de/]
>>
>>
>> [PATCH v3] (July '23) ---------------------------------------------------
>>
>> Changes since v2:
>> * Split the patch into a patch series.
>> * Incorporate the changes requested.
>> * Style updates to better match the existing documentation.
>> * And a lot of small fixes.
>>
>>
>> Hi Mauro,
>>
>> it took a little longer then expected, but I didn't had much time in spare
>> for this. I'm pretty much occupied by other things at the moment.
>> The winter season would be better for things like this, but I try to
>> finish it as quick as possible.
>>
>> I went through your mail point by point and I'm confident, that I was able
>> to sort out your questions now. At least I don't see anything that need to
>> be improved anymore.
>> The work has been done in a lot of small blocks over a pretty long period
>> after my daily work, mostly late at night. Despite double checking
>> everything, I maybe still have missed something. I hope it is not too
>> much.
>>
>> For usage it has been checked against the known projects using the DVB
>> decoder APIs:
>> * The AV7110 kernel driver.
>> * The out of tree driver for the HD full featured cards.[1]
>> * The "Enigma2" sources from openatv team.[2]
>>   (The drivers of the boxes are binary only.)
>>
>> Possibly unused items have been listed in the comment of the patches.
>> Please take this lists with a pinch of salt. With the number of items
>> checked, it is pretty easy to miss an occurrence or have a false positive.
>> Although I've done my best, there is still the chance that I've missed an
>> use case.
>>
>> I tried to complete the documentation of this unused definition too.
>> Most information had been collect anyway and writing it down wasn't that
>> much of effort.
>>
>> Removing the definition and documentation later at once is always an
>> option.
>> I would prefer to do it this way, if something has to be removed.
>> It is easier to revert the change in case of a regression.
>> If necessary I can provide the patches too.
>>
>> Regards
>> Stefan
>>
>> [1: https://github.com/s-moch/linux-saa716x]
>> [2: https://github.com/openatv/enigma2/tree/master]
>>
>>
>>
>> Stefan Herdler (6):
>>   Add documentation for legacy DVB decoder API
>>   Add documentation for osd.h
>>   Add documentation for audio.h (data types)
>>   Add documentation for audio.h (function calls)
>>   Add documentation for video.h (data types)
>>   Add documentation for video.h (function calls)
>>
>>  .../media/dvb/legacy_dvb_apis.rst             |    1 +
>>  .../media/dvb/legacy_dvb_audio.rst            | 1642 +++++++++++
>>  .../media/dvb/legacy_dvb_decoder_api.rst      |   61 +
>>  .../media/dvb/legacy_dvb_osd.rst              |  883 ++++++
>>  .../media/dvb/legacy_dvb_video.rst            | 2430 +++++++++++++++++
>>  5 files changed, 5017 insertions(+)
>>  create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst
>>  create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst
>>  create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst
>>  create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_video.rst
>>
>> --
>> 2.34.0
>>
>>
>
>
>
> Thanks,
> Mauro