diff --git a/Documentation/DocBook/media/dvb/frontend.xml b/Documentation/DocBook/media/dvb/frontend.xml index 98443c4c2818..3b3973aee8eb 100644 --- a/Documentation/DocBook/media/dvb/frontend.xml +++ b/Documentation/DocBook/media/dvb/frontend.xml @@ -29,58 +29,6 @@ specification is available at Eutelsat. -
-Frontend Data Types - -
-Frontend type - -For historical reasons, frontend types are named by the type of modulation - used in transmission. The fontend types are given by fe_type_t type, defined as: - - -Frontend types - - &cs-def; - - - fe_type - Description - DTV_DELIVERY_SYSTEM equivalent type - - - - - FE_QPSK - For DVB-S standard - SYS_DVBS - - - FE_QAM - For DVB-C annex A standard - SYS_DVBC_ANNEX_A - - - FE_OFDM - For DVB-T standard - SYS_DVBT - - - FE_ATSC - For ATSC standard (terrestrial) or for DVB-C Annex B (cable) used in US. - SYS_ATSC (terrestrial) or SYS_DVBC_ANNEX_B (cable) - -
- -Newer formats like DVB-S2, ISDB-T, ISDB-S and DVB-T2 are not described at the above, as they're -supported via the new FE_GET_PROPERTY/FE_GET_SET_PROPERTY ioctl's, using the DTV_DELIVERY_SYSTEM parameter. - - -The usage of this field is deprecated, as it doesn't report all supported standards, and -will provide an incomplete information for frontends that support multiple delivery systems. -Please use DTV_ENUM_DELSYS instead. -
-
frontend capabilities @@ -157,6 +105,7 @@ a specific frontend type. };
+
diseqc slave reply @@ -258,90 +207,8 @@ typedef enum fe_status { recommended to reset DiSEqC, tone and parameters -
-
-frontend parameters -The kind of parameters passed to the frontend device for tuning depend on -the kind of hardware you are using. -The struct dvb_frontend_parameters uses an -union with specific per-system parameters. However, as newer delivery systems -required more data, the structure size weren't enough to fit, and just -extending its size would break the existing applications. So, those parameters -were replaced by the usage of -FE_GET_PROPERTY/FE_SET_PROPERTY ioctl's. The -new API is flexible enough to add new parameters to existing delivery systems, -and to add newer delivery systems. -So, newer applications should use -FE_GET_PROPERTY/FE_SET_PROPERTY instead, in -order to be able to support the newer System Delivery like DVB-S2, DVB-T2, -DVB-C2, ISDB, etc. -All kinds of parameters are combined as an union in the FrontendParameters structure: - -struct dvb_frontend_parameters { - uint32_t frequency; /⋆ (absolute) frequency in Hz for QAM/OFDM ⋆/ - /⋆ intermediate frequency in kHz for QPSK ⋆/ - fe_spectral_inversion_t inversion; - union { - struct dvb_qpsk_parameters qpsk; - struct dvb_qam_parameters qam; - struct dvb_ofdm_parameters ofdm; - struct dvb_vsb_parameters vsb; - } u; -}; - -In the case of QPSK frontends the frequency field specifies the intermediate -frequency, i.e. the offset which is effectively added to the local oscillator frequency (LOF) of -the LNB. The intermediate frequency has to be specified in units of kHz. For QAM and -OFDM frontends the frequency specifies the absolute frequency and is given in Hz. - - -
-QPSK parameters -For satellite QPSK frontends you have to use the dvb_qpsk_parameters structure: - - struct dvb_qpsk_parameters { - uint32_t symbol_rate; /⋆ symbol rate in Symbols per second ⋆/ - fe_code_rate_t fec_inner; /⋆ forward error correction (see above) ⋆/ - }; - -
-
-QAM parameters -for cable QAM frontend you use the dvb_qam_parameters structure: - - struct dvb_qam_parameters { - uint32_t symbol_rate; /⋆ symbol rate in Symbols per second ⋆/ - fe_code_rate_t fec_inner; /⋆ forward error correction (see above) ⋆/ - fe_modulation_t modulation; /⋆ modulation type (see above) ⋆/ - }; - -
-
-VSB parameters -ATSC frontends are supported by the dvb_vsb_parameters structure: - -struct dvb_vsb_parameters { - fe_modulation_t modulation; /⋆ modulation type (see above) ⋆/ -}; - -
-
-OFDM parameters -DVB-T frontends are supported by the dvb_ofdm_parameters structure: - - struct dvb_ofdm_parameters { - fe_bandwidth_t bandwidth; - fe_code_rate_t code_rate_HP; /⋆ high priority stream code rate ⋆/ - fe_code_rate_t code_rate_LP; /⋆ low priority stream code rate ⋆/ - fe_modulation_t constellation; /⋆ modulation type (see above) ⋆/ - fe_transmit_mode_t transmission_mode; - fe_guard_interval_t guard_interval; - fe_hierarchy_t hierarchy_information; - }; - -
frontend spectral inversion The Inversion field can take one of these values: @@ -358,6 +225,7 @@ typedef enum fe_spectral_inversion { itself.
+
frontend code rate The possible values for the fec_inner field used on @@ -384,6 +252,7 @@ typedef enum fe_code_rate { detection.
+
frontend modulation type for QAM, OFDM and VSB For cable and terrestrial frontends, e. g. for @@ -410,8 +279,10 @@ it needs to specify the quadrature modulation mode which can be one of the follo } fe_modulation_t;
+
More OFDM parameters +
Number of carriers per channel @@ -426,6 +297,7 @@ typedef enum fe_transmit_mode { } fe_transmit_mode_t;
+
frontend bandwidth @@ -440,6 +312,7 @@ typedef enum fe_bandwidth { } fe_bandwidth_t;
+
frontend guard inverval @@ -455,6 +328,7 @@ typedef enum fe_guard_interval { } fe_guard_interval_t;
+
frontend hierarchy @@ -467,22 +341,9 @@ typedef enum fe_hierarchy { } fe_hierarchy_t;
-
-
-frontend events - - struct dvb_frontend_event { - fe_status_t status; - struct dvb_frontend_parameters parameters; - }; - -
-
- -
Frontend Function Calls @@ -694,417 +555,6 @@ typedef enum fe_hierarchy {
-
-FE_READ_BER -DESCRIPTION - - -This ioctl call returns the bit error rate for the signal currently - received/demodulated by the front-end. For this command, read-only access to - the device is sufficient. - - -SYNOPSIS - - -int ioctl(int fd, int request = FE_READ_BER, - uint32_t ⋆ber); - - -PARAMETERS - - -int fd - -File descriptor returned by a previous call to open(). - - -int request - -Equals FE_READ_BER for this command. - - -uint32_t *ber - -The bit error rate is stored into *ber. - - - -&return-value-dvb; -
- -
-FE_READ_SNR - -DESCRIPTION - - -This ioctl call returns the signal-to-noise ratio for the signal currently received - by the front-end. For this command, read-only access to the device is sufficient. - - -SYNOPSIS - - -int ioctl(int fd, int request = FE_READ_SNR, uint16_t - ⋆snr); - - -PARAMETERS - - -int fd - -File descriptor returned by a previous call to open(). - - -int request - -Equals FE_READ_SNR for this command. - - -uint16_t *snr - -The signal-to-noise ratio is stored into *snr. - - - -&return-value-dvb; -
- -
-FE_READ_SIGNAL_STRENGTH -DESCRIPTION - - -This ioctl call returns the signal strength value for the signal currently received - by the front-end. For this command, read-only access to the device is sufficient. - - -SYNOPSIS - - -int ioctl( int fd, int request = - FE_READ_SIGNAL_STRENGTH, uint16_t ⋆strength); - - - -PARAMETERS - - -int fd - -File descriptor returned by a previous call to open(). - - -int request - -Equals FE_READ_SIGNAL_STRENGTH for this - command. - - -uint16_t *strength - -The signal strength value is stored into *strength. - - - -&return-value-dvb; -
- -
-FE_READ_UNCORRECTED_BLOCKS -DESCRIPTION - - -This ioctl call returns the number of uncorrected blocks detected by the device - driver during its lifetime. For meaningful measurements, the increment in block - count during a specific time interval should be calculated. For this command, - read-only access to the device is sufficient. - - -Note that the counter will wrap to zero after its maximum count has been - reached. - - -SYNOPSIS - - -int ioctl( int fd, int request = - FE_READ_UNCORRECTED_BLOCKS, uint32_t ⋆ublocks); - - -PARAMETERS - - -int fd - -File descriptor returned by a previous call to open(). - - -int request - -Equals FE_READ_UNCORRECTED_BLOCKS for this - command. - - -uint32_t *ublocks - -The total number of uncorrected blocks seen by the driver - so far. - - - -&return-value-dvb; -
- -
-FE_SET_FRONTEND -DESCRIPTION - - -This ioctl call starts a tuning operation using specified parameters. The result - of this call will be successful if the parameters were valid and the tuning could - be initiated. The result of the tuning operation in itself, however, will arrive - asynchronously as an event (see documentation for FE_GET_EVENT and - FrontendEvent.) If a new FE_SET_FRONTEND operation is initiated before - the previous one was completed, the previous operation will be aborted in favor - of the new one. This command requires read/write access to the device. - - - -SYNOPSIS - - -int ioctl(int fd, int request = FE_SET_FRONTEND, - struct dvb_frontend_parameters ⋆p); - - -PARAMETERS - - -int fd - -File descriptor returned by a previous call to open(). - - -int request - -Equals FE_SET_FRONTEND for this command. - - -struct - dvb_frontend_parameters - *p - -Points to parameters for tuning operation. - - - -&return-value-dvb; - -EINVAL - -Maximum supported symbol rate reached. - - -
- -
-FE_GET_FRONTEND -DESCRIPTION - - -This ioctl call queries the currently effective frontend parameters. For this - command, read-only access to the device is sufficient. - - - -SYNOPSIS - - -int ioctl(int fd, int request = FE_GET_FRONTEND, - struct dvb_frontend_parameters ⋆p); - - - -PARAMETERS - - -int fd - -File descriptor returned by a previous call to open(). - - -int request - -Equals FE_SET_FRONTEND for this command. - - -struct - dvb_frontend_parameters - *p - -Points to parameters for tuning operation. - - - -&return-value-dvb; - -EINVAL - -Maximum supported symbol rate reached. - - - -
- -
-FE_GET_EVENT -DESCRIPTION - - -This ioctl call returns a frontend 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. Since the event queue allocated is - rather small (room for 8 events), the queue must be serviced regularly to avoid - overflow. If an overflow happens, the oldest event is discarded from the queue, - and an error (EOVERFLOW) occurs the next time the queue is read. After - reporting the error condition in this fashion, subsequent - FE_GET_EVENT - calls will return events from the queue as usual. - - -For the sake of implementation simplicity, this command requires read/write - access to the device. - - - -SYNOPSIS - - -int ioctl(int fd, int request = QPSK_GET_EVENT, - struct dvb_frontend_event ⋆ev); - - - -PARAMETERS - - -int fd - -File descriptor returned by a previous call to open(). - - -int request - -Equals FE_GET_EVENT for this command. - - -struct - dvb_frontend_event - *ev - -Points to the location where the event, - - - -if any, is to be stored. - - - -&return-value-dvb; - -EWOULDBLOCK - -There is no event pending, and the device is in - non-blocking mode. - - -EOVERFLOW - -Overflow in event queue - one or more events were lost. - - -
-
FE_GET_INFO DESCRIPTION @@ -1521,40 +971,15 @@ FE_TUNE_MODE_ONESHOT When set, this flag will disable any zigzagging or other "n &return-value-dvb;
-
- FE_DISHNETWORK_SEND_LEGACY_CMD -DESCRIPTION - - -WARNING: This is a very obscure legacy command, used only at stv0299 driver. Should not be used on newer drivers. -It provides a non-standard method for selecting Diseqc voltage on the frontend, for Dish Network legacy switches. -As support for this ioctl were added in 2004, this means that such dishes were already legacy in 2004. - - - -SYNOPSIS - - -int ioctl(int fd, int request = - FE_DISHNETWORK_SEND_LEGACY_CMD, unsigned long cmd); - - - -PARAMETERS - - - unsigned long cmd - - - -sends the specified raw cmd to the dish via DISEqC. - - - - -&return-value-dvb;
+
+DVB Frontend legacy API (a. k. a. DVBv3) +The usage of this API is deprecated, as it doesn't support all digital + TV standards, doesn't provide good statistics measurements and provides + incomplete information. This is kept only to support legacy applications. + +&sub-frontend_legacy_api;
&sub-dvbproperty; diff --git a/Documentation/DocBook/media/dvb/frontend_legacy_api.xml b/Documentation/DocBook/media/dvb/frontend_legacy_api.xml new file mode 100644 index 000000000000..f4d300488d12 --- /dev/null +++ b/Documentation/DocBook/media/dvb/frontend_legacy_api.xml @@ -0,0 +1,603 @@ +
+Frontend Legacy Data Types + +
+Frontend type + +For historical reasons, frontend types are named by the type of modulation + used in transmission. The fontend types are given by fe_type_t type, defined as: + + +Frontend types + + &cs-def; + + + fe_type + Description + DTV_DELIVERY_SYSTEM equivalent type + + + + + FE_QPSK + For DVB-S standard + SYS_DVBS + + + FE_QAM + For DVB-C annex A standard + SYS_DVBC_ANNEX_A + + + FE_OFDM + For DVB-T standard + SYS_DVBT + + + FE_ATSC + For ATSC standard (terrestrial) or for DVB-C Annex B (cable) used in US. + SYS_ATSC (terrestrial) or SYS_DVBC_ANNEX_B (cable) + +
+ +Newer formats like DVB-S2, ISDB-T, ISDB-S and DVB-T2 are not described at the above, as they're +supported via the new FE_GET_PROPERTY/FE_GET_SET_PROPERTY ioctl's, using the DTV_DELIVERY_SYSTEM parameter. + + +The usage of this field is deprecated, as it doesn't report all supported standards, and +will provide an incomplete information for frontends that support multiple delivery systems. +Please use DTV_ENUM_DELSYS instead. +
+ + +
+frontend parameters +The kind of parameters passed to the frontend device for tuning depend on +the kind of hardware you are using. +The struct dvb_frontend_parameters uses an +union with specific per-system parameters. However, as newer delivery systems +required more data, the structure size weren't enough to fit, and just +extending its size would break the existing applications. So, those parameters +were replaced by the usage of +FE_GET_PROPERTY/FE_SET_PROPERTY ioctl's. The +new API is flexible enough to add new parameters to existing delivery systems, +and to add newer delivery systems. +So, newer applications should use +FE_GET_PROPERTY/FE_SET_PROPERTY instead, in +order to be able to support the newer System Delivery like DVB-S2, DVB-T2, +DVB-C2, ISDB, etc. +All kinds of parameters are combined as an union in the FrontendParameters structure: + +struct dvb_frontend_parameters { + uint32_t frequency; /⋆ (absolute) frequency in Hz for QAM/OFDM ⋆/ + /⋆ intermediate frequency in kHz for QPSK ⋆/ + fe_spectral_inversion_t inversion; + union { + struct dvb_qpsk_parameters qpsk; + struct dvb_qam_parameters qam; + struct dvb_ofdm_parameters ofdm; + struct dvb_vsb_parameters vsb; + } u; +}; + +In the case of QPSK frontends the frequency field specifies the intermediate +frequency, i.e. the offset which is effectively added to the local oscillator frequency (LOF) of +the LNB. The intermediate frequency has to be specified in units of kHz. For QAM and +OFDM frontends the frequency specifies the absolute frequency and is given in Hz. + + +
+QPSK parameters +For satellite QPSK frontends you have to use the dvb_qpsk_parameters structure: + + struct dvb_qpsk_parameters { + uint32_t symbol_rate; /⋆ symbol rate in Symbols per second ⋆/ + fe_code_rate_t fec_inner; /⋆ forward error correction (see above) ⋆/ + }; + +
+ +
+QAM parameters +for cable QAM frontend you use the dvb_qam_parameters structure: + + struct dvb_qam_parameters { + uint32_t symbol_rate; /⋆ symbol rate in Symbols per second ⋆/ + fe_code_rate_t fec_inner; /⋆ forward error correction (see above) ⋆/ + fe_modulation_t modulation; /⋆ modulation type (see above) ⋆/ + }; + +
+ +
+VSB parameters +ATSC frontends are supported by the dvb_vsb_parameters structure: + +struct dvb_vsb_parameters { + fe_modulation_t modulation; /⋆ modulation type (see above) ⋆/ +}; + +
+ +
+OFDM parameters +DVB-T frontends are supported by the dvb_ofdm_parameters structure: + + struct dvb_ofdm_parameters { + fe_bandwidth_t bandwidth; + fe_code_rate_t code_rate_HP; /⋆ high priority stream code rate ⋆/ + fe_code_rate_t code_rate_LP; /⋆ low priority stream code rate ⋆/ + fe_modulation_t constellation; /⋆ modulation type (see above) ⋆/ + fe_transmit_mode_t transmission_mode; + fe_guard_interval_t guard_interval; + fe_hierarchy_t hierarchy_information; + }; + +
+
+ +
+frontend events + + struct dvb_frontend_event { + fe_status_t status; + struct dvb_frontend_parameters parameters; + }; + +
+
+ +
+Frontend Legacy Function Calls + +Those functions are defined at DVB version 3. The support is kept in + the kernel due to compatibility issues only. Their usage is strongly + not recommended + +
+FE_READ_BER +DESCRIPTION + + +This ioctl call returns the bit error rate for the signal currently + received/demodulated by the front-end. For this command, read-only access to + the device is sufficient. + + +SYNOPSIS + + +int ioctl(int fd, int request = FE_READ_BER, + uint32_t ⋆ber); + + +PARAMETERS + + +int fd + +File descriptor returned by a previous call to open(). + + +int request + +Equals FE_READ_BER for this command. + + +uint32_t *ber + +The bit error rate is stored into *ber. + + + +&return-value-dvb; +
+ +
+FE_READ_SNR + +DESCRIPTION + + +This ioctl call returns the signal-to-noise ratio for the signal currently received + by the front-end. For this command, read-only access to the device is sufficient. + + +SYNOPSIS + + +int ioctl(int fd, int request = FE_READ_SNR, uint16_t + ⋆snr); + + +PARAMETERS + + +int fd + +File descriptor returned by a previous call to open(). + + +int request + +Equals FE_READ_SNR for this command. + + +uint16_t *snr + +The signal-to-noise ratio is stored into *snr. + + + +&return-value-dvb; +
+ +
+FE_READ_SIGNAL_STRENGTH +DESCRIPTION + + +This ioctl call returns the signal strength value for the signal currently received + by the front-end. For this command, read-only access to the device is sufficient. + + +SYNOPSIS + + +int ioctl( int fd, int request = + FE_READ_SIGNAL_STRENGTH, uint16_t ⋆strength); + + + +PARAMETERS + + +int fd + +File descriptor returned by a previous call to open(). + + +int request + +Equals FE_READ_SIGNAL_STRENGTH for this + command. + + +uint16_t *strength + +The signal strength value is stored into *strength. + + + +&return-value-dvb; +
+ +
+FE_READ_UNCORRECTED_BLOCKS +DESCRIPTION + + +This ioctl call returns the number of uncorrected blocks detected by the device + driver during its lifetime. For meaningful measurements, the increment in block + count during a specific time interval should be calculated. For this command, + read-only access to the device is sufficient. + + +Note that the counter will wrap to zero after its maximum count has been + reached. + + +SYNOPSIS + + +int ioctl( int fd, int request = + FE_READ_UNCORRECTED_BLOCKS, uint32_t ⋆ublocks); + + +PARAMETERS + + +int fd + +File descriptor returned by a previous call to open(). + + +int request + +Equals FE_READ_UNCORRECTED_BLOCKS for this + command. + + +uint32_t *ublocks + +The total number of uncorrected blocks seen by the driver + so far. + + + +&return-value-dvb; +
+ +
+FE_SET_FRONTEND +DESCRIPTION + + +This ioctl call starts a tuning operation using specified parameters. The result + of this call will be successful if the parameters were valid and the tuning could + be initiated. The result of the tuning operation in itself, however, will arrive + asynchronously as an event (see documentation for FE_GET_EVENT and + FrontendEvent.) If a new FE_SET_FRONTEND operation is initiated before + the previous one was completed, the previous operation will be aborted in favor + of the new one. This command requires read/write access to the device. + + + +SYNOPSIS + + +int ioctl(int fd, int request = FE_SET_FRONTEND, + struct dvb_frontend_parameters ⋆p); + + +PARAMETERS + + +int fd + +File descriptor returned by a previous call to open(). + + +int request + +Equals FE_SET_FRONTEND for this command. + + +struct + dvb_frontend_parameters + *p + +Points to parameters for tuning operation. + + + +&return-value-dvb; + +EINVAL + +Maximum supported symbol rate reached. + + +
+ +
+FE_GET_FRONTEND +DESCRIPTION + + +This ioctl call queries the currently effective frontend parameters. For this + command, read-only access to the device is sufficient. + + + +SYNOPSIS + + +int ioctl(int fd, int request = FE_GET_FRONTEND, + struct dvb_frontend_parameters ⋆p); + + + +PARAMETERS + + +int fd + +File descriptor returned by a previous call to open(). + + +int request + +Equals FE_SET_FRONTEND for this command. + + +struct + dvb_frontend_parameters + *p + +Points to parameters for tuning operation. + + + +&return-value-dvb; + +EINVAL + +Maximum supported symbol rate reached. + + + +
+ +
+FE_GET_EVENT +DESCRIPTION + + +This ioctl call returns a frontend 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. Since the event queue allocated is + rather small (room for 8 events), the queue must be serviced regularly to avoid + overflow. If an overflow happens, the oldest event is discarded from the queue, + and an error (EOVERFLOW) occurs the next time the queue is read. After + reporting the error condition in this fashion, subsequent + FE_GET_EVENT + calls will return events from the queue as usual. + + +For the sake of implementation simplicity, this command requires read/write + access to the device. + + + +SYNOPSIS + + +int ioctl(int fd, int request = QPSK_GET_EVENT, + struct dvb_frontend_event ⋆ev); + + + +PARAMETERS + + +int fd + +File descriptor returned by a previous call to open(). + + +int request + +Equals FE_GET_EVENT for this command. + + +struct + dvb_frontend_event + *ev + +Points to the location where the event, + + + +if any, is to be stored. + + + +&return-value-dvb; + +EWOULDBLOCK + +There is no event pending, and the device is in + non-blocking mode. + + +EOVERFLOW + +Overflow in event queue - one or more events were lost. + + +
+ +
+ FE_DISHNETWORK_SEND_LEGACY_CMD +DESCRIPTION + + +WARNING: This is a very obscure legacy command, used only at stv0299 driver. Should not be used on newer drivers. +It provides a non-standard method for selecting Diseqc voltage on the frontend, for Dish Network legacy switches. +As support for this ioctl were added in 2004, this means that such dishes were already legacy in 2004. + + + +SYNOPSIS + + +int ioctl(int fd, int request = + FE_DISHNETWORK_SEND_LEGACY_CMD, unsigned long cmd); + + + +PARAMETERS + + + unsigned long cmd + + + +sends the specified raw cmd to the dish via DISEqC. + + + + +&return-value-dvb; +
+ +