[linux-dvb] [PATCH-REWORKED] frontend.h add dvb-s2 support including backwards compability

[Felix Domke]

Johannes Stezenbach wrote:
> On Wed, Feb 22, 2006, Marcel Siegert wrote:
>>once again same topic.
>>after short discussion with felix domke on irc, 
>>we found that the attached solution is more suitable.
> I'd actually prefer an extended definition of struct dvb_frontend_parameters
> with room for more parameters (e.g. to query DVB-T cell ids etc.), plus
> some padding to allow for future extensions.
> FE_SET_FRONTEND would be redefined to use the new struct, however
> it must be source code compatible (i.e. no changes to apps
> necessary, they should continue to work with identical capabilites
> if compiled against the new frontend.h).
> Binary compatibility can be retained by adding *_OLD cruft,
> see dvb/net.h for an example.
> What do you think?
This would basicly be Marcel's first idea, right?

In that idea, struct dvb_frontend_(parameters|event)_ex would be
fixed-size, and FE_(GET|SET)_FRONTEND_EX / FE_GET_EVENT_EX would operate
on that structure.

It would fix DVB-S2, but break for every new change. As you said, some
padding would help here, but only until there is a new scheme which
requires even larger parameter sets.

Now, the basic idea was to let FE_SET_FRONTEND(_EX) operate not on a
full dvb_frontend_parameters, but on a subset, i.e.
sizeof(frequency)+sizeof(inversion)+sizeof(struct dvb_<mode>_paramters).
That would make it possible to define new fields, without breaking old
applications.

(We could also define new dvb_<mode>_parameters which always include
frequency and inversion as first two fields with
dvb_<modulation>_parameters as backward compatbility without these
fields, as a side note)

Do you all agree with that until here?

Now, we could simply add a field into the "struct
dvb_frontend_parameters", say:

struct dvb_frontend_parameters_ex {
	int standard; /* new */
 	__u32 frequency;
	fe_spectral_inversion_t inversion;
 	union {
		struct dvb_dvbs_parameters qpsk;
		struct dvb_dvbc_parameters  qam;
		struct dvb_dvbt_parameters ofdm;
		struct dvb_dvbs2_parameters qpsk2;
		...
 	} u;
 };

Note that the size of this struct can grow when new standards are added.
All kernel stuff only uses the actually used structure, which is
indicated by the "standard"-field.

The "standard"-field had to be filled on a FE_SET_FRONTEND_EX. A call to
FE_GET_FRONTEND had to ensure that the same structure (size) as the last
call to FE_SET_FRONTEND_EX has to be used, same for FE_GET_EVENT.

Now, we had 3 more IOCTLs:
FE_SET_FRONTEND_EX (which uses the new "standard"-field)
FE_GET_FRONTEND_EX (which also uses the new struct, and is able to use
the new standard modes)
FE_GET_EVENT_EX    (which also uses the new struct)

Having a growing structure would be the only way to be scalable even for
new standards. We could always add more fields into that union. Older
applications, which define a smaller union, would still be compatible as
FE_GET_FRONTEND_EX only fills the appropriate number of bytes. Only when
a new standard is selected, more bytes would be written.

Note that, as written above, FE_GET_* has to use EXACTLY the same mode
(as set by the last FE_SET_FRONTEND_EX call) every time, otherwise the
application could have allocated a differently sized union. Plus an
application would not expect to tune on one standard, but get a
different standard back.

Now, as small modification to the above, i would introduce the
FE_SET_MODE (i would call it FE_SET_STANDARD), in order to replace the
"standard" field in the structure.

That would have a number of advantages:
 - We could keep the available IOCTLs. FE_SET_MODE set the required
mode, and FE_GET_FRONTEND etc. are 100% backward compatible when an
"old" standard is selected.
 - There is no special need to specify the FE_GET_FRONTEND/FE_GET_EVENT
behaviour. The whole frontend operates on the standard set by the
FE_SET_MODE ioctl.
 - Capabilities (for example, the symbol rate range, which typically
differs between DVB-S and DVB-S2) could change after a FE_SET_MODE
 - Combo frontends, for example DVB-S/DVB-T, could be handled fine. You
just switch them to the required standard.

Some notes to backward compatibility:

An application not prepared for a new standard would never select a
standard which doesn't fit into their idea of the union size. Thus this
would give backward compatibility (older apps with newer core).

Newer applications, selecting a standard which isn't available, would
detect that this standard is not available (FE_SET_MODE would fail).
This is also no problem.

Newer applications, running with an older dvb-core which doesn't know of
FE_SET_MODE would allocate the current size of the union. The older
dvb-core would copy sizeof(dvb_frontend_parameters), not the specialized
number of bytes (which could be less). This is also no problem - an
application should always use the "struct dvb_frontend_parameters".

Comments?

regards,
Felix