subject:"\[PATCH v2 00\/26\] Improve DVB documentation and reduce its gap"

Re: [PATCH v2 00/26] Improve DVB documentation and reduce its gap

2017-09-04 Thread Mauro Carvalho Chehab

Em Mon, 4 Sep 2017 11:40:59 +0200
Honza Petrouš  escreveu:

> > So, IMHO, the interface is broken by design. Perhaps that's
> > the reason why no upstream driver uses it.  
> 
> I have the same feeling regarding brokenness.
> 
> >
> > What seems to be a much better design would be to use the demux
> > set filter ioctls and route the PIDs to the right CA.
> >  
> 
> I don't have access to any programmer reference documentation
> for any modern DVB-enabled SoC, but I see two possible scenario
> of connecting descramblers to the demuxes (most of modern SoCs
> have more then one demux) - static one, when every demux has
> predefined descramblers already connected to it and dynamic ones,
> when any descrambler can be connected to the any demux.

I don't have access to the documentation either, but I know
some designs that have multiple demods that are dynamically set.
Some hardware even allow to dynamically change the maximum amount
of filters per demod at runtime.

> From that reason I vote to have some descrambler specific ioctl,
> which allow more flexibility then if we add it to the filter set ioctl.

I suspect that doing it at the demod does a lot more sense.

Anyway, someone should come with a driver requiring it upstream
for us to discuss and find the better alternatives to support.

Thanks,
Mauro

Re: [PATCH v2 00/26] Improve DVB documentation and reduce its gap

2017-09-04 Thread Honza Petrouš

2017-09-04 11:06 GMT+02:00 Mauro Carvalho Chehab :
> Em Mon, 4 Sep 2017 09:12:49 +0200
> Honza Petrouš  escreveu:
>
>> 2017-09-04 2:54 GMT+02:00 Mauro Carvalho Chehab :
>> > Em Sun, 3 Sep 2017 22:05:23 +0200
>> > Honza Petrouš  escreveu:
>> >
>> >> 1) #define CA_SET_DESCR  _IOW('o', 134, ca_descr_t)
>> >> 
>> >>
>> >> CA_SET_DESCR is used for feeding descrambler device
>> >> with correct keys (called here "control words") what
>> >> allows to get services unscrambled.
>> >>
>> >> The best docu is:
>> >>
>> >> "Digital Video Broadcasting (DVB);
>> >> Support for use of the DVB Scrambling Algorithm version 3
>> >> within digital broadcasting systems"
>> >>
>> >> Defined as DVB Document A125 and publicly
>> >> available here:
>> >>
>> >> https://www.dvb.org/resources/public/standards/a125_dvb-csa3.pdf
>> >>
>> >>
>> >> typedef struct ca_descr {
>> >> unsigned int index;
>> >> unsigned int parity;/* 0 == even, 1 == odd */
>> >> unsigned char cw[8];
>> >> } ca_descr_t;
>> >>
>> >> The 'index' is adress of the descrambler instance, as there exist
>> >> limited number of them (retieved by CA_GET_DESCR_INFO).
>> >
>> > Thanks for the info. If I understood well, the enclosed patch should
>> > be documenting it.
>> >
>> >
>> > Thanks,
>> > Mauro
>> >
>> > [PATCH] media: ca docs: document CA_SET_DESCR ioctl and structs
>> >
>> > The av7110 driver uses CA_SET_DESCR to store the descrambler
>> > control words at the CA descrambler slots.
>> >
>> > Document it.
>> >
>> > Thanks-to: Honza Petrouš 
>> > Signed-off-by: Mauro Carvalho Chehab 
>> >
>> > diff --git a/Documentation/media/uapi/dvb/ca-set-descr.rst 
>> > b/Documentation/media/uapi/dvb/ca-set-descr.rst
>> > index 9c484317d55c..a6c47205ffd8 100644
>> > --- a/Documentation/media/uapi/dvb/ca-set-descr.rst
>> > +++ b/Documentation/media/uapi/dvb/ca-set-descr.rst
>> > @@ -28,22 +28,11 @@ Arguments
>> >  ``msg``
>> >Pointer to struct :c:type:`ca_descr`.
>> >
>> > -.. c:type:: ca_descr
>> > -
>> > -.. code-block:: c
>> > -
>> > -struct ca_descr {
>> > -   unsigned int index;
>> > -   unsigned int parity;
>> > -   unsigned char cw[8];
>> > -};
>> > -
>> > -
>> >  Description
>> >  ---
>> >
>> > -.. note:: This ioctl is undocumented. Documentation is welcome.
>> > -
>> > +CA_SET_DESCR is used for feeding descrambler CA slots with descrambling
>> > +keys (refered as control words).
>> >
>> >  Return Value
>> >  
>> > diff --git a/include/uapi/linux/dvb/ca.h b/include/uapi/linux/dvb/ca.h
>> > index f66ed53f4dc7..a62ddf0cebcd 100644
>> > --- a/include/uapi/linux/dvb/ca.h
>> > +++ b/include/uapi/linux/dvb/ca.h
>> > @@ -109,9 +109,16 @@ struct ca_msg {
>> > unsigned char msg[256];
>> >  };
>> >
>> > +/**
>> > + * struct ca_descr - CA descrambler control words info
>> > + *
>> > + * @index: CA Descrambler slot
>> > + * @parity: control words parity, where 0 means even and 1 means odd
>> > + * @cw: CA Descrambler control words
>> > + */
>> >  struct ca_descr {
>> > unsigned int index;
>> > -   unsigned int parity;/* 0 == even, 1 == odd */
>> > +   unsigned int parity;
>> > unsigned char cw[8];
>> >  };
>> >
>> >
>>
>> Yeh, it should be that way.
>
> Good! I'll add this patch to the series.
>
>> BTW, the only issue I have in mind is how to link particular
>> descrambler with the PID
>> after your removal of the CA_SET_PID. And yes, I know that currently we have
>> no any user of such ioctl in our driver base :)
>
> Well, I don't think that an ioctl like CA_SET_PID would solve it.
>
> On a generic case with is quite common nowadays on embedded hardware,
> We have K demods and M CIs (where K may be different than M).
>
> Also, You may need to route N PIDs to O descramblers.

