[linux-dvb] [RFC] Frontend API

[Holger Waechtler <holger@convergence.de>]

Hi all,

below you find a proposal for the Frontend API Headerfile. Here a short
list of changes and reasons:

  - the /dev/ost directory is named now /dev/dvb

  - /include/linux/ost is now /include/linux/dvb

  - frontend- and sec-device are merged. Almost all tuners can create the
    DiSEqC-sequences, some of them the tone signal too. So this maps better
    on the hardware and make it easier to write clean frontend drivers

  - structs follow the kernel naming scheme, no typedefs for structs anymore.

  - the struct dvb_frontend_info contains a name field, here you can get
    type, information and vendor of the tuner device

  - DiSEqC messages are sent through an interface which basically reflects the
    Eutelsat DiSEqC bus specification. Almost all highlevel DiSEqC stuff is
    done in userspace. The ioctl blocks until the command is sent; thus it's
    easy to implement the correct timing

  - 13.5V and 18.5V definitions in SecVoltage are gone - if the tuner supports
    high LNB voltages you can enable them using the FE_ENABLE_HIGH_LNB_VOLTAGE
    ioctl

  - the FrontendStatus bits are defined in a way that reflects real tuners/
    demodulators a little bit better

  - all frontend parameter enums have an XXX_AUTO enum, this will be used for
    software (or if supported: hardware) autoprobing

  - struct dvb_frontend_event is simplified. You get the currently tuned
    parameter set (real parameters if you used autoprobing) and the status bits.
    The parameter set is only valid if the FE_HAS_LOCK bit is set

  - FE_READ_SIGNAL_STRENGTH and FE_READ_SNR return values in the range of
    0...65536 (0 means no signal, higher values good signals). We don't define
    if the this range is mapped linear, logarithmic or whatever but recommend that
    a value of about 70% (~45000) means a good signal

  - when the frontend device gets closed, all voltages are switched off after a
    configurable timeout. The demodulator will go into standby mode when possible

we have implemented this for a few frontends in the NEWSTRUCT branch, but this
code is neither complete nor well tested. Please comment only the API definition
for now, we will need some more time until this gets reality.

- Holger



----------------------------------------------------------------------------------
/*
  * frontend.h
  *
  * Copyright (C) 2000 Marcus Metzler <marcus@convergence.de>
  *                    Ralph  Metzler <ralph@convergence.de>
  *                    Holger Waechtler <holger@convergence.de>
  *                    Andre' Draszik <ad@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 _FRONTEND_H_
#define _FRONTEND_H_

#include <asm/types.h>



typedef enum {
         FE_QPSK,
         FE_QAM,
         FE_OFDM
} FrontendType;


struct dvb_frontend_info {
         FrontendType type;
         __u32        min_frequency;
         __u32        max_frequency;
         __u32        max_symbol_rate;
         __u32        min_symbol_rate;
	char         hw_name[128];
};



/**
  *  Check out the DiSEqC bus spec available on http://www.eutelsat.org/ for
  *  the meaning of this struct...
  */
struct dvb_diseqc_msg {
         __u8 msg [6];           /*  { framing, address, command, data [3] } */
         __u8 msg_len;           /*  valid values are 3...6  */
};


typedef enum {
         SEC_VOLTAGE_13,
         SEC_VOLTAGE_18
} SecVoltage;


typedef enum {
         SEC_TONE_ON,
         SEC_TONE_OFF
} SecToneMode;


typedef enum {
         SEC_MINI_A,
         SEC_MINI_B
} SecMiniCmd;


typedef enum {
	FE_HAS_SIGNAL     = 1,      /*  found something above the noise level */
	FE_HAS_CARRIER    = 2,      /*  found a DVB signal  */
	FE_HAS_VITERBI    = 4,      /*  FEC is stable  */
	FE_HAS_SYNC       = 8,      /*  found sync bytes  */
	FE_HAS_LOCK       = 16      /*  everything's working... */
} FrontendStatus;


typedef enum {
         INVERSION_OFF,
         INVERSION_ON,
         INVERSION_AUTO
} SpectralInversion;


