summaryrefslogtreecommitdiff
path: root/cesar/ce/rx/bitloading/inc/bitloading.h
blob: 42e970cd938a0c61bd181ee0cf20901cb718ece6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
#ifndef ce_rx_bitloading_inc_bitloading_h
#define ce_rx_bitloading_inc_bitloading_h
/* Cesar project {{{
 *
 * Copyright (C) 2010 Spidcom
 *
 * <<<Licence>>>
 *
 * }}} */
/**
 * \file    ce/rx/bitloading/inc/bitloading.h
 * \brief   Functions to compute tone map using TNS algorithms.
 * \ingroup ce_rx_bl
 *
 * This header declares functions used to compute and optimize tone maps using
 * the TNS algorithms. Those functions are used by the bit loading initial and
 * iterative.
 */

#include "ce/rx/bitloading/bitloading.h"

#include "mac/common/tonemap.h"
#include "mac/common/tonemask.h"

/**
 * Structure for the table to sort carriers with lowest BER impact.
 * This table will contains all the theoretical BER that respect the BER
 * consign and the impact when increasing of one modulation on theoretical
 * BER.
 */
typedef struct ce_rx_bl_ber_impact_t
{
    /**
     * Index of the carrier.
     */
    u16 carrier_index;
    /**
     * BER theoretical of the modulation that respect BER consign.
     */
    u64 ber_lower;
    /**
     * Impact on BER when increasing modulation to the next upper one.
     */
    u32 ber_diff;
} ce_rx_bl_ber_impact_t;

BEGIN_DECLS

/**
 * Compare two values.
 * \param  table  optimization table.
 * \param  p1  first position to compare.
 * \param  p2  second position to compare.
 * \return  true if p1 < p2.
 */
static inline bool
ce_rx_bl_ber_impact_compare (ce_rx_bl_ber_impact_t *table, uint p1, uint p2)
{
    /* Check parameter. */
    dbg_assert (table);

    if (table[p1].ber_diff < table[p2].ber_diff)
        return true;
    return false;
}

/**
 * Swap two values.
 * \param  table  optimization table.
 * \param  p1  first index to swap.
 * \param  p2  second index to swap.
 */
static inline void
ce_rx_bl_ber_impact_swap (ce_rx_bl_ber_impact_t *table, uint p1, uint p2)
{
    /* Check parameter. */
    dbg_assert (table);

    XCH (table[p1], table[p2]);
}

/**
 * Sort optimization table to increase carrier with lowest BER impact.
 * \param  opti_table  the optimization table to sort.
 * \param  size  the size of the opti_table.
 */
void
ce_rx_bl_sort_optimization (ce_rx_bl_ber_impact_t *opti_table, uint size);

/**
 * Set a tone map under a BER consign.
 * \param  ber_pt  BER consign to respect.
 * \param  tonemask  the tone mask context.
 * \param  bl  the bit loading context.
 * \param  tm  tone map initial generated (non-optimized version).
 * \param  opti_table  the optimization table (required to optimize the tone
 * \param  tone_en  tone enabled count (active but not 0).
 * map).
 * \return  the sum of theoretical BER for the generated tone map (based on
 * the ber_lower) pondered by the modulation (Q49U64).
 *
 * For each tone, this function will find the modulation which respect the BER
 * consign. In consequence, the tone map will always be under the BER consign.
 * In contrast, \sa ce_rx_bl_update_tone_map_at_ber_consign
 * will update the tone map at BER consign.
 *
 * It also generates an non-sorted optimization table (for next step, to
 * improve BER to reach BER consign).
 */
u64
ce_rx_bl_update_tone_map_under_ber_consign (u64 ber_pt,
                                            tonemask_info_t *tonemask,
                                            ce_rx_bitloading_t *bl,
                                            tonemap_t *tm,
                                            ce_rx_bl_ber_impact_t *opti_table,
                                            uint *tone_en);

/**
 * Update a tone map to reach a BER consign.
 * \param  ber_pt  BER consign to respect.
 * \param  tonemask  the tone mask context.
 * \param  bl  the bit loading context.
 * \param  tm  tone map initial generated (non-iterative version).
 * \param  opti  the optimization table.
 * \param  ber_weighted_sum_q49  the sum of theoretical BER pondered by
 * modulation for the tone map (Q49U64)
 * \param  tone_en  tone enabled count (active but not 0).
 * \param  opti_failed  set to true if not possible to optimize tone map,
 * false otherwise
 * \return  The position of the cursor in the optimization table.
 *
 * This function updates a tone map to make it perfectly respect the BER
 * consign (or just under).
 */
u16
ce_rx_bl_update_tone_map_at_ber_consign (u64 ber_pt,
                                         tonemask_info_t *tonemask,
                                         ce_rx_bitloading_t *bl,
                                         tonemap_t *tm,
                                         ce_rx_bl_ber_impact_t *opti,
                                         u64 *ber_weighted_sum_q49,
                                         uint *tone_en,
                                         bool *opti_failed);

/**
 * Compute a tone map which iterates on the BER consign.
 * \param  bpt_initial  initial bits per tone (to compute initial BER
 * consign).
 * \param  iteration_max  maximum number of iteration.
 * \param  tonemask  the tone mask context.
 * \param  reducedtm  extra tone mask context used to mask faulty carriers
 * during tonemap generation. Can be the same as tonemask.
 * \param  bl  the bit loading context.
 * \return  the computed tone map or NULL if no tone map computation is
 * possible.
 *
 * This function generates a tone map which respect the BER consign, based on
 * the bit per tone initial. It re-does this process with a new BER consign,
 * based on the bit per tone of the newly generated tone map. Those iterations
 * are repeated until no evolution of the BER consign or the maximum number of
 * iterations is reached.
 *
 * This whole algorithm is done twice, for each FEC rate and only keep the
 * best tone map pondered by the FEC rate.
 */
tonemap_t *
ce_rx_bl_compute_tone_map_iterative (const u64 bpt_initial[PHY_FEC_RATE_NB],
                                     uint iteration_max,
                                     tonemask_info_t *tonemask,
                                     tonemask_info_t *reducedtm,
                                     ce_rx_bitloading_t *bl);

END_DECLS

#endif /* ce_rx_bitloading_inc_bitloading_h */