TBH that is exactly most common use-case = most Digital TV
vendors are scrambling per-service, what requires one descrambler
for all scrambled PIDs (usually only A/V PIDs are scrambled)
for particular service. So we have to add more PIDs to one descrambler

What was possible by multiple call of CA_SET_PID (I agree that much
better would be name like CA_ADD_PID)
>
> As user switch channels, the N PIDs should be unset, and another
> set of N' pids will be routed.
>
> CA_SET_PID allows to set just one PID, without identifying from
> what demod it would be received, and doesn't have a "reset"
> function to undo.

Here I can agree - it looks like the value -1 in 'index' should
do the job, but it, unfortunately, looses info from which descrambler
it should be removed (see note in struct ca_pid for value -1)

>
> So, IMHO, the interface is broken by design. Perhaps that's
> the reason why no upstream driver uses it.

I have the same feeling regarding brokenness.

>
> What seems to be a much better design would be to use the

Re: [PATCH v2 00/26] Improve DVB documentation and reduce its gap

2017-09-04 Thread Mauro Carvalho Chehab

Em Mon, 4 Sep 2017 09:12:49 +0200
Honza Petrouš  escreveu:

> 2017-09-04 2:54 GMT+02:00 Mauro Carvalho Chehab :
> > Em Sun, 3 Sep 2017 22:05:23 +0200
> > Honza Petrouš  escreveu:
> >  
> >> 1) #define CA_SET_DESCR  _IOW('o', 134, ca_descr_t)
> >> 
> >>
> >> CA_SET_DESCR is used for feeding descrambler device
> >> with correct keys (called here "control words") what
> >> allows to get services unscrambled.
> >>
> >> The best docu is:
> >>
> >> "Digital Video Broadcasting (DVB);
> >> Support for use of the DVB Scrambling Algorithm version 3
> >> within digital broadcasting systems"
> >>
> >> Defined as DVB Document A125 and publicly
> >> available here:
> >>
> >> https://www.dvb.org/resources/public/standards/a125_dvb-csa3.pdf
> >>
> >>
> >> typedef struct ca_descr {
> >> unsigned int index;
> >> unsigned int parity;/* 0 == even, 1 == odd */
> >> unsigned char cw[8];
> >> } ca_descr_t;
> >>
> >> The 'index' is adress of the descrambler instance, as there exist
> >> limited number of them (retieved by CA_GET_DESCR_INFO).  
> >
> > Thanks for the info. If I understood well, the enclosed patch should
> > be documenting it.
> >
> >
> > Thanks,
> > Mauro
> >
> > [PATCH] media: ca docs: document CA_SET_DESCR ioctl and structs
> >
> > The av7110 driver uses CA_SET_DESCR to store the descrambler
> > control words at the CA descrambler slots.
> >
> > Document it.
> >
> > Thanks-to: Honza Petrouš 
> > Signed-off-by: Mauro Carvalho Chehab 
> >
> > diff --git a/Documentation/media/uapi/dvb/ca-set-descr.rst 
> > b/Documentation/media/uapi/dvb/ca-set-descr.rst
> > index 9c484317d55c..a6c47205ffd8 100644
> > --- a/Documentation/media/uapi/dvb/ca-set-descr.rst
> > +++ b/Documentation/media/uapi/dvb/ca-set-descr.rst
> > @@ -28,22 +28,11 @@ Arguments
> >  ``msg``
> >Pointer to struct :c:type:`ca_descr`.
> >
> > -.. c:type:: ca_descr
> > -
> > -.. code-block:: c
> > -
> > -struct ca_descr {
> > -   unsigned int index;
> > -   unsigned int parity;
> > -   unsigned char cw[8];
> > -};
> > -
> > -
> >  Description
> >  ---
> >
> > -.. note:: This ioctl is undocumented. Documentation is welcome.
> > -
> > +CA_SET_DESCR is used for feeding descrambler CA slots with descrambling
> > +keys (refered as control words).
> >
> >  Return Value
> >  
> > diff --git a/include/uapi/linux/dvb/ca.h b/include/uapi/linux/dvb/ca.h
> > index f66ed53f4dc7..a62ddf0cebcd 100644
> > --- a/include/uapi/linux/dvb/ca.h
> > +++ b/include/uapi/linux/dvb/ca.h
> > @@ -109,9 +109,16 @@ struct ca_msg {
> > unsigned char msg[256];
> >  };
> >
> > +/**
> > + * struct ca_descr - CA descrambler control words info
> > + *
> > + * @index: CA Descrambler slot
> > + * @parity: control words parity, where 0 means even and 1 means odd
> > + * @cw: CA Descrambler control words
> > + */
> >  struct ca_descr {
> > unsigned int index;
> > -   unsigned int parity;/* 0 == even, 1 == odd */
> > +   unsigned int parity;
> > unsigned char cw[8];
> >  };
> >
> >  
> 
> Yeh, it should be that way.