typedef enum {
         FEC_NONE,
         FEC_1_2,
         FEC_2_3,
         FEC_3_4,
         FEC_4_5,
         FEC_5_6,
         FEC_6_7,
         FEC_7_8,
         FEC_8_9,
         FEC_AUTO
} CodeRate;


typedef enum {
         QPSK,
         QAM_16,
         QAM_32,
         QAM_64,
         QAM_128,
         QAM_256,
	QAM_AUTO
} Modulation;


typedef enum {
	TRANSMISSION_MODE_2K,
	TRANSMISSION_MODE_8K,
	TRANSMISSION_MODE_AUTO
} TransmitMode;

typedef enum {
	BANDWIDTH_8_MHZ,
	BANDWIDTH_7_MHZ,
	BANDWIDTH_6_MHZ,
	BANDWIDTH_AUTO
} BandWidth;


typedef enum {
	GUARD_INTERVAL_1_32,
	GUARD_INTERVAL_1_16,
	GUARD_INTERVAL_1_8,
	GUARD_INTERVAL_1_4,
	GUARD_INTERVAL_AUTO
} GuardInterval;


typedef enum {
	HIERARCHY_NONE,
	HIERARCHY_1,
	HIERARCHY_2,
	HIERARCHY_4,
	HIERARCHY_AUTO
} Hierarchy;


struct dvb_qpsk_parameters {
         __u32     symbol_rate; /* symbol rate in Symbols per second */
         CodeRate  inner_fec;   /* forward error correction (see above) */
};


struct dvb_qam_parameters {
         __u32      symbol_rate; /* symbol rate in Symbols per second */
         CodeRate   inner_fec;   /* forward error correction (see above) */
         Modulation modulation;  /* modulation type (see above) */
};


struct dvb_ofdm_parameters {
         BandWidth     band_width;
         CodeRate      code_rate_HP;        /* high priority stream code rate */
         CodeRate      code_rate_LP;        /* low priority stream code rate */
         Modulation    modulation;          /* modulation type (see above) */
         TransmitMode  transmission_mode;
         GuardInterval guard_interval;
         Hierarchy     hierarchy_information;
};


struct dvb_frontend_parameters {
         __u32 frequency;          /* (absolute) frequency in Hz for QAM/OFDM */
                                   /* intermediate frequency in kHz for QPSK */
	SpectralInversion inversion;
	union {
		struct dvb_qpsk_parameters qpsk;
		struct dvb_qam_parameters  qam;
		struct dvb_ofdm_parameters ofdm;
	} u;
};


struct dvb_frontend_event {
	FrontendStatus status;
	struct dvb_frontend_parameters parameters;
};



#define FE_GET_INFO                   _IOR('o', 61, struct dvb_frontend_info)

#define FE_DISEQC_RESET_OVERLOAD      _IO('o', 62)
#define FE_DISEQC_SEND_MSG            _IOW('o', 63, struct dvb_diseqc_msg)
#define FE_DISEQC_SEND_BURST          _IOW('o', 64, SecMiniCmd)

#define FE_SET_TONE                   _IOW('o', 65, SecToneMode)
#define FE_SET_VOLTAGE                _IOW('o', 66, SecVoltage)
#define FE_ENABLE_HIGH_LNB_VOLTAGE    _IOW('o', 67, int)

#define FE_READ_STATUS                _IOR('o', 68, FrontendStatus)
#define FE_READ_BER                   _IOR('o', 69, __u32)
#define FE_READ_SIGNAL_STRENGTH       _IOR('o', 70, __u16)
#define FE_READ_SNR                   _IOR('o', 71, __u16)
#define FE_READ_UNCORRECTED_BLOCKS    _IOR('o', 72, __u32)
#define FE_GET_NEXT_FREQUENCY         _IOW('o', 73, __u32)
#define FE_GET_NEXT_SYMBOL_RATE       _IOW('o', 74, __u32)

#define FE_SET_FRONTEND               _IOW('o', 75, struct dvb_frontend_parameters)
#define FE_GET_FRONTEND               _IOR('o', 76, struct dvb_frontend_parameters)
#define FE_GET_EVENT                  _IOR('o', 77, struct dvb_frontend_event)


#endif /*_FRONTEND_H_*/




-- 
Info:
To unsubscribe send a mail to listar@linuxtv.org with "unsubscribe linux-dvb" as subject.