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