Good! I'll add this patch to the series.

> BTW, the only issue I have in mind is how to link particular
> descrambler with the PID
> after your removal of the CA_SET_PID. And yes, I know that currently we have
> no any user of such ioctl in our driver base :)

Well, I don't think that an ioctl like CA_SET_PID would solve it.

On a generic case with is quite common nowadays on embedded hardware,
We have K demods and M CIs (where K may be different than M).

Also, You may need to route N PIDs to O descramblers.

As user switch channels, the N PIDs should be unset, and another
set of N' pids will be routed.

CA_SET_PID allows to set just one PID, without identifying from
what demod it would be received, and doesn't have a "reset" 
function to undo.

So, IMHO, the interface is broken by design. Perhaps that's
the reason why no upstream driver uses it.

What seems to be a much better design would be to use the demux
set filter ioctls and route the PIDs to the right CA.


Thanks,
Mauro

Re: [PATCH v2 00/26] Improve DVB documentation and reduce its gap

2017-09-04 Thread Honza Petrouš

2017-09-04 2:54 GMT+02:00 Mauro Carvalho Chehab :
> Em Sun, 3 Sep 2017 22:05:23 +0200
> Honza Petrouš  escreveu:
>
>> 1) #define CA_SET_DESCR  _IOW('o', 134, ca_descr_t)
>> 
>>
>> CA_SET_DESCR is used for feeding descrambler device
>> with correct keys (called here "control words") what
>> allows to get services unscrambled.
>>
>> The best docu is:
>>
>> "Digital Video Broadcasting (DVB);
>> Support for use of the DVB Scrambling Algorithm version 3
>> within digital broadcasting systems"
>>
>> Defined as DVB Document A125 and publicly
>> available here:
>>
>> https://www.dvb.org/resources/public/standards/a125_dvb-csa3.pdf
>>
>>
>> typedef struct ca_descr {
>> unsigned int index;
>> unsigned int parity;/* 0 == even, 1 == odd */
>> unsigned char cw[8];
>> } ca_descr_t;
>>
>> The 'index' is adress of the descrambler instance, as there exist
>> limited number of them (retieved by CA_GET_DESCR_INFO).
>
> Thanks for the info. If I understood well, the enclosed patch should
> be documenting it.
>
>
> Thanks,
> Mauro
>
> [PATCH] media: ca docs: document CA_SET_DESCR ioctl and structs
>
> The av7110 driver uses CA_SET_DESCR to store the descrambler
> control words at the CA descrambler slots.
>
> Document it.
>
> Thanks-to: Honza Petrouš 
> Signed-off-by: Mauro Carvalho Chehab 
>
> diff --git a/Documentation/media/uapi/dvb/ca-set-descr.rst 
> b/Documentation/media/uapi/dvb/ca-set-descr.rst
> index 9c484317d55c..a6c47205ffd8 100644
> --- a/Documentation/media/uapi/dvb/ca-set-descr.rst
> +++ b/Documentation/media/uapi/dvb/ca-set-descr.rst
> @@ -28,22 +28,11 @@ Arguments
>  ``msg``
>Pointer to struct :c:type:`ca_descr`.
>
> -.. c:type:: ca_descr
> -
> -.. code-block:: c
> -
> -struct ca_descr {
> -   unsigned int index;
> -   unsigned int parity;
> -   unsigned char cw[8];
> -};
> -
> -
>  Description
>  ---
>
> -.. note:: This ioctl is undocumented. Documentation is welcome.
> -
> +CA_SET_DESCR is used for feeding descrambler CA slots with descrambling
> +keys (refered as control words).
>
>  Return Value
>  
> diff --git a/include/uapi/linux/dvb/ca.h b/include/uapi/linux/dvb/ca.h
> index f66ed53f4dc7..a62ddf0cebcd 100644
> --- a/include/uapi/linux/dvb/ca.h
> +++ b/include/uapi/linux/dvb/ca.h
> @@ -109,9 +109,16 @@ struct ca_msg {
> unsigned char msg[256];
>  };
>
> +/**
> + * struct ca_descr - CA descrambler control words info
> + *
> + * @index: CA Descrambler slot
> + * @parity: control words parity, where 0 means even and 1 means odd
> + * @cw: CA Descrambler control words
> + */
>  struct ca_descr {
> unsigned int index;
> -   unsigned int parity;/* 0 == even, 1 == odd */
> +   unsigned int parity;
> unsigned char cw[8];
>  };
>
>

