Coverage Report

Created: 2025-06-15 00:57

/src/cmp_tool/lib/cmp_chunk.h
Line
Count
Source
1
/**
2
 * @file   cmp_chunk.h
3
 * @author Dominik Loidolt (dominik.loidolt@univie.ac.at)
4
 * @date   2024
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 software chunk compression library
17
 * @see Data Compression User Manual PLATO-UVIE-PL-UM-0001
18
 */
19
20
#ifndef CMP_CHUNK_H
21
#define CMP_CHUNK_H
22
23
#include <stddef.h>
24
#include <stdint.h>
25
26
#include "common/cmp_support.h"
27
#include "common/cmp_entity.h"
28
#include "common/cmp_error_list.h"
29
30
/* valid specific compression parameter ranges for chunk compression
31
 * (every parameter except cmp_mode, model_value, lossy_par)
32
 */
33
#define MIN_CHUNK_CMP_PAR 1U
34
#define MAX_CHUNK_CMP_PAR UINT16_MAX /* the compression entity does not allow larger values */
35
36
1.12k
#define ROUND_UP_TO_4(x) ((((x)+3)/4)*4)
37
38
1.12k
#define COMPRESS_CHUNK_BOUND_UNSAFE(chunk_size, num_col) ( \
39
1.12k
  ROUND_UP_TO_4(NON_IMAGETTE_HEADER_SIZE +   \
40
1.12k
          (num_col) * CMP_COLLECTION_FILD_SIZE +  \
41
1.12k
          (chunk_size)        \
42
1.12k
          )           \
43
1.12k
)
44
45
46
/**
47
 * @brief returns the maximum compressed size in a worst case scenario
48
 *
49
 * In case the input data is not compressible
50
 * This macro is primarily useful for compilation-time evaluation
51
 * (stack memory allocation for example)
52
 *
53
 * @note if the number of collections is not know you can use the
54
 *  compress_chunk_cmp_size_bound function
55
 *
56
 * @param chunk_size  size in bytes of the chunk
57
 * @param num_col number of collections in the chunk
58
 *
59
 * @returns maximum compressed size for chunk compression; 0 on error
60
 */
61
62
#define COMPRESS_CHUNK_BOUND(chunk_size, num_col) (         \
63
  (num_col) > 0 &&                \
64
  (num_col) <= CMP_ENTITY_MAX_SIZE/COLLECTION_HDR_SIZE &&       \
65
  (chunk_size) >= COLLECTION_HDR_SIZE * (num_col) &&        \
66
  (chunk_size) <= CMP_ENTITY_MAX_SIZE &&            \
67
  COMPRESS_CHUNK_BOUND_UNSAFE(chunk_size, num_col) <= CMP_ENTITY_MAX_SIZE ? \
68
  COMPRESS_CHUNK_BOUND_UNSAFE(chunk_size, num_col) : 0        \
69
)
70
71
72
/**
73
 * @struct cmp_par
74
 * @brief structure containing all the compression parameters needed for chunk compression
75
 */
76
77
struct cmp_par {
78
  enum cmp_mode cmp_mode;   /**< compression mode parameter */
79
  uint32_t model_value;   /**< model weighting parameter */
80
  uint32_t lossy_par;   /**< lossy compression parameter */
81
82
  uint32_t nc_imagette;   /**< compression parameter for imagette compression */
83
84
  uint32_t s_exp_flags;   /**< compression parameter for short cadence exposure flags data */
85
  uint32_t s_fx;      /**< compression parameter for short cadence normal flux data */
86
  uint32_t s_ncob;    /**< compression parameter for short cadence normal center of brightness data */
87
  uint32_t s_efx;     /**< compression parameter for short cadence extended flux data  */
88
  uint32_t s_ecob;    /**< compression parameter for short cadence extended center of brightness data */
89
90
  uint32_t l_exp_flags;   /**< compression parameter for long cadence exposure flags data */
91
  uint32_t l_fx;      /**< compression parameter for long cadence normal flux data */
92
  uint32_t l_ncob;    /**< compression parameter for long cadence normal center of brightness data */
93
  uint32_t l_efx;     /**< compression parameter for long cadence extended flux data using extended mask */
94
  uint32_t l_ecob;    /**< compression parameter for long cadence extended center of brightness data */
95
  uint32_t l_fx_cob_variance; /**< compression parameter for long cadence flux/COB variance data */
96
97
  uint32_t saturated_imagette;  /**< compression parameter for saturated imagette data */
98
99
  uint32_t nc_offset_mean;    /**< compression parameter for normal camera offset mean data */
100
  uint32_t nc_offset_variance;    /**< compression parameter for normal camera offset variance data */
101
  uint32_t nc_background_mean;    /**< compression parameter for normal camera background mean data */
102
  uint32_t nc_background_variance;  /**< compression parameter for normal camera background variance data */
103
  uint32_t nc_background_outlier_pixels;  /**< compression parameter for normal camera background outlier pixels data */
104
105
  uint32_t smearing_mean;     /**< compression parameter for smearing mean data */
106
  uint32_t smearing_variance_mean;  /**< compression parameter for smearing variance mean data */
107
  uint32_t smearing_outlier_pixels; /**< compression parameter for smearing outlier pixels data */
108
109
  uint32_t fc_imagette;     /**< compression parameter for fast camera imagette data */
110
  uint32_t fc_offset_mean;    /**< compression parameter for fast camera offset mean data */
111
  uint32_t fc_offset_variance;    /**< compression parameter for fast camera offset variance data */
112
  uint32_t fc_background_mean;    /**< compression parameter for fast camera background mean data */
113
  uint32_t fc_background_variance;  /**< compression parameter for fast camera background variance data */
114
  uint32_t fc_background_outlier_pixels;  /**< compression parameter for fast camera background outlier pixels data */
115
};
116
117
118
/**
119
 * @brief returns the maximum compressed size in a worst case scenario
120
 *
121
 * In case the input data is not compressible
122
 * This function is primarily useful for memory allocation purposes
123
 * (destination buffer size).
124
 *
125
 * @note if the number of collections is known you can use the
126
 *  COMPRESS_CHUNK_BOUND macro for compilation-time evaluation
127
 *  (stack memory allocation for example)
128
 *
129
 * @param chunk   pointer to the chunk you want to compress
130
 * @param chunk_size  size of the chunk in bytes
131
 *
132
 * @returns maximum compressed size for a chunk compression on success or an
133
 *  error code if it fails (which can be tested with cmp_is_error())
134
 */
