/src/cmp_tool/lib/common/cmp_support.h
Line | Count | Source |
1 | | /** |
2 | | * @file cmp_support.h |
3 | | * @author Dominik Loidolt (dominik.loidolt@univie.ac.at) |
4 | | * @date 2018 |
5 | | * |
6 | | * @copyright GPLv2 |
7 | | * This program is free software; you can redistribute it and/or modify it |
8 | | * under the terms and conditions of the GNU General Public License, |
9 | | * version 2, as published by the Free Software Foundation. |
10 | | * |
11 | | * This program is distributed in the hope it will be useful, but WITHOUT |
12 | | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
13 | | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for |
14 | | * more details. |
15 | | * |
16 | | * @brief compression/decompression helper functions |
17 | | */ |
18 | | |
19 | | #ifndef CMP_SUPPORT_H |
20 | | #define CMP_SUPPORT_H |
21 | | |
22 | | #include <stdint.h> |
23 | | #include <stddef.h> |
24 | | |
25 | | |
26 | 6.32M | #define CMP_COLLECTION_FILD_SIZE 2 |
27 | | |
28 | | |
29 | | #define CMP_LOSSLESS 0 |
30 | | #define CMP_PAR_UNUNSED 0 |
31 | | |
32 | | /* valid compression parameter ranges for RDCU/ICU imagette compression according to PLATO-UVIE-PL-UM-0001 */ |
33 | | #define MAX_RDCU_CMP_MODE 4U |
34 | 200 | #define MIN_IMA_GOLOMB_PAR 1U |
35 | 3.55k | #define MAX_IMA_GOLOMB_PAR 63U |
36 | 54 | #define MIN_IMA_SPILL 2U |
37 | 18 | #define MAX_RDCU_ROUND 2U |
38 | | /* for maximum spill value look at cmp_rdcu_max_spill function */ |
39 | | |
40 | | /* valid compression parameter ranges for ICU non-imagette compression */ |
41 | 642k | #define MIN_NON_IMA_GOLOMB_PAR 1U |
42 | 665k | #define MAX_NON_IMA_GOLOMB_PAR UINT16_MAX /* the compression entity does not allow larger values */ |
43 | 312k | #define MIN_NON_IMA_SPILL 2U |
44 | | /* for maximum spill value look at cmp_icu_max_spill function */ |
45 | 194k | #define MAX_ICU_ROUND 3U |
46 | | |
47 | | |
48 | | /* default imagette RDCU compression parameters for model compression */ |
49 | | #define CMP_DEF_IMA_MODEL_DATA_TYPE DATA_TYPE_IMAGETTE |
50 | 16 | #define CMP_DEF_IMA_MODEL_CMP_MODE CMP_MODE_MODEL_MULTI |
51 | 16 | #define CMP_DEF_IMA_MODEL_MODEL_VALUE 8 |
52 | 16 | #define CMP_DEF_IMA_MODEL_LOSSY_PAR 0 |
53 | | |
54 | 16 | #define CMP_DEF_IMA_MODEL_GOLOMB_PAR 4 |
55 | 16 | #define CMP_DEF_IMA_MODEL_SPILL_PAR 48 |
56 | 16 | #define CMP_DEF_IMA_MODEL_AP1_GOLOMB_PAR 3 |
57 | 16 | #define CMP_DEF_IMA_MODEL_AP1_SPILL_PAR 35 |
58 | 16 | #define CMP_DEF_IMA_MODEL_AP2_GOLOMB_PAR 5 |
59 | 16 | #define CMP_DEF_IMA_MODEL_AP2_SPILL_PAR 60 |
60 | | |
61 | 32 | #define CMP_DEF_IMA_MODEL_RDCU_DATA_ADR 0x000000 |
62 | 32 | #define CMP_DEF_IMA_MODEL_RDCU_MODEL_ADR 0x200000 |
63 | 32 | #define CMP_DEF_IMA_MODEL_RDCU_UP_MODEL_ADR 0x400000 |
64 | 32 | #define CMP_DEF_IMA_MODEL_RDCU_BUFFER_ADR 0x600000 |
65 | | |
66 | | /* default imagette RDCU compression parameters for 1d-differencing compression */ |
67 | | #define CMP_DEF_IMA_DIFF_DATA_TYPE DATA_TYPE_IMAGETTE |
68 | 2 | #define CMP_DEF_IMA_DIFF_CMP_MODE CMP_MODE_DIFF_ZERO |
69 | 2 | #define CMP_DEF_IMA_DIFF_MODEL_VALUE 8 /* not needed for 1d-differencing cmp_mode */ |
70 | 2 | #define CMP_DEF_IMA_DIFF_LOSSY_PAR 0 |
71 | | |
72 | 2 | #define CMP_DEF_IMA_DIFF_GOLOMB_PAR 7 |
73 | 2 | #define CMP_DEF_IMA_DIFF_SPILL_PAR 60 |
74 | 2 | #define CMP_DEF_IMA_DIFF_AP1_GOLOMB_PAR 6 |
75 | 2 | #define CMP_DEF_IMA_DIFF_AP1_SPILL_PAR 48 |
76 | 2 | #define CMP_DEF_IMA_DIFF_AP2_GOLOMB_PAR 8 |
77 | 2 | #define CMP_DEF_IMA_DIFF_AP2_SPILL_PAR 72 |
78 | | |
79 | 32 | #define CMP_DEF_IMA_DIFF_RDCU_DATA_ADR 0x000000 |
80 | 32 | #define CMP_DEF_IMA_DIFF_RDCU_MODEL_ADR 0x000000 /* not needed for 1d-differencing cmp_mode */ |
81 | 32 | #define CMP_DEF_IMA_DIFF_RDCU_UP_MODEL_ADR 0x000000 /* not needed for 1d-differencing cmp_mode */ |
82 | 32 | #define CMP_DEF_IMA_DIFF_RDCU_BUFFER_ADR 0x600000 |
83 | | |
84 | | |
85 | | /* imagette sample to byte conversion factor; one imagette samples has 16 bits (2 bytes) */ |
86 | 264 | #define IMA_SAM2BYT 2 |
87 | | |
88 | | |
89 | | /** |
90 | | * @brief defined compression data product types |
91 | | */ |
92 | | |
93 | | enum cmp_data_type { |
94 | | DATA_TYPE_UNKNOWN, |
95 | | DATA_TYPE_IMAGETTE, |
96 | | DATA_TYPE_IMAGETTE_ADAPTIVE, |
97 | | DATA_TYPE_SAT_IMAGETTE, |
98 | | DATA_TYPE_SAT_IMAGETTE_ADAPTIVE, |
99 | | DATA_TYPE_OFFSET, |
100 | | DATA_TYPE_BACKGROUND, |
101 | | DATA_TYPE_SMEARING, |
102 | | DATA_TYPE_S_FX, |
103 | | DATA_TYPE_S_FX_EFX, |
104 | | DATA_TYPE_S_FX_NCOB, |
105 | | DATA_TYPE_S_FX_EFX_NCOB_ECOB, |
106 | | DATA_TYPE_L_FX, |
107 | | DATA_TYPE_L_FX_EFX, |
108 | | DATA_TYPE_L_FX_NCOB, |
109 | | DATA_TYPE_L_FX_EFX_NCOB_ECOB, |
110 | | DATA_TYPE_F_FX, |
111 | | DATA_TYPE_F_FX_EFX, |
112 | | DATA_TYPE_F_FX_NCOB, |
113 | | DATA_TYPE_F_FX_EFX_NCOB_ECOB, |
114 | | DATA_TYPE_F_CAM_IMAGETTE, |
115 | | DATA_TYPE_F_CAM_IMAGETTE_ADAPTIVE, |
116 | | DATA_TYPE_F_CAM_OFFSET, |
117 | | DATA_TYPE_F_CAM_BACKGROUND, |
118 | | DATA_TYPE_CHUNK |
119 | | }; |
120 | | |
121 | | |
122 | | /** |
123 | | * @brief compression modes |
124 | | * This enum defines the various compression modes available |
125 | | */ |
126 | | |
127 | | enum cmp_mode { |
128 | | CMP_MODE_RAW, /**< raw compression mode */ |
129 | | CMP_MODE_MODEL_ZERO, /**< model compression mode with zero escape symbol mechanism */ |
130 | | CMP_MODE_DIFF_ZERO, /**< 1-D differential compression mode with zero escape symbol mechanism */ |
131 | | CMP_MODE_MODEL_MULTI, /**< model compression mode with multi escape symbol mechanism */ |
132 | | CMP_MODE_DIFF_MULTI /**< 1-D differential multi compression mode with multi escape symbol mechanism*/ |
133 | | }; |
134 | | |
135 | | |
136 | | /** |
137 | | * @brief The cmp_cfg structure can contain the complete configuration for a SW |
138 | | * (de)compression |
139 | | */ |
140 | | |
141 | | __extension__ |
142 | | struct cmp_cfg { |
143 | | const void *src; /**< Pointer to the source data buffer (data to be compressed for compression; compressed data for decompression) */ |
144 | | void *dst; /**< Pointer to the destination buffer (compressed data for compression; decompressed data for decompression) */ |
145 | | const void *model_buf; /**< Pointer to the model buffer */ |
146 | | void *updated_model_buf; /**< Pointer to the updated model buffer */ |
147 | | uint32_t samples; /**< Number of samples in a collection, length of the data and model buffers */ |
148 | | uint32_t stream_size; /**< Length of the compressed data buffer in number of samples */ |
149 | | enum cmp_data_type data_type; /**< Compression Data Product Type */ |
150 | | enum cmp_mode cmp_mode; /**< 0: raw mode |
151 | | * 1: model mode with zero escape symbol mechanism |
152 | | * 2: 1d differencing mode without input model with zero escape symbol mechanism |
153 | | * 3: model mode with multi escape symbol mechanism |
154 | | * 4: 1d differencing mode without input model multi escape symbol mechanism |
155 | | */ |
156 | | uint32_t model_value; /**< Model weighting parameter */ |
157 | | uint32_t round; /**< lossy compression parameter */ |
158 | | union { |
159 | | uint32_t cmp_par_1; |
160 | | uint32_t cmp_par_imagette; /**< Golomb parameter for imagette data compression */ |
161 | | uint32_t cmp_par_exp_flags; /**< Compression parameter for exposure flags compression */ |
162 | | }; |
163 | | union { |
164 | | uint32_t spill_par_1; |
165 | | uint32_t spill_imagette; /**< Spillover threshold parameter for imagette data compression */ |
166 | | uint32_t spill_exp_flags; /**< Spillover threshold parameter for exposure flags compression */ |
167 | | }; |
168 | | |
169 | | union { |
170 | | uint32_t cmp_par_2; |
171 | | uint32_t cmp_par_fx; /**< Compression parameter for normal flux compression */ |
172 | | uint32_t cmp_par_offset_mean; /**< Compression parameter for auxiliary science mean compression */ |
173 | | }; |
174 | | union { |
175 | | uint32_t spill_par_2; |
176 | | uint32_t spill_fx; /**< Spillover threshold parameter for normal flux compression */ |
177 | | uint32_t spill_offset_mean; /**< Spillover threshold parameter for auxiliary science mean compression */ |
178 | | }; |
179 | | |
180 | | union { |
181 | | uint32_t cmp_par_3; |
182 | | uint32_t cmp_par_ncob; /**< Compression parameter for normal center of brightness compression */ |
183 | | uint32_t cmp_par_offset_variance; /**< Compression parameter for auxiliary science variance compression */ |
184 | | }; |
185 | | union { |
186 | | uint32_t spill_par_3; |
187 | | uint32_t spill_ncob; /**< Spillover threshold parameter for normal center of brightness compression */ |
188 | | uint32_t spill_offset_variance; /**< Spillover threshold parameter for auxiliary science variance compression */ |
189 | | }; |
190 | | |
191 | | union { |
192 | | uint32_t cmp_par_4; |
193 | | uint32_t cmp_par_efx; /**< Compression parameter for extended flux compression */ |
194 | | uint32_t cmp_par_background_mean; /**< Compression parameter for auxiliary science mean compression */ |
195 | | uint32_t cmp_par_smearing_mean; /**< Compression parameter for auxiliary science mean compression */ |
196 | | }; |
197 | | union { |
198 | | uint32_t spill_par_4; |
199 | | uint32_t spill_efx; /**< Spillover threshold parameter for extended flux compression */ |
200 | | uint32_t spill_background_mean; /**< Spillover threshold parameter for auxiliary science mean compression */ |
201 | | uint32_t spill_smearing_mean; /**< Spillover threshold parameter for auxiliary science mean compression */ |
202 | | }; |
203 | | |
204 | | union { |
205 | | uint32_t cmp_par_5; |
206 | | uint32_t cmp_par_ecob; /**< Compression parameter for extended center of brightness compression */ |
207 | | uint32_t cmp_par_background_variance; /**< Compression parameter for auxiliary science variance compression */ |
208 | | uint32_t cmp_par_smearing_variance; /**< Compression parameter for auxiliary science variance compression */ |
209 | | }; |
210 | | union { |
211 | | uint32_t spill_par_5; |
212 | | uint32_t spill_ecob; /**< Spillover threshold parameter for extended center of brightness compression */ |
213 | | uint32_t spill_background_variance; /**< Spillover threshold parameter for auxiliary science variance compression */ |
214 | | uint32_t spill_smearing_variance; /**< Spillover threshold parameter for auxiliary science variance compression */ |
215 | | }; |
216 | | |
217 | | union { |
218 | | uint32_t cmp_par_6; |
219 | | uint32_t cmp_par_fx_cob_variance; /**< Compression parameter for flux/COB variance compression */ |
220 | | uint32_t cmp_par_background_pixels_error; /**< Compression parameter for auxiliary science outlier pixels number compression */ |
221 | | uint32_t cmp_par_smearing_pixels_error; /**< Compression parameter for auxiliary science outlier pixels number compression */ |
222 | | }; |
223 | | union { |
224 | | uint32_t spill_par_6; |
225 | | uint32_t spill_fx_cob_variance; /**< Spillover threshold parameter for flux/COB variance compression */ |
226 | | uint32_t spill_background_pixels_error; /**< Spillover threshold parameter for auxiliary science outlier pixels number compression */ |
227 | | uint32_t spill_smearing_pixels_error; /**< Spillover threshold parameter for auxiliary science outlier pixels number compression */ |
228 | | }; |
229 | | }; |
230 | | |
231 | | |
232 | | /** |
233 | | * @brief RDCU configuration structure, can contain the information of the |
234 | | * RDCU configuration registers |
235 | | */ |
236 | | |
237 | | struct rdcu_cfg { |
238 | | uint16_t *input_buf; /**< Pointer to the data to compress buffer */ |
239 | | uint16_t *model_buf; /**< Pointer to the model buffer */ |
240 | | uint16_t *icu_new_model_buf; /**< Pointer to the updated model buffer */ |
241 | | uint32_t *icu_output_buf; /**< Pointer to the compressed data buffer */ |
242 | | uint32_t samples; /**< Number of 16-bit samples to compress, length of the data and model buffer */ |
243 | | uint32_t buffer_length; /**< Length of the compressed data buffer in number of samples */ |
244 | | uint32_t rdcu_data_adr; /**< RDCU data to compress start address, the first data address in the RDCU SRAM; HW only */ |
245 | | uint32_t rdcu_model_adr; /**< RDCU model start address, the first model address in the RDCU SRAM; HW only */ |
246 | | uint32_t rdcu_new_model_adr; /**< RDCU updated model start address, the address in the RDCU SRAM where the updated model is stored; HW only */ |
247 | | uint32_t rdcu_buffer_adr; /**< RDCU compressed data start address, the first output data address in the RDCU SRAM; HW only */ |
248 | | enum cmp_mode cmp_mode; /**< compression mode */ |
249 | | uint32_t model_value; /**< Model weighting parameter */ |
250 | | uint32_t round; /**< lossy compression parameter */ |
251 | | uint32_t golomb_par; /**< Golomb parameter for imagette data compression */ |
252 | | uint32_t spill; /**< Spillover threshold parameter for imagette data compression */ |
253 | | uint32_t ap1_golomb_par; /**< Adaptive 2 spillover threshold for imagette data; HW only */ |
254 | | uint32_t ap1_spill; /**< Adaptive 2 Golomb parameter; HW only */ |
255 | | uint32_t ap2_golomb_par; /**< Adaptive 2 spillover threshold for imagette data; HW only */ |
256 | | uint32_t ap2_spill; /**< Adaptive 2 Golomb parameter; HW only */ |
257 | | }; |
258 | | |
259 | | |
260 | | /** |
261 | | * @brief The cmp_status structure can contain the information of the compressor |
262 | | * status register from the RDCU |
263 | | * @see RDCU-FRS-FN-0632 |
264 | | */ |
265 | | |
266 | | struct cmp_status { |
267 | | uint8_t cmp_ready; /**< Data Compressor Ready; 0: Compressor is busy 1: Compressor is ready */ |
268 | | uint8_t cmp_active; /**< Data Compressor Active; 0: Compressor is on hold; 1: Compressor is active */ |
269 | | uint8_t data_valid; /**< Compressor Data Valid; 0: Data is invalid; 1: Data is valid */ |
270 | | uint8_t cmp_interrupted; /**< Data Compressor Interrupted; HW only; 0: No compressor interruption; 1: Compressor was interrupted */ |
271 | | uint8_t rdcu_interrupt_en; /**< RDCU Interrupt Enable; HW only; 0: Interrupt is disabled; 1: Interrupt is enabled */ |
272 | | }; |
273 | | |
274 | | |
275 | | /** |
276 | | * @brief The cmp_info structure contains the information and metadata of an |
277 | | * executed RDCU compression. |
278 | | */ |
279 | | |
280 | | struct cmp_info { |
281 | | uint32_t cmp_mode_used; /**< Compression mode used */ |
282 | | uint32_t spill_used; /**< Spillover threshold used */ |
283 | | uint32_t golomb_par_used; /**< Golomb parameter used */ |
284 | | uint32_t samples_used; /**< Number of samples (16-bit value) to be stored */ |
285 | | uint32_t cmp_size; /**< Compressed data size; measured in bits */ |
286 | | uint32_t ap1_cmp_size; /**< Adaptive compressed data size 1; measured in bits */ |
287 | | uint32_t ap2_cmp_size; /**< Adaptive compressed data size 2; measured in bits */ |
288 | | uint32_t rdcu_new_model_adr_used; /**< Updated model start address used */ |
289 | | uint32_t rdcu_cmp_adr_used; /**< Compressed data start address */ |
290 | | uint8_t model_value_used; /**< Model weighting parameter used */ |
291 | | uint8_t round_used; /**< Number of noise bits to be rounded used */ |
292 | | uint16_t cmp_err; /**< Compressor errors |
293 | | * [bit 0] small_buffer_err; The length for the compressed data buffer is too small |
294 | | * [bit 1] cmp_mode_err; The cmp_mode parameter is not set correctly |
295 | | * [bit 2] model_value_err; The model_value parameter is not set correctly |
296 | | * [bit 3] cmp_par_err; The spill, golomb_par combination is not set correctly |
297 | | * [bit 4] ap1_cmp_par_err; The ap1_spill, ap1_golomb_par combination is not set correctly (only HW compression) |
298 | | * [bit 5] ap2_cmp_par_err; The ap2_spill, ap2_golomb_par combination is not set correctly (only HW compression) |
299 | | * [bit 6] mb_err; Multi bit error detected by the memory controller (only HW compression) |
300 | | * [bit 7] slave_busy_err; The bus master has received the "slave busy" status (only HW compression) |
301 | | * [bit 8] slave_blocked_err; The bus master has received the “slave blocked” status (only HW compression) |
302 | | * [bit 9] invalid address_err; The bus master has received the “invalid address” status (only HW compression) |
303 | | */ |
304 | | }; |
305 | | |
306 | | |
307 | | /** |
308 | | * @brief structure containing flux/COB compression parameters pairs for the |
309 | | * cmp_cfg_fx_cob_get_need_pars() function |
310 | | */ |
311 | | |
312 | | struct fx_cob_par { |
313 | | uint8_t exp_flags; |
314 | | uint8_t fx; |
315 | | uint8_t ncob; |
316 | | uint8_t efx; |
317 | | uint8_t ecob; |
318 | | uint8_t fx_cob_variance; |
319 | | }; |
320 | | |
321 | | |
322 | | int is_a_pow_of_2(unsigned int v); |
323 | | unsigned int ilog_2(uint32_t x); |
324 | | unsigned int cmp_bit_to_byte(unsigned int cmp_size_bit); |
325 | | |
326 | | int cmp_cfg_gen_par_is_invalid(const struct cmp_cfg *cfg); |
327 | | int cmp_cfg_imagette_is_invalid(const struct cmp_cfg *cfg); |
328 | | int cmp_cfg_fx_cob_is_invalid(const struct cmp_cfg *cfg); |
329 | | int cmp_cfg_aux_is_invalid(const struct cmp_cfg *cfg); |
330 | | uint32_t cmp_ima_max_spill(unsigned int golomb_par); |
331 | | uint32_t cmp_icu_max_spill(unsigned int cmp_par); |
332 | | |
333 | | int cmp_data_type_is_invalid(enum cmp_data_type data_type); |
334 | | int rdcu_supported_data_type_is_used(enum cmp_data_type data_type); |
335 | | int cmp_imagette_data_type_is_used(enum cmp_data_type data_type); |
336 | | int cmp_ap_imagette_data_type_is_used(enum cmp_data_type data_type); |
337 | | int cmp_fx_cob_data_type_is_used(enum cmp_data_type data_type); |
338 | | int cmp_cfg_fx_cob_get_need_pars(enum cmp_data_type data_type, struct fx_cob_par *par); |
339 | | int cmp_aux_data_type_is_used(enum cmp_data_type data_type); |
340 | | |
341 | | int cmp_mode_is_supported(enum cmp_mode cmp_mode); |
342 | | int model_mode_is_used(enum cmp_mode cmp_mode); |
343 | | int raw_mode_is_used(enum cmp_mode cmp_mode); |
344 | | int zero_escape_mech_is_used(enum cmp_mode cmp_mode); |
345 | | int multi_escape_mech_is_used(enum cmp_mode cmp_mode); |
346 | | |
347 | | |
348 | | void print_cmp_info(const struct cmp_info *info); |
349 | | |
350 | | #endif /* CMP_SUPPORT_H */ |