Yeh, it should be that way.

BTW, the only issue I have in mind is how to link particular
descrambler with the PID
after your removal of the CA_SET_PID. And yes, I know that currently we have
no any user of such ioctl in our driver base :)

/Honza

Re: [PATCH v2 00/26] Improve DVB documentation and reduce its gap

2017-09-03 Thread Mauro Carvalho Chehab

Em Sun, 3 Sep 2017 22:05:23 +0200
Honza Petrouš  escreveu:

> > There is still a gap at the CA API, as there are three ioctls that are used
> > only by a few drivers and whose structs are not properly documented:
> > CA_GET_MSG, CA_SEND_MSG and CA_SET_DESCR.
> >
> > The first two ones seem to be related to a way that a few drivers
> > provide to send/receive messages.  
> 
> I never seen usage of such R/W ioctls, all drivers I have access to
> are using read()/write() variant of communication.

Yeah, the normal usage is to use R/W syscalls.

> BTW, I just remembered dvblast app, part of videolan.org:
> 
> http://www.videolan.org/projects/dvblast.html
> 
> which is using CA_GET_MSG/CA_SEND_MSG:
> 
> https://code.videolan.org/videolan/dvblast/blob/master/en50221.c

>From the ca_msg struct:

/* a message to/from a CI-CAM */
struct ca_msg {
unsigned int index;
unsigned int type;
unsigned int length;
unsigned char msg[256];
};

