GNU Radio's DVBS2RX Package
plsync_cc.h
Go to the documentation of this file.
1/* -*- c++ -*- */
2/*
3 * Copyright (c) 2019-2021 Igor Freire.
4 *
5 * This file is part of gr-dvbs2rx.
6 *
7 * SPDX-License-Identifier: GPL-3.0-or-later
8 */
9
10#ifndef INCLUDED_DVBS2RX_PLSYNC_CC_H
11#define INCLUDED_DVBS2RX_PLSYNC_CC_H
12
13#include <gnuradio/block.h>
15
16namespace gr {
17namespace dvbs2rx {
18
19/*!
20 * \brief DVB-S2 Physical Layer (PL) Synchronizer
21 * \ingroup dvbs2rx
22 *
23 * \details
24 *
25 * This block finds DVB-S2 PLFRAMEs on the input symbol-spaced IQ stream and outputs the
26 * corresponding XFECFRAMEs towards a downstream constellation de-mapper block.
27 * Internally, it implements PL frame timing recovery, coarse and fine frequency offset
28 * estimation, carrier phase tracking, PLSC decoding, and PL descrambling. Furthermore, it
29 * manages frequency corrections carried out by an external rotator block connected via a
30 * message port.
31 *
32 * This block can also filter PLFRAMEs based on target PL signaling (PLS) values. In
33 * constant coding and modulation (CCM) mode, the PLS filter must specify a single option
34 * (i.e., a single MODCOD, frame size, and pilot configuration). In contrast, in adaptive
35 * or variable coding and modulation (ACM/VCM) mode, the filter can be configured to allow
36 * multiple PLS values, including all of them. In this case, since the output XFECFRAMEs
37 * can vary in length and format, this block tags the first sample of each output
38 * XFECFRAME with the frame's PLS information.
39 */
40class DVBS2RX_API plsync_cc : virtual public gr::block
41{
42public:
43 typedef std::shared_ptr<plsync_cc> sptr;
44
45 /*!
46 * \brief Make physical layer deframer block.
47 *
48 * \param gold_code (int) Gold code used for physical layer scrambling.
49 * \param freq_est_period (int) Freq. offset estimation period in frames.
50 * \param sps (double) Oversampling ratio at the input to the upstream MF.
51 * \param debug_level (int) Debug level.
52 * \param acm_vcm (bool) Whether running in ACM/VCM mode. Determines whether the PLS
53 * filter can include multiple options.
54 * \param multistream (bool) Whether the input signal carries multiple MPEG transport
55 * streams (MIS mode). Determines whether dummy PLFRAMEs are expected in the received
56 * signal, even if operating in CCM mode (refer to Table D.2 of the standard).
57 * \param pls_filter_lo (uint64_t) Lower 64 bits of the PLS filter bitmask. A value of
58 * 1 in the n-th position indicates PLS "n" (for n in 0 to 63) should be enabled.
59 * \param pls_filter_hi (uint64_t) Upper 64 bits of the PLS filter bitmask. A value of
60 * 1 in the n-th position indicates PLS "n" (for n in 64 to 127) should be enabled.
61 *
62 * \note When `acm_vcm=false`, the constructor throws an exception if `pls_filter_lo`
63 * and `pls_filter_hi` collectively select more than one PLS value (i.e., if their
64 * aggregate population count is greater than one).
65 *
66 * \note The oversampling ratio (sps) parameter is only used to schedule phase
67 * increment updates (i.e., frequency corrections) to an external rotator. This block
68 * attempts to schedule frequency corrections at the start of PLFRAMEs. Nevertheless,
69 * while this block processes a symbol-spaced IQ stream, it assumes the external
70 * rotator lies before the matched filter (MF) and, as such, processes a
71 * fractionally-spaced IQ stream. Hence, when scheduling a frequency correction, this
72 * block uses the sps paramter to adjust the symbol-spaced sample offset of a PLFRAME
73 * to the corresponding fractionally-spaced offset in the rotator's input.
74 */
75 static sptr make(int gold_code,
76 int freq_est_period,
77 double sps,
78 int debug_level,
79 bool acm_vcm,
80 bool multistream,
81 uint64_t pls_filter_lo,
82 uint64_t pls_filter_hi);
83
84 /*!
85 * \brief Get the current frequency offset estimate.
86 * \return (float) Frequency offset.
87 */
88 virtual float get_freq_offset() = 0;
89
90 /*!
91 * \brief Get the coarse frequency offset correction state.
92 * \return (bool) True when the frequency offset is coarsely corrected.
93 */
94 virtual bool get_coarse_freq_corr_state() = 0;
95
96 /*!
97 * \brief Get the current lock status.
98 * \return (bool) True when the frame synchronizer is locked.
99 */
100 virtual bool get_locked() = 0;
101
102 /*!
103 * \brief Get the current count of detected start-of-frame (SOF) instants.
104 *
105 * This count includes all detected SOFs, including false positives. Note that
106 * detecting a SOF does not mean that instant will lead to a processed frame. Frames
107 * are only processed after frame timing lock, which requires two consecutive SOFs
108 * detected with the correct interval between them. Hence, the SOF count is always
109 * greater than or equal to the processed frame count.
110 *
111 * \return (uint64_t) Detected SOF count.
112 */
113 virtual uint64_t get_sof_count() = 0;
114
115 /*!
116 * \brief Get the current count of processed (accepted) PLFRAMEs.
117 *
118 * A PLFRAME is processed after frame timing lock and after being accepted by the PLS
119 * filter, in which case its XFECFRAME is output to the next block. Frames rejected by
120 * the PLS filter and dummy frames are not included in this count.
121 *
122 * \return (uint64_t) Processed frame count.
123 */
124 virtual uint64_t get_frame_count() = 0;
125
126 /*!
127 * \brief Get the current count of rejected PLFRAMEs.
128 * \return (uint64_t) Rejected frame count.
129 */
130 virtual uint64_t get_rejected_count() = 0;
131
132 /*!
133 * \brief Get the current count of received dummy PLFRAMEs.
134 * \return (uint64_t) Dummy frame count.
135 */
136 virtual uint64_t get_dummy_count() = 0;
137
138 /*!
139 * \brief Get the timestamp of the last frame synchronization lock.
140 * \return (std::chrono::system_clock::time_point) Last frame lock timestamp in UTC.
141 * \note The timestamp is only valid after the first frame lock.
142 */
143 virtual std::chrono::system_clock::time_point get_lock_time() = 0;
144};
145
146} // namespace dvbs2rx
147} // namespace gr
148
149#endif /* INCLUDED_DVBS2RX_PLSYNC_CC_H */
DVB-S2 Physical Layer (PL) Synchronizer.
Definition plsync_cc.h:41
virtual std::chrono::system_clock::time_point get_lock_time()=0
Get the timestamp of the last frame synchronization lock.
virtual uint64_t get_frame_count()=0
Get the current count of processed (accepted) PLFRAMEs.
virtual bool get_coarse_freq_corr_state()=0
Get the coarse frequency offset correction state.
virtual bool get_locked()=0
Get the current lock status.
virtual float get_freq_offset()=0
Get the current frequency offset estimate.
virtual uint64_t get_dummy_count()=0
Get the current count of received dummy PLFRAMEs.
virtual uint64_t get_sof_count()=0
Get the current count of detected start-of-frame (SOF) instants.
virtual uint64_t get_rejected_count()=0
Get the current count of rejected PLFRAMEs.
static sptr make(int gold_code, int freq_est_period, double sps, int debug_level, bool acm_vcm, bool multistream, uint64_t pls_filter_lo, uint64_t pls_filter_hi)
Make physical layer deframer block.
std::shared_ptr< plsync_cc > sptr
Definition plsync_cc.h:43
#define DVBS2RX_API
Definition include/gnuradio/dvbs2rx/api.h:19
Fixed-length double-ended queue with contiguous volk-aligned elements.
Definition gr_bch.h:22