[linux-dvb] [PATCH][REWORKED/RFC] dvb-s2 support added to frontend.h

[Johannes Stezenbach]

On Fri, Mar 03, 2006, Marcel Siegert wrote:
> +/**
> + * Don't use FE_QPSK, FE_QAM, FE_OFDM any longer in new applications.
> + * They are deprecated and just kept for compatibility issues.
> + */

This is not entirely true since for backward compat the default
FE type returned by FE_GET_INFO will be one of those. We should
probably document that if FE_GET_EXTENDED_INFO is available,
apps should not look at FE_GET_INFO ->type.
It's a bit confusing...

> +/*! describes common supported frontend capabilities. */
> +enum dvb_fe_common_cap {
> +	DVB_FE_CAN_INVERSION_AUTO   = (1 << 0), /*!< frontend can handle spectral inversion automatically */
> +	DVB_FE_CAN_RECOVER          = (1 << 1), /*!< frontend can recover from a cable unplug automatically */
> +	DVB_FE_CAN_MUTE_TS          = (1 << 2), /*!< frontend can stop spurious TS data output */

How would an app use this? I guess not. IMHO these shouldn't be in
the public API, these are part of the private API between frontends
and dvb-core. They should be in dvb-frontend.h.

BTW, I guess we won't use doxygen so there's no need fo all the ! and <.

> +	DVB_FE_SUP_HIGH_LNB_VOLTAGE = (1 << 31), /*!< frontend can deliver higher lnb voltages */

I'm also not sure about this. IMHO apps should always assume the
hardware/driver can do it. If the hardware can't,
FE_ENABLE_HIGH_LNB_VOLTAGE is a no-op.

> +/*! describes other available, frontend type dependent capabilities. */
> +enum dvb_fe_other_cap {
> +	DVB_FE_CAN_TRANSMISSION_MODE_AUTO = (1 << 0), /*!< (DVB-T specific) */
> +	DVB_FE_CAN_BANDWIDTH_AUTO         = (1 << 1), /*!< (DVB-T specific) */
> +	DVB_FE_CAN_GUARD_INTERVAL_AUTO    = (1 << 2), /*!< (DVB-T specific) */
> +	DVB_FE_CAN_HIERARCHY_AUTO         = (1 << 31), /*!< (DVB-T specific) */
> +};

Except for bandwidth these are all contained in TPS signalling, so
I think it is safe to assume all DVB-T frontends can do this.
Or does anyone know one that doesn't?

For bandwidth, I think most frontends can not handle this automatically
(actually, all which I know of). dvb-core doesn't currently implement
AUTO, so the app must *always* choose the correct bandwidth.



> +/**
> + *  this struct will be filled by the FE_GET_EXTENDED_INFO ioctl.
> + *  it is a extension to the normal frontend capabilities and provided
> + *  if the dvb_fe_info.caps is having the FE_HAS_EXTENDED_INFO bit set.
> + */
> +struct dvb_fe_caps_extended {
> +	fe_code_rate_t 		caps_fec;		/*!< supported fecs */
> +	fe_modulation_t		caps_modulation;	/*!< supported modulations */
> +	enum dvb_fe_common_cap	caps_common;		/*!< supported common capabilities */
> +	enum dvb_fe_other_cap	caps_other;		/*!< supported other capabilities */
> +	fe_type_t		caps_frontends_avail;	/*!< supported frontend_types */

I guess these bit sets should all be __u32, no?

> +#define dvb_qpsk_parameters dvb_dvbs_parameters
> +#define dvb_qam_parameters dvb_dvbc_parameters
> +#define dvb_ofdm_parameters dvb_dvbt_parameters
> +
> +/* just kept for backwards binary compatibility */
> +struct __dvb_frontend_parameters_old {

IMHO all legacy cruft should be moved to the bottom of the file
(if possible), seperated by a big "LEGACY CRUFT" warning.

> +/**
> + * Important notice on dvb_frontend_event and FE_GET_EVENT

rather thay just say it is "important", better give a reason:
"FE_GET_EVENT is somewhat mis-designed, it returns always stale imformation."

> + * Applications should:
> + * - open the frontend device with O_NONBLOCK
> + * - poll() for events
> + * - FE_GET_EVENT all pending events to clear the POLLPRI status,
> + *?  and throw them away

"?"

> +/**
> + * Struct to keep the api version which can be queried
> + * via the FE_GET_API_VERSION ioctl.
> + * Need for having encapsulation libraries in userspace
> + * possible.
> + */
> +struct dvb_api_version {
> +	__u16	major;
> +	__u16	minor;
> +};

I suggest we take this out of this package. If someone can prove
a usecase where this really makes sense we add it later.

> +/**
> + * use to set the FE_STANDARD - if a tuner supports more than one type. e.g. DVB-C/T or DVB-S/S2 combi frontends
> + * after FE_SET_STANDARD was set, the drivers has to make sure still to reflect the standards available, but
> + * capabilities should be adjusted to the selected stanadard
> + */

lines are too long

> +/**
> + * used to query the api v4 backported capabilities (see above for details)
> + */
> +#define FE_GET_EXTENDED_INFO	   _IOR('o', 86, struct dvb_fe_caps_extended)

Better remove the V4 comment, it just might confuse people.


BTW, a while ago we talked about DVB-T low/high prio selection,
and DVB-H. Is there someone who still cares about it and
wants to use the opportunity to check on that?


Johannes