It only uses length and msg fields. Describing those seem
quite obvious. However, what "index" and "type" means?

Within the Kernel, only two drivers implement it:

$ git grep -l ca_msg drivers/
drivers/media/firewire/firedtv-ci.c
drivers/media/pci/bt8xx/dst_ca.c

At the dst_ca driver, checking for those fields don't give any
useful result:
$ grep index drivers/media/pci/bt8xx/dst_ca.c
(nothing)
$ grep type drivers/media/pci/bt8xx/dst_ca.c
// Copy application_type, application_manufacturer and manufacturer_code
p_ca_caps->slot_type = 1;
p_ca_caps->descr_type = 1;
p_ca_slot_info->type = CA_CI;
p_ca_slot_info->type = CA_CI;

(btw, using "1" for slot_type and descr_type there seems a very bad
thing)

The code at ca_get_message(), handle_dst_tag(), ca_set_pmt(), etc also
doesn't seem to be using neither one of those fields.

The same happens at firedtv-ci: it also doesn't seem to be using
none of those fields.

It should be noticed that, the dst_ca seems to allow more than one
descrambler:

p_ca_caps->descr_num = slot_cap[7];

Yet, the index is not used. So, it doesn't seem to be related to
the descrambler index (or there's an implementation bug there - and
at dvblast - as none uses it).

What *I* suspect is that this were meant to be used for either
CA index/type or DESCR index/type, but, when this got implemented,
people discovered that this would be useless and never actually
used those fields. Yet, I may be completely wrong and those were
added to mean something else.

If so, then we could just change the struct to:

struct ca_msg {
unsigned int reserved[2];
unsigned int length;
unsigned char msg[256];
};

And document just length and msg.

Thanks,
Mauro

Re: [PATCH v2 00/26] Improve DVB documentation and reduce its gap

2017-09-03 Thread Mauro Carvalho Chehab

Em Sun, 3 Sep 2017 22:05:23 +0200
Honza Petrouš  escreveu:

> 1) #define CA_SET_DESCR  _IOW('o', 134, ca_descr_t)
> 
> 
> CA_SET_DESCR is used for feeding descrambler device
> with correct keys (called here "control words") what
> allows to get services unscrambled.
> 
> The best docu is:
> 
> "Digital Video Broadcasting (DVB);
> Support for use of the DVB Scrambling Algorithm version 3
> within digital broadcasting systems"
> 
> Defined as DVB Document A125 and publicly
> available here:
> 
> https://www.dvb.org/resources/public/standards/a125_dvb-csa3.pdf
> 
> 
> typedef struct ca_descr {
> unsigned int index;
> unsigned int parity;/* 0 == even, 1 == odd */
> unsigned char cw[8];
> } ca_descr_t;
> 
> The 'index' is adress of the descrambler instance, as there exist
> limited number of them (retieved by CA_GET_DESCR_INFO).

