Coverage Report

Created: 2025-06-15 00:57

/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 */