135
136
uint32_t compress_chunk_cmp_size_bound(const void *chunk, size_t chunk_size);
137
138
139
/**
140
 * @brief initialise the compress_chunk() function
141
 *
142
 * If not initialised the compress_chunk() function sets the timestamps and
143
 * version_id in the compression entity header to zero
144
 *
145
 * @param return_timestamp  pointer to a function returning a current 48-bit
146
 *        timestamp
147
 * @param version_id    application software version identifier
148
 */
149
150
void compress_chunk_init(uint64_t (*return_timestamp)(void), uint32_t version_id);
151
152
153
/**
154
 * @brief compress a data chunk consisting of put together data collections
155
 *
156
 * @param chunk     pointer to the chunk to be compressed
157
 * @param chunk_size    byte size of the chunk
158
 * @param chunk_model   pointer to a model of a chunk; has the same size
159
 *        as the chunk (can be NULL if no model compression
160
 *        mode is used)
161
 * @param updated_chunk_model pointer to store the updated model for the next
162
 *        model mode compression; has the same size as the
163
 *        chunk (can be the same as the model_of_data
164
 *        buffer for in-place update or NULL if updated
165
 *        model is not needed)
166
 * @param dst     destination pointer to the compressed data
167
 *        buffer; has to be 4-byte aligned; can be NULL to
168
 *        only get the compressed data size
169
 * @param dst_capacity    capacity of the dst buffer; it's recommended to
170
 *        provide a dst_capacity >=
171
 *        compress_chunk_cmp_size_bound(chunk, chunk_size)
172
 *        as it eliminates one potential failure scenario:
173
 *        not enough space in the dst buffer to write the
174
 *        compressed data; size is internally rounded down
175
 *        to a multiple of 4
176
 * @param cmp_par   pointer to a compression parameters struct
177
 * @returns the byte size of the compressed data or an error code if it
178
 *  fails (which can be tested with cmp_is_error())
179
 */
180
181
uint32_t compress_chunk(const void *chunk, uint32_t chunk_size,
182
      const void *chunk_model, void *updated_chunk_model,
183
      uint32_t *dst, uint32_t dst_capacity,
184
      const struct cmp_par *cmp_par);
185
186
187
/**
188
 * @brief set the model id and model counter in the compression entity header
189
 *
190
 * @param dst   pointer to the compressed data (starting with a
191
 *      compression entity header)
192
 * @param dst_size  byte size of the dst buffer
193
 * @param model_id  model identifier; for identifying entities that originate
194
 *      from the same starting model
195
 * @param model_counter model_counter; counts how many times the model was
196
 *      updated; for non model mode compression use 0
197
 *
198
 * @returns the byte size of the dst buffer (= dst_size) on success or an error
199
 *  code if it fails (which can be tested with cmp_is_error())
200
 */
201
202
uint32_t compress_chunk_set_model_id_and_counter(void *dst, uint32_t dst_size,
203
             uint16_t model_id, uint8_t model_counter);
204
205
206
/**
207
 * @brief tells if a result is an error code
208
 *
209
 * @param code  return value to check
210
 *
211
 * @returns non-zero if the code is an error
212
 */
213
214
unsigned int cmp_is_error(uint32_t code);
215
216
217
/**
218
 * @brief provides a readable string from a compression return value (useful for debugging)
219
 *
220
 * @param code  compression return value to describe
221
 *
222
 * @returns a pointer to a string literal that describes the error code.
223
 */
224
225
const char *cmp_get_error_name(uint32_t code);
226
227
228
/**
229
 * @brief convert a function result into a cmp_error enum
230
 *
231
 * @param code  compression return value to get the error code
232
 *
233
 * @returns error code
234
 */
235
236
enum cmp_error cmp_get_error_code(uint32_t code);
237
238
239
/**
240
 * @brief get a string describing an error code
241
 *
242
 * @param code  the error code to describe, obtain with cmp_get_error_code()
243
 *
244
 * @returns a pointer to a string literal that describes the error code.
245
 */
246
247
const char *cmp_get_error_string(enum cmp_error code);
248
249
250
#endif /* CMP_CHUNK_H */