Thanks for the info. If I understood well, the enclosed patch should
be documenting it. 


Thanks,
Mauro

[PATCH] media: ca docs: document CA_SET_DESCR ioctl and structs

The av7110 driver uses CA_SET_DESCR to store the descrambler
control words at the CA descrambler slots.

Document it.

Thanks-to: Honza Petrouš 
Signed-off-by: Mauro Carvalho Chehab 

diff --git a/Documentation/media/uapi/dvb/ca-set-descr.rst 
b/Documentation/media/uapi/dvb/ca-set-descr.rst
index 9c484317d55c..a6c47205ffd8 100644
--- a/Documentation/media/uapi/dvb/ca-set-descr.rst
+++ b/Documentation/media/uapi/dvb/ca-set-descr.rst
@@ -28,22 +28,11 @@ Arguments
 ``msg``
   Pointer to struct :c:type:`ca_descr`.
 
-.. c:type:: ca_descr
-
-.. code-block:: c
-
-struct ca_descr {
-   unsigned int index;
-   unsigned int parity;
-   unsigned char cw[8];
-};
-
-
 Description
 ---
 
-.. note:: This ioctl is undocumented. Documentation is welcome.
-
+CA_SET_DESCR is used for feeding descrambler CA slots with descrambling
+keys (refered as control words).
 
 Return Value
 
diff --git a/include/uapi/linux/dvb/ca.h b/include/uapi/linux/dvb/ca.h
index f66ed53f4dc7..a62ddf0cebcd 100644
--- a/include/uapi/linux/dvb/ca.h
+++ b/include/uapi/linux/dvb/ca.h
@@ -109,9 +109,16 @@ struct ca_msg {
unsigned char msg[256];
 };
 
+/**
+ * struct ca_descr - CA descrambler control words info
+ *
+ * @index: CA Descrambler slot
+ * @parity: control words parity, where 0 means even and 1 means odd
+ * @cw: CA Descrambler control words
+ */
 struct ca_descr {
unsigned int index;
-   unsigned int parity;/* 0 == even, 1 == odd */
+   unsigned int parity;
unsigned char cw[8];
 };

Re: [PATCH v2 00/26] Improve DVB documentation and reduce its gap

2017-09-03 Thread Honza Petrouš

> There is still a gap at the CA API, as there are three ioctls that are used
> only by a few drivers and whose structs are not properly documented:
> CA_GET_MSG, CA_SEND_MSG and CA_SET_DESCR.
>
> The first two ones seem to be related to a way that a few drivers
> provide to send/receive messages. Yet, I was unable to get what
> "index" and "type" means on those ioctls. The CA_SET_DESCR is
> only supported by av7110 driver, and has an even weirder
> undocumented struct. I was unable to discover at the Kernel, VDR
> or Kaffeine how those structs are filled. I suspect that there's
> something wrong there, but I won't risk trying to fix without
> knowing more about them. So, let's just document that those
> are needing documentation :-)
>

BTW, I just remembered dvblast app, part of videolan.org:

http://www.videolan.org/projects/dvblast.html

which is using CA_GET_MSG/CA_SEND_MSG:

https://code.videolan.org/videolan/dvblast/blob/master/en50221.c

/Honza

Re: [PATCH v2 00/26] Improve DVB documentation and reduce its gap

2017-09-03 Thread Honza Petrouš

> There is still a gap at the CA API, as there are three ioctls that are used
> only by a few drivers and whose structs are not properly documented:
> CA_GET_MSG, CA_SEND_MSG and CA_SET_DESCR.
>
> The first two ones seem to be related to a way that a few drivers
> provide to send/receive messages.

I never seen usage of such R/W ioctls, all drivers I have access to
are using read()/write() variant of communication.

Yet, I was unable to get what
> "index" and "type" means on those ioctls. The CA_SET_DESCR is
> only supported by av7110 driver, and has an even weirder
> undocumented struct. I was unable to discover at the Kernel, VDR
> or Kaffeine how those structs are filled. I suspect that there's
> something wrong there, but I won't risk trying to fix without
> knowing more about them. So, let's just document that those
> are needing documentation :-)
>


1) #define CA_SET_DESCR  _IOW('o', 134, ca_descr_t)


CA_SET_DESCR is used for feeding descrambler device
with correct keys (called here "control words") what
allows to get services unscrambled.

The best docu is:

"Digital Video Broadcasting (DVB);
Support for use of the DVB Scrambling Algorithm version 3
within digital broadcasting systems"

Defined as DVB Document A125 and publicly
available here:

https://www.dvb.org/resources/public/standards/a125_dvb-csa3.pdf


typedef struct ca_descr {
unsigned int index;
unsigned int parity;/* 0 == even, 1 == odd */
unsigned char cw[8];
} ca_descr_t;

The 'index' is adress of the descrambler instance, as there exist
limited number of them (retieved by CA_GET_DESCR_INFO).
See below:


2) #define CA_SET_PID_IOW('o', 135, ca_pid_t)
===

The second ioctl was used to link particular PID with particular
descrambler, what means that all such pids (you are allowed
to create n-to-1 link), can be descrambled by one descrambler.

This is needed in case of multiservice descrambling, when
usually exist one key (control word) per one service (so all PIDs
for one service have to be linked with one descrambler)

Without this ioctl there is no way to address particular
descrambler and so no way to use more then ONE descrambler
per demux

/Honza

[PATCH v2 00/26] Improve DVB documentation and reduce its gap

2017-09-01 Thread Mauro Carvalho Chehab

The DVB documentation was negligected for a long time, with
resulted on several gaps between the API description and its
documentation.

I'm doing a new reading at the documentation. As result of it,
this series:

- improves the introductory chapter, making it more generic;
- Do some adjustments at the frontend API, using kernel-doc
  when possible.
- Remove unused APIs at DVB demux. I suspect that the drivers
  implementing such APIs were either never merged upstream,
  or the API itself  were never used or was deprecated a long
  time ago. In any case, it doesn't make any sense to carry
  on APIs that aren't properly documented, nor are used on the
  upstream Kernel.

With this patch series, the gap between documentation and
code is solved for 3 DVB APIs:

  - Frontend API;
  - Demux API;
  - Net API.

There is still a gap at the CA API, as there are three ioctls that are used
only by a few drivers and whose structs are not properly documented:
CA_GET_MSG, CA_SEND_MSG and CA_SET_DESCR.

The first two ones seem to be related to a way that a few drivers
provide to send/receive messages. Yet, I was unable to get what
"index" and "type" means on those ioctls. The CA_SET_DESCR is
only supported by av7110 driver, and has an even weirder
undocumented struct. I was unable to discover at the Kernel, VDR
or Kaffeine how those structs are filled. I suspect that there's
something wrong there, but I won't risk trying to fix without
knowing more about them. So, let's just document that those
are needing documentation :-)

---

v2: Added CA API patches at the end and verified that everything
compiles after each patch. Also do some fixes at dst_ca for it
to report the error code to userspace and remove boilerplate
code there.

Mauro Carvalho Chehab (27):
  media: ca.h: split typedefs from structs
  media: dmx.h: split typedefs from structs
  media: dvb/intro: use the term Digital TV to refer to the system
  media: dvb/intro: update references for TV standards
  media: dvb/intro: update the history part of the document
  media: dvb/intro: adjust the notices about optional hardware
  media: dvb/frontend.h: move out a private internal structure
  media: dvb/frontend.h: document the uAPI file
  media: dvb frontend docs: use kernel-doc documentation
  media: fe_property_parameters.rst: better define properties usage
  media: fe_property_parameters.rst: better document bandwidth
  media: dmx.h: get rid of unused DMX_KERNEL_CLIENT
  media: dmx.h: get rid of DMX_GET_CAPS
  media: dmx.h: get rid of DMX_SET_SOURCE
  media: dmx.h: get rid of GET_DMX_EVENT
  media: dmx.h: add kernel-doc markups and use it at Documentation/
  media: net.rst: Fix the level of a section of the net chapter
  media: ca.h: get rid of CA_SET_PID
  media: ca.h: document most CA data types
  media: dst_ca: return a proper error code from CA errors
  media: ca-reset.rst: add some description to this ioctl
  media: ca-get-cap.rst: document this ioctl
  media: ca-get-slot-info.rst: document this ioctl
  media: ca-get-descr-info.rst: document this ioctl
  media: dvb CA docs: place undocumented data together with ioctls
  media: dvb rst: identify the documentation gap at the API
  media: dst_ca: remove CA_SET_DESCR boilerplate

 Documentation/media/ca.h.rst.exceptions|1 -
 Documentation/media/dmx.h.rst.exceptions   |   20 +-
 Documentation/media/dvb-drivers/ci.rst |1 -
 Documentation/media/frontend.h.rst.exceptions  |  185 ++-
 Documentation/media/uapi/dvb/ca-get-cap.rst|   36 +-
 Documentation/media/uapi/dvb/ca-get-descr-info.rst |   29 +-
 Documentation/media/uapi/dvb/ca-get-msg.rst|   38 +-
 Documentation/media/uapi/dvb/ca-get-slot-info.rst  |   98 +-
 Documentation/media/uapi/dvb/ca-reset.rst  |3 +-
 Documentation/media/uapi/dvb/ca-set-descr.rst  |   10 +
 Documentation/media/uapi/dvb/ca-set-pid.rst|   60 -
 Documentation/media/uapi/dvb/ca.rst|5 +
 Documentation/media/uapi/dvb/ca_data_types.rst |  103 +-
 Documentation/media/uapi/dvb/ca_function_calls.rst |1 -
 Documentation/media/uapi/dvb/dmx-get-caps.rst  |   41 -
 Documentation/media/uapi/dvb/dmx-get-event.rst |   60 -
 Documentation/media/uapi/dvb/dmx-set-source.rst|   44 -
 Documentation/media/uapi/dvb/dmx_fcalls.rst|3 -
 Documentation/media/uapi/dvb/dmx_types.rst |  225 +---
 Documentation/media/uapi/dvb/dtv-fe-stats.rst  |   17 -
 Documentation/media/uapi/dvb/dtv-properties.rst|   15 -
 Documentation/media/uapi/dvb/dtv-property.rst  |   31 -
 Documentation/media/uapi/dvb/dtv-stats.rst |   18 -
 Documentation/media/uapi/dvb/dvbproperty-006.rst   |   12 -
 Documentation/media/uapi/dvb/dvbproperty.rst   |   28 +-
 .../media/uapi/dvb/fe-diseqc-recv-slave-reply.rst  |   40 +-
 .../media/uapi/dvb/fe-diseqc-send-burst.rst|   31 +-
 .../media/uapi/dvb/fe-diseqc-send-master-cmd.rst   |   29 +-

Re: [PATCH v2 00/26] Improve DVB documentation and reduce its gap

Re: [PATCH v2 00/26] Improve DVB documentation and reduce its gap

Re: [PATCH v2 00/26] Improve DVB documentation and reduce its gap

Re: [PATCH v2 00/26] Improve DVB documentation and reduce its gap

Re: [PATCH v2 00/26] Improve DVB documentation and reduce its gap

Re: [PATCH v2 00/26] Improve DVB documentation and reduce its gap

Re: [PATCH v2 00/26] Improve DVB documentation and reduce its gap

Re: [PATCH v2 00/26] Improve DVB documentation and reduce its gap

[PATCH v2 00/26] Improve DVB documentation and reduce its gap

9 matches

Site Navigation

Mail list logo

Footer information